Interop

لمحة سريعة

يوفّر ⁨NextPDF Pro⁩ مجموعة مُصدَّرة من كائنات نقل بيانات النتائج (⁨DTOs⁩) التي تُسلسِل مخرَج تحليل ⁨PDF⁩ — معلومات المستند، والصفحات، وكتل النص، والتجزئة، وبيانات النماذج — إلى شكل ⁨JSON⁩ مستقر ومُقفَل المخطّط للاستهلاك من قِبل الأنظمة والأدوات الخارجية.

التوفّر والترخيص

تتوفّر هذه الإمكانية في ⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بمظروف ترخيص من طبقة ⁨Pro⁩. النشر الذي يفتقر إلى ذلك الاستحقاق لا يُحمِّل أصناف الإمكانية. ⁨Interop⁩ جزء من إصدار ⁨Pro⁩؛ ولا يوجد علم ترخيص منفصل لكل ميزة. ‏قارن الإصدارات واحصل على ترخيص.

التثبيت

composer require nextpdf/pro:^3

نظرة مفاهيمية عامة

عندما يعبر مخرَج معالجة ⁨PDF⁩ حدّ عملية أو خدمة، يحتاج المُستقبِل إلى عقد مستقر. يوفّر سطح ⁨Interop V1⁩ ذلك:

• InteropResultInterface — ينفّذ هذا كلُّ كائن نقل بيانات نتائج. يُسلسِل كلٌّ منها إلى مصفوفة آمنة لـ ⁨JSON⁩ تحمل دائمًا مفتاح schema_version، وإلى سلسلة ⁨JSON.⁩
• كائنات نقل بيانات النتائج — DocumentInfo وPageInfo وBoundingBox، وExtractedText / ExtractedPage / TextBlock، وDocumentSegmentation / Segment، وFormData / FormField. كلٌّ منها رؤية غير قابلة للتغيير لنتيجة تحليل واحدة.
• SchemaLock — حارس تكامل مستمر. يحمل ⁨SHA-256⁩ للمخطّط المُجمَّد ويُفشِل البناء إذا تغيّر ملف المخطّط دون رفع نسخة مقابل، بحيث لا ينحرف عقد السلك بصمت.

سطح ⁨Interop⁩ مُصدَّر صراحةً (SCHEMA_VERSION). عامِله بوصفه عقد ⁨API⁩ عامًا: التغييرات الإضافية ترفع المخطّط؛ والتغييرات الكاسرة تتطلّب نسخة رئيسية جديدة.

لماذا يعمل بهذه الطريقة

يُعامَل شكل التسلسل بوصفه عقد ⁨API⁩ عامًا، لا تفصيلًا تنفيذيًا. يحمل كلُّ كائن نقل بيانات مفتاح schema_version، فيتفرّع المستهلكون بناءً على الشكل الذي يستقبلونه بدلًا من التخمين. يثبّت SchemaLock قيمة ⁨SHA-256⁩ للمخطّط المُجمَّد في ⁨CI⁩، فلا يمكن أن ينحرف الشكل دون رفع نسخة. هذا ما يتيح للأنظمة الخارجية البناء على ⁨JSON⁩ بأمان: لا يتحرّك العقد إلا حين تتحرّك النسخة. يبقى المخرَج محمولًا — بيانات موثَّقة ومُصدَّرة تملكها، لا شكلًا يتبدّل من تحتك.

خلفية التصميم: ‏نواة مفتوحة، دون احتكار.

سطح الـ ⁨API⁩

الصنف	المسؤولية
InteropResultInterface	عقد التسلسل المشترك.
DocumentInfo, PageInfo, BoundingBox	كائنات نقل بيانات المستند/الصفحة المشتركة.
ExtractedText, ExtractedPage, TextBlock	كائنات نقل بيانات استخراج النص.
DocumentSegmentation, Segment	كائنات نقل بيانات تجزئة المستند.
FormData, FormField	كائنات نقل بيانات النماذج.
SchemaLock	حارس انحراف المخطّط المستمر.

