النماذج

لمحة سريعة

يقرأ ⁨NextPDF Pro⁩ بيانات النماذج التفاعلية ويكتبها: قيم حقول ⁨AcroForm⁩، وملفات بيانات ⁨XFDF⁩، والبيانات التي تحملها قوالب ⁨XFA⁩ (بنية نماذج ⁨XML⁩). وهو يُكمِّل قارئ النماذج مفتوح المصدر في ⁨Core⁩ بربط البيانات والاستخراج والتسلسل.

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

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

‏⁨Form⁩ جزء من إصدار ⁨Pro⁩. لا يوجد علم ترخيص منفصل لكل ميزة.

التثبيت

composer require nextpdf/pro:^3

تتطلّب قدرة ⁨Form⁩ ترخيص ⁨NextPDF Pro⁩ صالحًا. انظر التوافر والترخيص.

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

يخزّن نموذج ⁨PDF⁩ التفاعلي — الذي يُسمّى أحيانًا ⁨AcroForm⁩ — كل حقل في قاموس حقل، كما هو مُعرَّف في ⁨ISO 32000-2⁩ §12.7. يبني ⁨NextPDF Pro⁩ فوق قارئ النماذج في ⁨Core⁩ لإضافة ثلاث قدرات:

• دورة ⁨AcroForm⁩ الكاملة. يقرأ FormDataExtractor أزواج اسم/قيمة الحقول من حقول النماذج المُحلَّلة ويُنتج كائن XfdfData أو خريطة name → value بسيطة. ويُنفّذ XfdfWriter العكس، مُولِّدًا مستند ⁨XFDF⁩.
• قراءة ⁨XFDF⁩ وكتابته. ‏⁨XFDF⁩ هو تنسيق تبادل بيانات ⁨XML⁩ لقيم النماذج الموصوف في ⁨ISO 19444-1:2019⁩. يقرأ XfdfParser ملف ⁨XFDF⁩ إلى بيانات مُنظَّمة؛ ويُسلسِل XfdfWriter قيم الحقول إلى ⁨XFDF⁩، مع مرجع اختياري يعود إلى الـ ⁨PDF⁩ المصدر.
• استخراج بيانات ⁨XFA⁩. يعثر XfaParser على رزم ⁨XFA⁩ في المستند، ويربط شذرات ⁨XML⁩، ويحلّل رزمتَي القالب ومجموعات البيانات إلى بيانات حقول مُنظَّمة.

نطاق دعم ⁨XFA⁩

دعم ⁨XFA⁩ في ⁨NextPDF Pro⁩ موجَّه بالبيانات، لا محرّك عرض أو سكربتة ⁨XFA⁩ كامل. يستخرج المُحلِّل رزمتَي القالب ومجموعات البيانات ويُنظِّمهما لكي تقرأ تعريفات الحقول وقيمها. وهو لا يُنفّذ سكربتات حساب نماذج ⁨XFA⁩، ولا يَعرض تخطيطات ⁨XFA⁩ الديناميكية، ولا يُجري دورة كاملة لكل نوع رزمة ⁨XFA⁩. اختبر المُحلِّل مقابل مستنداتك المحدّدة قبل الاعتماد عليه لمجموعة نماذج ⁨XFA⁩ معيّنة. يُعطِّل كل تحليل ⁨XML⁩ تحميل الكيانات الخارجية (آمن من ⁨XXE⁩).

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

دعم ⁨XFA⁩ مقصور على البيانات لا العرض، عن قصد. يُعلّم ⁨ISO 32000-2⁩ مُدخَل ⁨XFA⁩ في قاموس النموذج بأنه مهجور في ⁨PDF 2.0⁩ (§⁨12.7⁩). ومحرّك تخطيط وسكربتة ⁨XFA⁩ كامل سيلاحق سطحًا قديمًا لم تعد معظم أحمال العمل بحاجة إليه. يستخرج ⁨NextPDF Pro⁩ بدلًا من ذلك رزمتَي القالب ومجموعات البيانات، حيث تسكن بيانات الحقول الدائمة، ويصرف النظر عن البقية. ويقود المنطق نفسه تحليلًا مُعطَّل ⁨XXE⁩ وسقف المسح، لأن مُدخَل النماذج يصل كثيرًا من أطراف غير موثوقة. وهذا يُبقي سطح نماذج ⁨Pro⁩ امتدادًا رقيقًا ومتوقَّعًا لنموذج ⁨AcroForm⁩ في ⁨Core⁩.

خلفية التصميم: من نموذج قابل للتعبئة إلى سجل مُجمَّد: تعبئة ⁨AcroForm⁩ وتسطيحه.

سطح الـ ⁨API⁩

الصنف	المسؤولية
FormDataExtractor	استخراج قيم حقول ⁨AcroForm⁩ بوصفها XfdfData أو مصفوفة.
XfdfParser	تحليل مستند ⁨XFDF⁩ إلى بيانات مُنظَّمة.
XfdfWriter	تسلسل قيم الحقول إلى ⁨XFDF⁩، مع مرجع ⁨PDF⁩ اختياري.
XfaParser	استخراج وتحليل رزمتَي قالب ومجموعات بيانات ⁨XFA⁩.
FormDataBinder	ربط خريطة بيانات مرة أخرى على حقول النموذج.

