‏⁨Form⁩ — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع المتعمّق لوحدة ⁨Form⁩ في ⁨Pro⁩. وهي تغطي استخراج قيم ⁨AcroForm⁩، وقراءة ⁨XFDF⁩ وكتابته، وربط البيانات، واستخراج بيانات ⁨XFA⁩. تستهلك الوحدة قيم NextPDF\Form\FormField التي ينتجها قارئ النماذج في ⁨Core⁩، وتضيف فوقها التسلسل والتحليل والربط. دعم ⁨XFA⁩ موجّه نحو البيانات: يبني المحلّل بنية حزمتَي القالب ومجموعات البيانات. وهو لا ينفّذ نصوص حساب ⁨XFA⁩ البرمجية ولا يعرض تخطيطات ⁨XFA⁩ الديناميكية.

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

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

لا يوجد عَلَم ترخيص لكل ميزة على حدة. هذه إمكانية خاصة بإصدار ⁨Pro⁩.

سطح ⁨API⁩ العام

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يطرح أو يفشل بـ	ملاحظات
FormDataExtractor::extract	list<FormField> $fields	يقرأ اسم كل حقل وقيمته	XfdfData	—	يشمل الحقول التي قيمتها فارغة.
FormDataExtractor::toArray	list<FormField> $fields	يبني خريطة نصية من الاسم إلى القيمة	array<string, string>	—	الاسم المكرَّر لاحقًا يستبدل الأسبق.
FormDataExtractor::toXfdf	list<FormField> $fields، ?string $pdfHref = null	يفوّض إلى XfdfWriter::fromFields	string (XFDF XML)	—	مسار مُيسِّر للتصدير بنداء واحد.
FormDataExtractor::extractNonEmpty	list<FormField> $fields	يتخطى الحقول التي قيمتها السلسلة الفارغة	XfdfData	—	—
FormDataExtractor::getEmptyFieldNames	list<FormField> $fields	يسرد أسماء الحقول التي لم تُضبط لها قيمة	list<string>	—	مُكمِّل لـ extractNonEmpty.
XfdfWriter::fromFields	list<FormField> $fields، ?string $pdfHref = null	يجمع أزواج الاسم-القيمة، ويفوّض إلى fromArray	string (XFDF XML)	—	—
XfdfWriter::fromArray	array<string, string> $data، ?string $pdfHref = null	يغلّف الخريطة في XfdfData، ويفوّض	string (XFDF XML)	—	—
XfdfWriter::fromXfdfData	XfdfData $data، ?string $pdfHref = null	يُسلسِل إلى ⁨XFDF⁩؛ أسماء الترميز النقطي تتداخل كعناصر <field> هرمية	string (XFDF XML)	—	يزيل أحرف التحكم غير المسموح بها في ⁨XML 1.0⁩؛ راجع عقد السلوك.
XfdfParser::parse	string $xfdfXml	يحمّل ⁨XML⁩ بأمان ضد ⁨XXE⁩ ويُسطّح الحقول إلى الترميز النقطي	XfdfData	InvalidArgumentException	سقف إدخال ⁨10 MiB⁩؛ يقبل الجذور ذات فضاء الأسماء وغير ذات فضاء الأسماء.
XfdfParser::parseFile	string $filePath	يحلّ المسار، ويقرأ الملف، ويفوّض إلى parse	XfdfData	InvalidArgumentException	المسارات المفقودة أو غير الملفّية أو غير القابلة للقراءة تطرح استثناء.
XfaParser::parse	string $pdfData	فحص العلامة، واستخراج ⁨XML⁩، وتحليل الحزم	XfaFormData	InvalidArgumentException، XfaParseException	غياب علامة /XFA يُعيد نتيجة فارغة، لا خطأ.
XfaParser::hasXfa	string $pdfData	يمسح البايتات بحثًا عن علامة /XFA	bool	—	مسح بعلامة بايتية؛ أي ورود للرمز يُطابِق.
XfaParser::extractXfaXml	string $pdfData	مسح التدفق بحثًا عن علامات ⁨XFA⁩، ثم بحث مباشر عن <xdp:xdp>	string (XFA XML or '')	RuntimeException (مُصرَّح به)	يمسح ⁨50 MiB⁩ الأولى من الإدخال على الأكثر.
XfaParser::parseXml	string $xml	يستخرج حزمتَي القالب ومجموعات البيانات، ويحلّل عناصر <field>	XfaFormData	XfaParseException	سقف ⁨XML⁩ ⁨10 MiB⁩، مفروض قبل تحميل ⁨DOM⁩.
FormDataBinder::bind	list<FormField> $fields، XfdfData $data	ينشئ نسخ FormField جديدة بقيم مربوطة	FormDataBindResult	—	لا تُعدَّل الأصول أبدًا؛ خانات الاختيار تُطبَّع إلى Yes/Off.
FormDataBinder::fromXfdf	list<FormField> $fields، string $xfdfXml	يحلّل ⁨XFDF⁩، ثم يربط	FormDataBindResult	InvalidArgumentException	أنماط الفشل هي أنماط XfdfParser::parse.
FormDataBinder::fromArray	list<FormField> $fields، array<string, string> $data	يغلّف الخريطة في XfdfData، ثم يربط	FormDataBindResult	—	—
FormDataBindResult	isFullyBound، hasNoUnmatchedKeys، boundCount، fieldCount؛ readonly fields، boundFieldNames، unmatchedDataKeys، unboundFieldNames	تشخيصات ربط غير قابلة للتغيير	حسب الدالّة	—	isFullyBound تتطلّب صفر مفاتيح غير مطابَقة وصفر حقول غير مربوطة.
XfdfData	hasField، getValue، count، isEmpty، getFieldNames، withField، withoutField، merge؛ readonly fields	حاوية غير قابلة للتغيير من الاسم إلى القيمة	حسب الدالّة	—	with* وmerge تُعيد نسخًا جديدة؛ merge تفضّل قيم الوسيط.
XfaFormData	getField، hasField، count، fieldNames؛ readonly fields، templateXml، datasetsXml	نتيجة تحليل ⁨XFA⁩ غير قابلة للتغيير	حسب الدالّة	—	يحمل ⁨XML⁩ الخام لحزمتَي القالب ومجموعات البيانات لأجل الذهاب والإياب.
XfaFormField	readonly name، type، value، required، caption، options	سجل حقل مفرد غير قابل للتغيير	—	—	type هو أحد text أو numeric أو date أو choice أو button أو signature.
XfaPacket	حالات التعداد Template، Datasets، Config، LocaleSet، ConnectionSet، Form؛ xmlNamespace()	تعداد حزم مدعوم بسلسلة نصية	string من xmlNamespace()	—	معرّفات فضاء الأسماء (URIs) تتبع ⁨XFA Specification 3.3⁩.

