Pro الإصدار

⁨Interop⁩ — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع على مستوى العقد لـ NextPDF\Pro\Interop\V1. تحتوي الوحدة على أربعة عشر رمزًا عامًا: عقد تسلسل واحد (InteropResultInterface)، وحارس سلامة ⁨CI⁩ واحد (SchemaLock)، وثلاثة ⁨DTOs⁩ نتائج عالية المستوى (ExtractedText وDocumentSegmentation وFormData)، وتسعة كائنات قيمة وتعدادات داعمة. كل ⁨DTO⁩ هو عرض غير قابل للتغيير وقابل للتسلسل إلى ⁨JSON⁩ لنتيجة تحليل واحدة. شكل السلك مُصدَّر ومقفول؛ لا شيء على هذا السطح يُعيد تشغيل التحليل. يوجد العرض الموجّه للمهام على صفحة القدرة.

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

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

لا توجد راية قدرة في وقت التشغيل تُبوِّب هذه الوحدة. الفئات متاحة كلما كان nextpdf/pro مثبّتًا ومرخّصًا.

سطح واجهة ⁨API⁩ العامة

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يُطلق أو يفشل بـ	ملاحظات
`InteropResultInterface`	—	عقد لـ ⁨DTOs⁩ النتائج عالية المستوى؛ يوسّع `JsonSerializable`	—	لا يُطلق استثناءً	`SCHEMA_VERSION` هو السلسلة `'1.0'`.
`InteropResultInterface::toArray()`	لا شيء	يُسلسِل إلى مصفوفة آمنة لـ ⁨JSON⁩ تحمل دائمًا `schema_version`	`array<string, mixed>`	لا يُطلق استثناءً	تُصدر التطبيقات أيضًا مُميِّز `type`.
`InteropResultInterface::toJson()`	`int $flags = 0`	يُرمِّز ناتج `toArray()`؛ تُدمَج `JSON_THROW_ON_ERROR` دائمًا عبر ⁨OR⁩	`string`	`JsonException` عند بيانات غير قابلة للترميز	مرِّر أعلامًا مثل `JSON_PRETTY_PRINT`.
`SchemaLock::verify()`	لا شيء	يُجزِّئ ملف ⁨V1⁩ `schema.json` على القرص ويقارنه بـ ⁨SHA-256⁩ المقفولة	`bool`	لا يُطلق استثناءً	`false` عندما يكون ملف المخطط مفقودًا أو غير قابل للقراءة أو مُعدَّلًا.
`SchemaLock::expectedHash()`	لا شيء	يُعيد التجزئة المقفولة	`string`	لا يُطلق استثناءً	مخرجات تشخيصية لفرز إخفاقات ⁨CI⁩.
`SchemaLock::actualHash()`	لا شيء	يُعيد تجزئة ملف المخطط الحالي	`string`	لا يُطلق استثناءً	تحلّ السلسلتان الحارستان `FILE_NOT_FOUND` / `READ_FAILED` محل التجزئة عند إخفاق الإدخال/الإخراج.
`BoundingBox`	`float $x`، `float $y`، `float $width`، `float $height`	صندوق غير قابل للتغيير بنقاط فضاء المستخدم في ⁨PDF⁩، الأصل في الزاوية السفلية اليسرى	—	لا يُطلق استثناءً	`area()`، `overlaps()`، `toArray()`، `fromArray()`.
`DocumentInfo`	`int $pageCount` بالإضافة إلى ستة حقول بيانات وصفية اختيارية	بيانات وصفية غير قابلة للتغيير للمستند	—	لا يُطلق استثناءً	`fromArray()` يحرس نوع كل حقل؛ الحقول الغائبة ترجع إلى القيم الافتراضية.
`PageInfo`	`int $pageNumber`، `float $width`، `float $height`، `int $rotation = 0`	بيانات وصفية غير قابلة للتغيير للصفحة	—	لا يُطلق استثناءً	`isLandscape()`؛ `fromArray()` يُكرِه السلاسل الرقمية والأعداد العشرية.
`ExtractedText`	`list<ExtractedPage> $pages`، `DocumentInfo $documentInfo`، `float $processingTimeMs = 0.0`	نتيجة استخراج النص للمستند بالكامل	—	`JsonException` من `toJson()` فقط	`page()`، `totalBlockCount()`، `plainText()`، `fromArray()`.
`ExtractedPage`	`PageInfo $pageInfo`، `list<TextBlock> $textBlocks`	حاوية لكل صفحة لكتل النص بترتيب القراءة	—	لا يُطلق استثناءً	`plainText()` يصل محتوى الكتل بمسافات مفردة.
`TextBlock`	`string $content`، `BoundingBox $boundingBox`، `int $pageNumber`، `string $fontName = ''`، `float $fontSize = 0.0`	سلسلة نصية متجاورة ذات موضع محدد	—	لا يُطلق استثناءً	اسم الخط وحجمه بأفضل جهد ممكن (الخط السائد في الكتلة).
`DocumentSegmentation`	`list<Segment> $segments`، `DocumentInfo $documentInfo`، `float $processingTimeMs = 0.0`	نتيجة تجزئة مدركة للتخطيط	—	`JsonException` من `toJson()` فقط	`segmentCount()`، `ofType()`، `onPage()`، `contentSegments()`، `fromArray()`.
`Segment`	`SegmentType $type`، `string $content`، `BoundingBox $boundingBox`، `int $pageNumber`، `float $confidence = 1.0`، `list<Segment> $children = []`	منطقة صفحة مُصنَّفة؛ الأبناء يتداخلون تكراريًا	—	لا يُطلق استثناءً	عتبة `isHighConfidence()` هي 0.8؛ `descendantCount()` تكرارية.
`SegmentType`	تعداد مدعوم بسلسلة نصية	اثنتا عشرة حالة، من `heading` إلى `unknown`	—	لا يُطلق استثناءً	`isContent()` و`isStructural()` يقسّمان الحالات.
`FormData`	`list<FormField> $fields`، `DocumentInfo $documentInfo`، `float $processingTimeMs = 0.0`	نتيجة استخراج النماذج للمستند بالكامل	—	`JsonException` من `toJson()` فقط	`field()`، `dataFields()`، `filledCount()`، `toKeyValueMap()`، `fromArray()`.
`FormField`	`string $name`، `FormFieldType $type`، بالإضافة إلى ستة حقول اختيارية	حقل نموذج مستخرج مفرد	—	لا يُطلق استثناءً	`isFilled()` هو `value !== ''`.
`FormFieldType`	تعداد مدعوم بسلسلة نصية	ثماني حالات، من `text` إلى `button`	—	لا يُطلق استثناءً	`isDataField()` هو `false` لـ `button` و`signature`.