المرجع الكامل على مستوى الطرائق في المرجع المتعمّق للنماذج.

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

use NextPDF\Pro\Form\FormDataExtractor;
use NextPDF\Pro\Form\XfdfWriter;

$values = FormDataExtractor::toArray($fields);
$xfdf   = XfdfWriter::fromFields($fields, 'invoice.pdf');

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

use NextPDF\Pro\Form\XfaParser;
use NextPDF\Pro\Form\Exception\XfaParseException;

try {
    $formData = (new XfaParser())->parse($pdfBytes);
    $logger->info('xfa.parsed', ['fields' => count($formData->fields)]);
} catch (XfaParseException $e) {
    $logger->warning('xfa.parse_failed', ['reason' => $e->getMessage()]);
}

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

• يرفض XfaParser مُدخَل ⁨PDF⁩ الأكبر من سقف مسحه بدلًا من قراءة بيانات غير محدودة.
• قد يحمل المستند نماذج تفاعلية وغير تفاعلية معًا؛ والاستخراج يستهدف قواميس الحقول الطرفية.
• تُجري دورة ⁨XFDF⁩ الكاملة على بُنى الحقول المسطّحة؛ والتسلسلات الهرمية للحقول العميقة التداخل قد تحتاج إلى معالجة صريحة.

الأداء

الاستخراج والتسلسل خطّيان بعدد حقول النموذج. تتدرّج تكلفة تحليل ⁨XFA⁩ بحجم رزم ⁨XML⁩ المُضمَّنة.

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

يُعطِّل كل تحليل ⁨XML⁩ حلّ الكيانات الخارجية لمنع ⁨XXE⁩. عامِل مُدخَل ⁨XFDF⁩ و⁨XFA⁩ من مصادر غير موثوقة على أنه عدائي وتحقّق من مجموعة الحقول المُحلَّلة قبل ربطها مرة أخرى في مستند.

المطابقة

السلوك	المرجع	الحالة
نموذج النماذج التفاعلية / قاموس الحقل	ISO 32000-2 §12.7	مُتوائم (مُعاد صياغته)
تنسيق تبادل بيانات ⁨XFDF⁩	ISO 19444-1:2019	مُتوائم

يُسجّل هذا الجدول المواصفات التي بُني عليها ⁨NextPDF Pro⁩. وهو ليس بيان شهادة رسمية.

عقد السلوك

• يقرأ FormDataExtractor أزواج اسم/قيمة من قواميس الحقول الطرفية المُحلَّلة ويُعيد كائن XfdfData أو مصفوفة name → value بسيطة.
• يحلّل XfdfParser مستند ⁨XFDF⁩ إلى بيانات مُنظَّمة؛ ويُسلسِل XfdfWriter قيم الحقول إلى ⁨XFDF⁩ مع مرجع اختياري يعود إلى الـ ⁨PDF⁩ المصدر.
• يعثر XfaParser على رزم ⁨XFA⁩، ويربط شذرات ⁨XML⁩، ويحلّل رزمتَي القالب ومجموعات البيانات إلى بيانات حقول مُنظَّمة. ويرفض مُدخَل ⁨PDF⁩ الأكبر من سقف مسحه بدلًا من قراءة بيانات غير محدودة.
• دعم ⁨XFA⁩ موجَّه بالبيانات: يستخرج المُحلِّل رزمتَي القالب ومجموعات البيانات ويُنظِّمهما. وهو لا يُنفّذ سكربتات حساب نماذج ⁨XFA⁩، ولا يَعرض تخطيطات ⁨XFA⁩ الديناميكية، ولا يُجري دورة كاملة لكل نوع رزمة ⁨XFA⁩.
• يُعطِّل كل تحليل ⁨XML⁩ حلّ الكيانات الخارجية (آمن من ⁨XXE⁩).

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

لا يغيّر ⁨Enterprise⁩ سلوك ⁨Form⁩. يضيف ⁨Enterprise⁩ ميزات امتثال وأرشفة من طبقة أعلى موثَّقة بشكل منفصل؛ وهي ليست مطلوبة لدورة ⁨AcroForm⁩ الكاملة، أو قراءة/كتابة ⁨XFDF⁩، أو استخراج بيانات ⁨XFA⁩.

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

يقرأ قارئ النماذج مفتوح المصدر في ⁨NextPDF Core⁩ حقول النماذج. قراءة/كتابة ⁨XFDF⁩، واستخراج بيانات ⁨XFA⁩، وربط الحقول إضافات في ⁨Pro⁩. انظر /modules/form/.

حدود النشر

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

انظر أيضًا

• ⁨Interop⁩ — كائنات نقل بيانات نماذج ذات إصدارات للأنظمة الخارجية.
• وحدة ⁨Form⁩ في ⁨Core⁩ — قارئ النماذج مفتوح المصدر.
• ⁨Form⁩ — مرجع متعمّق — مرجع على مستوى الطرائق لأصناف نماذج ⁨Pro⁩.