public static function extract(array $fields): XfdfData
public static function toArray(array $fields): array
public static function toXfdf(array $fields, ?string $pdfHref = null): string
public static function extractNonEmpty(array $fields): XfdfData
public static function getEmptyFieldNames(array $fields): array

public static function fromFields(array $fields, ?string $pdfHref = null): string
public static function fromArray(array $data, ?string $pdfHref = null): string
public static function fromXfdfData(XfdfData $data, ?string $pdfHref = null): string

public static function parse(string $xfdfXml): XfdfData
public static function parseFile(string $filePath): XfdfData

public function parse(string $pdfData): XfaFormData
public function hasXfa(string $pdfData): bool
public function extractXfaXml(string $pdfData): string
public function parseXml(string $xml): XfaFormData

public static function bind(array $fields, XfdfData $data): FormDataBindResult
public static function fromXfdf(array $fields, string $xfdfXml): FormDataBindResult
public static function fromArray(array $fields, array $data): FormDataBindResult

الاستثناءات

• NextPDF\Pro\Form\Exception\XfaParseException يمتد من RuntimeException — تعذّر تحليل حمولة ⁨XFA⁩ إلى XfaFormData. التصنيف الفرعي مقصود: مواقع النداء الحالية catch (RuntimeException $e) تظل تعمل.
• InvalidArgumentException من ⁨SPL⁩ — إدخال فارغ أو مفرط الحجم أو مشوَّه أو غير ⁨XFDF⁩ إلى XfdfParser؛ إدخال ⁨PDF⁩ فارغ إلى XfaParser::parse؛ مسارات غير قابلة للقراءة في XfdfParser::parseFile.