interface InteropResultInterface extends JsonSerializable

public const SCHEMA_VERSION = '1.0';

public function toArray(): array;

public function toJson(int $flags = 0): string;

final class SchemaLock

public static function verify(): bool

public static function expectedHash(): string

public static function actualHash(): string

final readonly class ExtractedText implements InteropResultInterface

public function __construct(
    public array $pages,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function page(int $pageNumber): ?ExtractedPage

public function totalBlockCount(): int

public function plainText(): string

public static function fromArray(array $data): self

final readonly class DocumentSegmentation implements InteropResultInterface

public function __construct(
    public array $segments,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function ofType(SegmentType $type): array

public function onPage(int $pageNumber): array

public function contentSegments(): array

public static function fromArray(array $data): self

final readonly class FormData implements InteropResultInterface

public function __construct(
    public array $fields,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function field(string $name): ?FormField

public function dataFields(): array

public function toKeyValueMap(): array

public static function fromArray(array $data): self

عقد السلوك

مظروف مُصدَّر. كل ⁨DTO⁩ عالي المستوى (ExtractedText وDocumentSegmentation وFormData) يُنفِّذ InteropResultInterface. يحمل ناتج toArray() الخاص به دائمًا schema_version ('1.0') ومُميِّز type: extracted_text أو document_segmentation أو form_data.
ترميز ⁨JSON⁩. يُفوِّض toJson() إلى json_encode مع دمج JSON_THROW_ON_ERROR عبر ⁨OR⁩ في أعلام المستدعي. يُفوِّض jsonSerialize() إلى toArray()، لذا يُنتج json_encode($dto) الشكل نفسه.
تسلسل حتمي. ترتيب المفاتيح وشكلها ثابتان بحسب الـ⁨DTO⁩. يُسقط Segment::toArray() مفتاح children عندما يكون فارغًا؛ ويُسقط FormField::toArray() مفتاح bounding_box عندما يكون null. يجب على المستهلكين معاملة كلا المفتاحين كاختياريين.
رحلة ذهاب وإياب. يكشف كل ⁨DTO⁩ عن fromArray() ثابتة تقبل كائن ⁨JSON⁩ مُفكَّك الترميز. تُحرَس أنواع الحقول عند هذا الحد العابر للعمليات: القيم الغائبة أو ذات النوع الخاطئ ترجع إلى القيم الافتراضية الموثّقة بدلًا من إطلاق استثناء.
قيم تعداد احتياطية. تُطابَق سلسلة type غير المُتعرَّف عليها مع SegmentType::Unknown في Segment::fromArray() ومع FormFieldType::Text في FormField::fromArray().
الإحداثيات. إحداثيات BoundingBox هي وحدات فضاء المستخدم في ⁨PDF⁩ (نقاط، 1/72 بوصة) مع الأصل في الزاوية السفلية اليسرى للصفحة. أرقام الصفحات مبنية على الأساس واحد في كل مكان.
وصل النص العادي. يصل ExtractedPage::plainText() محتوى الكتل بمسافات مفردة. ويصل ExtractedText::plainText() الصفحات بأسطر فارغة ("\n\n").
استعلامات التجزئة. يُرشِّح ofType() وonPage() وcontentSegments() الأجزاء عالية المستوى فقط ويُعيدون قوائم مُعاد فهرستها. يختار contentSegments() الأنواع التي يكون فيها SegmentType::isContent() بقيمة true: heading وsub_heading وparagraph وtable وlist وcode.
استعلامات النماذج. يستثني FormData::dataFields() وtoKeyValueMap() أنواع الحقول غير البيانية (button وsignature). يعُدّ filledCount() الحقول التي تكون قيمتها سلسلة غير فارغة.
قفل المخطط. يقرأ SchemaLock::verify() ملف ⁨V1⁩ schema.json المشحون مع الحزمة، ويُطبِّع ⁨CRLF⁩ إلى ⁨LF⁩، ويُجزِّئ بـ ⁨SHA-256⁩، ويقارن بالثابت المقفول في زمن ثابت. يستخدمه ⁨CI⁩ لحجب انحراف المخطط الصامت؛ لا تتغير قيمة القفل إلا مع تغيير مُصدَّر ومتعمَّد للمخطط.
سياسة الإصدارات. سطح ⁨V1⁩ عقد عام صريح. التغييرات الإضافية ترفع إصدار المخطط؛ والتغييرات الكاسرة تتطلب إصدارًا رئيسيًا جديدًا.

الحالات الحدّية وأنماط الإخفاق

العضو الوحيد المُطلِق للاستثناءات على هذا السطح هو toJson(): JsonException عندما تكون المصفوفة غير قابلة للترميز، مثلًا ⁨UTF-8⁩ غير صالح في المحتوى المستخرج.
يُعيد SchemaLock::verify() قيمة false — ولا يُطلق استثناءً أبدًا — عندما يكون ملف المخطط مفقودًا أو غير قابل للقراءة أو مُعدَّلًا. قارن expectedHash() بـ actualHash() للتمييز بين الانحراف وإخفاق الإدخال/الإخراج.
القيم الاحتياطية لـ fromArray() صامتة بحكم التصميم. page_number ذو النوع الخاطئ يصبح 1؛ وconfidence ذو النوع الخاطئ يصبح القيمة الافتراضية. تحقّق أعلى المصدر عندما تكون القيم الافتراضية المُصطنَعة غير مقبولة.
إكراه السلاسل الرقمية غير متماثل. يقبل PageInfo::fromArray() السلاسل الرقمية لحقوله من نوع العدد الصحيح والعشري؛ بينما يقبل Segment وTextBlock نوع العدد الصحيح أو العشري فقط لـ confidence وfont_size.
يتطلب BoundingBox::fromArray() جميع المفاتيح الأربعة وفق شكل المصفوفة الموثّق له. تستبدل الـ⁨DTOs⁩ التي تُضمِّنه صندوقًا صفريًا (أو null لـ FormField) عندما يكون المفتاح الغلاف غائبًا.
يستبدل ExtractedPage::fromArray() قيمة page_info احتياطية للصفحة 1 بمقاس 595 × 842 نقطة عندما يكون المفتاح مفقودًا أو ذا نوع خاطئ.
يقبل FormField::fromArray() القيم المنطقية الصارمة فقط لـ required وread_only؛ السلاسل والأعداد الصحيحة الصادقة تُطابَق مع false.
أبناء Segment يتكرّرون دون حد للعمق. التداخل العميق جدًا مقيّد فقط بحدود الذاكرة والمكدس في ⁨PHP⁩.
لا تحدث أي عملية مفتاح تشفيري أو توقيع في هذه الوحدة. يستخدم SchemaLock خوارزمية ⁨SHA-256⁩ حصريًا كمجموع تحقق لسلامة الملف، لذا لا يوجد سلوك خاص بوضع ⁨FIPS⁩.

المطابقة

‏⁨Interop V1⁩ عقد سلك مُصدَّر ومملوك لـ ⁨NextPDF⁩. لا يُنفِّذ معيارًا خارجيًا، لذا لا يوجد جدول استشهادات معيارية. تتوافق دلالات BoundingBox مع نموذج إحداثيات فضاء المستخدم في ⁨PDF⁩ الذي تستخدمه أنظمة ⁨Core⁩ الفرعية المُنتِجة؛ وذلك بيان توافق بنيوي، لا نتيجة اختبار مطابقة. ‏⁨NextPDF⁩ لا يملك أي شهادة ولا يمنح أيًّا منها.

ملاحظات التطوير

تفرّع على schema_version في المستهلكين. عامل المفاتيح الإضافية كمتوافقة؛ ارفض الإصدارات الرئيسية غير المعروفة صراحةً.
شغّل SchemaLock::verify() في ⁨CI⁩. عند الإخفاق، سجّل expectedHash() وactualHash() واشترط تغييرًا مُصدَّرًا ومتعمَّدًا للمخطط، لا تعديلًا في المكان أبدًا.
لرحلات الذهاب والإياب العابرة للعمليات، فكّ الترميز بمصفوفات ترابطية (json_decode($json, true)) وقدّم النتيجة إلى fromArray() المطابقة.
جميع الـ⁨DTOs⁩ من نوع final وreadonly. وسّع بالتركيب؛ اشتق عروضًا جديدة من الحقول العامة.
يُسطِّح toKeyValueMap() الحقول الحاملة للبيانات فقط. اقرأ حقول signature مباشرةً من FormData::$fields عندما يكون وجودها مهمًا.
إعادة الاستخدام آمنة: الـ⁨DTOs⁩ لا تحمل حالة قابلة للتغيير ولا موارد، لذا يمكن تخزينها مؤقتًا ومشاركتها عبر الطلبات وتسلسلها مرارًا.

حدود النشر

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