مثال شيفرة — بداية سريعة

$json = $result->toJson(JSON_PRETTY_PRINT);
$array = $result->toArray(); // includes 'schema_version'

مثال شيفرة — إنتاج

use NextPDF\Pro\Interop\V1\SchemaLock;

if (! SchemaLock::verify()) {
    throw new RuntimeException('Interop schema drift detected — version bump required.');
}
$payload = $result->toArray();
$httpClient->postJson($endpoint, $payload);

الحالات الحدّية والمزالق

• يتضمّن toArray() دائمًا schema_version؛ وعلى المستهلكين في المصبّ التفرّع بناءً عليه.
• يُعيد SchemaLock::verify() القيمة false إذا كان ملف المخطّط مفقودًا أو مُعدَّلًا.
• كائنات نقل البيانات رؤى للقراءة فقط؛ وهي لا تُعيد تشغيل التحليل.

الأداء

التسلسل خطّي بحجم رسم النتيجة.

ملاحظات أمنية

تحمل كائنات نقل البيانات مخرَج التحليل الذي تملؤه فقط. لا يحدث أي إدخال/إخراج لنظام الملفات أو الشبكة أثناء التسلسل.

المطابقة

يُعرّف ⁨Interop⁩ مخطّطًا مُصدَّرًا مملوكًا لـ ⁨NextPDF⁩؛ وهو لا ينفّذ معيارًا خارجيًا.

عقد السلوك

• ينفّذ كلُّ كائن نقل بيانات نتائج InteropResultInterface ويُسلسِل إلى مصفوفة آمنة لـ ⁨JSON⁩ تحمل دائمًا مفتاح schema_version، وإلى سلسلة ⁨JSON.⁩
• كائنات نقل بيانات النتائج (DocumentInfo وPageInfo وBoundingBox، وExtractedText/ExtractedPage/TextBlock، وDocumentSegmentation/Segment، وFormData/FormField) رؤى غير قابلة للتغيير للقراءة فقط؛ وهي لا تُعيد تشغيل التحليل.
• يحمل SchemaLock::verify() ⁨SHA-256⁩ للمخطّط المُجمَّد ويُعيد false إذا كان ملف المخطّط مفقودًا أو مُعدَّلًا، بحيث لا ينحرف عقد السلك بصمت.
• السطح مُصدَّر صراحةً (SCHEMA_VERSION): التغييرات الإضافية ترفع المخطّط؛ والتغييرات الكاسرة تتطلّب نسخة رئيسية جديدة.
• لا يحدث أي إدخال/إخراج لنظام الملفات أو الشبكة أثناء التسلسل.

ملاحظة حدود ⁨Enterprise⁩

لا يغيّر ⁨Enterprise⁩ سلوك ⁨Interop.⁩ يضيف ⁨Enterprise⁩ ميزات من طبقة أعلى موثَّقة بشكل منفصل؛ وهي ليست مطلوبة لاستخدام كائنات نقل بيانات النتائج المُصدَّرة.

احتياط ⁨Core⁩ / بديله

لا يوجد مكافئ في ⁨Core⁩ لكائنات نقل بيانات نتائج مُقفَلة المخطّط ومُصدَّرة. هذه إضافة في ⁨Pro.⁩

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح ⁨API⁩ العام المدعوم فقط. أما مسارات فضاءات الأسماء الداخلية، والأصناف المساعدة، وجداول الآليات، وأسماء ملفات أدلة التشغيل، وبادئات التذاكر فخارج النطاق.

انظر أيضًا

• ‏⁨Extraction⁩ — يُنتج نتائج النص والمقاطع.
• ‏⁨Form⁩ — يُنتج نتائج بيانات النماذج.
• ‏⁨Interop⁩ — مرجع متعمّق — مرجع كامل لحقول ⁨DTO⁩.