عقد السلوك

استخراج ⁨AcroForm⁩. يمرّ FormDataExtractor على قائمة الحقول التي تمرّرها ويقرأ اسم كل حقل وقيمته. تُعيد extract قيمة XfdfData؛ وتُعيد toArray خريطة نصية بسيطة من الاسم إلى القيمة. تُسقط extractNonEmpty الحقول التي قيمتها السلسلة الفارغة؛ وتُعيد getEmptyFieldNames قائمة الأسماء المُكمِّلة. لا يغيّر الاستخراج حقول الإدخال أبدًا.

كتابة ⁨XFDF⁩. يُنتج XfdfWriter مستندًا متوافقًا مع بنية ⁨ISO 19444-1:2019⁩. يبدأ الناتج بإعلان ⁨XFDF XML⁩ وجذر xfdf ضمن فضاء أسماء ⁨Adobe XFDF⁩ (http://ns.adobe.com/xfdf/) مع xml:space="preserve". قيمة pdfHref غير الخالية تُصدِر مرجعًا <f href="..."/> يعود إلى ⁨PDF⁩ المصدر. أسماء الحقول بالترميز النقطي (مثل address.city) تتداخل في شجرة عناصر <field> هرمية. القيم والسمات تُهرِّب محارف ⁨XML⁩ الخمسة الوصفية. أسماء الحقول وقيمها وpdfHref تُطبَّع إضافيًا لضمان صحة التشكيل: تُزال محارف تحكم ⁨C0⁩ التي يمنعها ⁨XML 1.0⁩، بينما تُحفظ ⁨TAB⁩ و⁨LF⁩ و⁨CR⁩. هذا التطبيع فاقِد بالتصميم، لذا يُصدِر الكاتب دائمًا ⁨XFDF⁩ صحيح التشكيل وقابلًا لإعادة التحليل بغضّ النظر عن البايتات التي يمرّرها المُستدعي.

قراءة ⁨XFDF⁩. يقبل XfdfParser جذور xfdf ذات فضاء الأسماء وغير ذات فضاء الأسماء، ويطابق اسم الجذر بغضّ النظر عن حالة الأحرف، لأن بعض المنتِجين يُصدِرون عنصر جذر بأحرف كبيرة. أشجار <field> الهرمية تُسطَّح عائدةً إلى أسماء الترميز النقطي، فتكتمل دورة الكتابة والقراءة ذهابًا وإيابًا. كل تحميل لـ ⁨XML⁩ يُعطِّل الوصول إلى الشبكة وحلّ الكيانات الخارجية. تضيف parseFile حلّ المسار وفحوص القابلية للقراءة أمام التحليل نفسه.

ربط البيانات. تُطابق FormDataBinder::bind مفاتيح البيانات مع أسماء الحقول. ولأن FormField غير قابل للتغيير، يُنشئ الربط نسخًا جديدة بقيم محدّثة؛ ولا تُعدَّل الأصول أبدًا. تُبلِّغ النتيجة عن ثلاث مجموعات تشخيصية: أسماء الحقول المربوطة، ومفاتيح البيانات التي لا حقل مطابق لها، والحقول التي لم تتلقّ بيانات. قيم خانات الاختيار تُطبَّع إلى نموذج حالة التشغيل/الإيقاف في ⁨ISO 32000-2:2020⁩، ⁨12.7.5.2.3⁩: القيم yes وtrue و1 وon بغضّ النظر عن حالة الأحرف تُطابَق إلى Yes؛ وكل قيمة أخرى تُطابَق إلى Off.

استخراج بيانات ⁨XFA⁩. تقبل XfaParser::parse بايتات ⁨PDF⁩ الخام. تمسح أولًا بحثًا عن علامة /XFA؛ وفي غياب العلامة تُعيد XfaFormData فارغة. ثم يجرّب الاستخراج استراتيجيتين: مسح كتل stream…endstream بحثًا عن مؤشّرات ⁨XFA XML⁩، ثم بحث مباشر عن مستند <xdp:xdp>. تُعاد شظية xdp:xdp المفردة كما هي؛ وتُدمَج الشظايا المتعددة في مِظروف xdp:xdp مُصطنَع. تستخرج parseXml حزمتَي القالب ومجموعات البيانات وتحلّل كل عنصر <field> في القالب إلى XfaFormField: سمة الاسم مطلوبة، والنوع يُشتقّ من عنصر ⁨UI⁩ الابن للحقل، وعَلَم الإلزام يُشتقّ من عنصر validate مضبوط فيه nullTest على error، وخيارات الاختيار تأتي من العناصر الأبناء items.

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

الحالات الحدّية وأنماط الفشل

• XfdfParser::parse('') يطرح InvalidArgumentException. الإدخال الذي يتجاوز ⁨10 MiB⁩ يطرح InvalidArgumentException يذكر السقف.
• ⁨XML⁩ المشوَّه يطرح InvalidArgumentException حاملًا رسائل ⁨libxml⁩ المجمَّعة. المستند صحيح التشكيل الذي جذره ليس xfdf يطرح ويذكر عنصر الجذر الفعلي.
• مستند ⁨XFDF⁩ بلا عنصر <fields> يُحلَّل إلى XfdfData فارغة؛ وهذا ليس خطأً.
• عناصر الحقول التي بلا سمة name تُتخطّى في تحليل ⁨XFDF⁩ و⁨XFA⁩ كليهما. حقل ⁨XFDF⁩ بلا عنصر ابن <value> لا يُسهم بأي مُدخَل.
• XfaParser::parse('') يطرح InvalidArgumentException. ملف ⁨PDF⁩ بلا علامة /XFA، أو ملف يتعذّر تحديد موضع ⁨XFA XML⁩ فيه، يُعيد XfaFormData فارغة بدل أن يطرح.
• hasXfa مسح بعلامة بايتية: أي رمز /XFA في الملف يُطابِق، بما في ذلك رمز في كائن غير مستخدَم. خطوة الاستخراج اللاحقة تقرّر إن كان يوجد ⁨XML⁩ قابل للاستخدام.
• يفحص استخراج ⁨XFA⁩ ⁨50 MiB⁩ الأولى من سلسلة بايتات ⁨PDF⁩ على الأكثر؛ والمحتوى بعد ذلك الحد لا يُمسح.
• ⁨XFA XML⁩ الذي يتجاوز ⁨10 MiB⁩ يطرح XfaParseException قبل أن تتجسّد أي شجرة ⁨DOM⁩. ⁨XFA XML⁩ المشوَّه يطرح XfaParseException مع رسائل ⁨libxml⁩.
• تطبيع خانات الاختيار لا يُمرِّر أبدًا القيم غير المعروفة؛ وأي شيء خارج صيغ التشغيل المقبولة يُطابَق إلى Off.
• إزالة الكاتب لأحرف التحكم فاقِدة: بايتات ⁨C0⁩ غير المسموح بها في ⁨XML 1.0⁩ داخل الأسماء أو القيم أو pdfHref تُسقَط ليبقى الناتج صحيح التشكيل. ⁨TAB⁩ و⁨LF⁩ و⁨CR⁩ تبقى.
• كل تحليل لـ ⁨XML⁩ يُعطِّل حلّ الكيانات الخارجية والوصول إلى الشبكة (آمن ضد ⁨XXE⁩).
• لا تُجري هذه الوحدة أي عمليات تشفيرية؛ ووضع ⁨FIPS⁩ لا يغيّر سلوكها.

المطابقة

السلوك	المرجع	الحالة
نموذج النموذج التفاعلي / قاموس الحقول	⁨ISO 32000-2:2020, 12.7⁩	متوافق (مؤصَّل بالمنتج)
تطبيع حالة التشغيل/الإيقاف لخانة الاختيار (Yes/Off)	⁨ISO 32000-2:2020, 12.7.5.2.3⁩	متوافق؛ البند مُستشهَد به في سجل استشهادات هذه الصفحة
بنية تبادل بيانات ⁨XFDF⁩	⁨ISO 19444-1:2019⁩	متوافق (مؤصَّل بالمنتج)
أسماء حزم ⁨XFA⁩ ومعرّفات فضاء الأسماء	⁨XFA Specification 3.3⁩	متوافق (مؤصَّل بالمنتج)

مجموعة ⁨RAG⁩ المتاحة وقت التأليف لا تتضمّن ⁨ISO 19444-1:2019⁩ ولا ⁨XFA Specification⁩ ولا ⁨W3C XML 1.0⁩، لذا فإن بيانات التوافق تلك مؤصَّلة بالمنتج من تعليقات المصدر والاختبارات بدلًا من الاستشهاد بالبنود. تصف هذه البيانات الإمكانية مقابل المستندات المُشار إليها. لا تملك ⁨NextPDF⁩ أي شهادة مطابقة، ودعم بندٍ ما ليس ادّعاء اعتماد.

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

• كل نقطة دخول عدا XfaParser ساكنة (static). XfaParser قابل للإنشاء وعديم الحالة؛ ويمكن إعادة استخدام نسخة واحدة بأمان عبر المستندات.
• دورة الذهاب والإياب المقصودة هي: قارئ النماذج في ⁨Core⁩ يُنتج قيم FormField؛ وFormDataExtractor أو XfdfWriter يُسلسِلها؛ وXfdfParser يقرأ البيانات مجددًا؛ وFormDataBinder يطبّقها على قائمة حقول. الأسماء الهرمية تنجو من الدورة عبر الترميز النقطي.
• استخدم تشخيصات FormDataBindResult (isFullyBound وunmatchedDataKeys وunboundFieldNames) لاكتشاف الانحراف بين ملف بيانات ⁨XFDF⁩ وقالب ⁨PDF⁩ مُنقَّح قبل قبول تعبئة.
• XfdfData كائن قيمة: withField وwithoutField وmerge تُعيد نسخًا جديدة. عند تصادم المفاتيح، تفضّل merge قيم الوسيط.
• XfaFormData يحتفظ بـ ⁨XML⁩ الخام لحزمتَي القالب ومجموعات البيانات (templateXml وdatasetsXml) لتتمكّن من المعالجة اللاحقة للحزم التي لا يغطّيها نموذج الحقول.
• لا تحلّل هذه الوحدة قواميس ⁨AcroForm⁩ من بايتات ⁨PDF⁩ بنفسها؛ بل تستهلك الحقول التي ينتجها قارئ النماذج في ⁨Core⁩. XfaParser وحده يعمل على محتوى ⁨PDF⁩ الخام.

حدود النشر

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

اطّلع أيضًا

• ⁨Form⁩ — نظرة عامة على الإمكانية
• ⁨Interop⁩ — مرجع متعمّق
• وحدة ⁨Core Form⁩