القالب — مرجع متعمّق

نظرة سريعة

يوثّق هذا المرجع التفصيلي مخطط قوالب ⁨JSON⁩ المقبول، وكل قاعدة تحقّق، وسلوك التنسيق الدقيق لكل نوع في أداة ربط البيانات. تحلّل الوحدة تعريف القالب، ثم تربط بيانات المُستدعي بعناصر نائبة مُنمَّطة. تُصدر سلاسل نصية مُنسّقة؛ ولا ترسم كائنات ⁨PDF⁩.

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

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

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

تُتيح الوحدة خدمتَي دخول اثنتين وأربعة كائنات قيمة غير قابلة للتغيير. كل رمز أدناه عام ومستقر.

الرمز	المعامِلات	السلوك الافتراضي	القيمة المُعادة	يطرح أو يفشل بـ	ملاحظات
TemplateParser::parse	string $json	يتحقّق ثم يبني التعريف	TemplateDefinition	InvalidArgumentException عند وجود أي خطأ تحقّق	يفوّض إلى validate أولًا.
TemplateParser::validate	string $json	يجمع كل الأخطاء البنيوية في تمريرة واحدة	list<string> (فارغة عند الصحّة)	لا يطرح أبدًا؛ يُعاد فشل فكّ ترميز ⁨JSON⁩ كرسالة	البوّابة المرجعية لحدود الطول والدقّة.
TemplateDataBinder::bind	TemplateDefinition $template، array<string,mixed> $data	يطابق العناصر النائبة دون حساسية لحالة الأحرف ويُنسّق حسب النوع	BindingResult	لا يطرح أبدًا؛ تتحوّل الحالات الشاذّة إلى تحذيرات أو حقول مفقودة	يستخدم القيمة الافتراضية للعنصر النائب عند غياب المفتاح.
TemplateDefinition::__construct	string $name، string $pageSize، string $orientation، list<TemplatePlaceholder> $placeholders، string $backgroundPdf = ''	يخزّن التعريف المُحلَّل	TemplateDefinition	TypeError عند عدم تطابق نوع وسيط	كائن قيمة final readonly.
TemplateDefinition::getPlaceholder	string $name	بحث بالاسم دون حساسية لحالة الأحرف	TemplatePlaceholder|null	لا فشل؛ يُعيد null عند الغياب	—
TemplateDefinition::requiredFields	لا شيء	يجمع أسماء العناصر النائبة التي لا قيمة افتراضية لها	list<string>	لا فشل	القيمة الافتراضية غير الفارغة تجعل العنصر النائب اختياريًا.
TemplatePlaceholder::__construct	string $name، PlaceholderType $type، float $x، float $y، float $width، float $height، string $defaultValue = ''، string $format = ''	يخزّن منطقة عنصر نائب واحد	TemplatePlaceholder	TypeError عند عدم تطابق نوع وسيط	الإحداثيات نقاط تُقاس من الزاوية العلوية اليسرى.
TemplatePlaceholder::matches	string $key	مقارنة اسم دون حساسية لحالة الأحرف	bool	لا فشل	—
BindingResult::__construct	list<BoundPlaceholder> $bindings، list<string> $missingFields، list<string> $warnings	يخزّن نتيجة الربط	BindingResult	TypeError عند عدم تطابق نوع وسيط	كائن قيمة final readonly.
BindingResult::isComplete	لا شيء	يفيد بما إذا كان كل حقل مطلوب قد رُبط	bool	لا فشل	صحيح عندما تكون missingFields فارغة.
BindingResult::count	لا شيء	يعدّ العناصر النائبة المربوطة بنجاح	int	لا فشل	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder، string $formattedValue، mixed $rawValue	يقرن عنصرًا نائبًا بقيمته المُنسّقة	BoundPlaceholder	TypeError عند عدم تطابق نوع وسيط	كائن قيمة final readonly.
PlaceholderType	حالات التعداد Text، Image، Barcode، Date، Number، Currency، Conditional	تصنيف عناصر نائبة مدعوم بسلاسل نصية	نسخة تعداد	ValueError من from() عند قيمة غير معروفة	tryFrom() يُعيد null بدلًا من ذلك.
PlaceholderType::requiresFormatting	لا شيء	يفيد بما إذا كان النوع يستهلك سلسلة تنسيق	bool	لا فشل	صحيح لـ Date وNumber وCurrency.

final class TemplateParser
{
    public function parse(string $json): TemplateDefinition;
    public function validate(string $json): array;
}

final class TemplateDataBinder
{
    public function bind(TemplateDefinition $template, array $data): BindingResult;
}

عقد السلوك

شكل ⁨JSON⁩ المقبول:

{
  "name": "string (required, non-empty)",
  "pageSize": "A3|A4|A5|A6|B4|B5|Letter|Legal|Tabloid",
  "orientation": "P|L",
  "backgroundPdf": "optional path string",
  "placeholders": [
    { "name": "string", "type": "text|image|barcode|date|number|currency|conditional",
      "x": number, "y": number, "width": number, "height": number,
      "defaultValue": "optional", "format": "optional" }
  ]
}

قواعد التحقّق، تُظهرها جميعًا validate كرسائل وتجمّعها parse في استثناء واحد:

• ‏name مفقود أو فارغ.
• ‏pageSize خارج قائمة السماح، أو orientation ليس P ولا L.
• ‏placeholders مفقود، أو قيمة ليست مصفوفة.
• لكل عنصر نائب: اسم مفقود أو فارغ؛ نوع غير صالح؛ x أو y أو width أو height مفقودة أو غير رقمية؛ اسم مكرّر (دون حساسية لحالة الأحرف).
• ‏defaultValue: ليست سلسلة نصية، أو أطول من 4096 بايت، أو تحمل حرف تحكّم ⁨ASCII⁩.
• ‏format: ليست سلسلة نصية، أو أطول من 256 بايت، أو تحمل حرف تحكّم ⁨ASCII⁩.
• ‏format لعنصر نائب من نوع number ليس عددًا صحيحًا غير سالب، أو يتجاوز 30.

دلالات الربط (TemplateDataBinder::bind):

• تُحوَّل مفاتيح البيانات إلى أحرف صغيرة للمطابقة دون حساسية لحالة الأحرف مع أسماء العناصر النائبة.
• المفتاح الغائب ذو القيمة الافتراضية غير الفارغة يربط القيمة الافتراضية؛ أما المفتاح الغائب بلا قيمة افتراضية فيُبلَّغ عنه في missingFields.
• قيم النص والصورة والباركود تُحوَّل إلى سلسلة نصية دون تغيير.
• يقبل ربط التاريخ DateTimeInterface، أو ختمًا زمنيًا صحيحًا بنظام ⁨Unix⁩، أو سلسلة نصية بأحد أربعة تنسيقات صريحة. تنسيق الإخراج الافتراضي هو Y-m-d.
• يستخدم ربط الأرقام number_format(value, decimals, '.', ','). يأتي عدد المنازل العشرية من format، وقيمته الافتراضية 2، ويُقيَّد ضمن المدى 0 إلى 30.
• يسبق ربط العملة الرقمَ المُنسّق بـ format، وتكون البادئة الافتراضية $.
• يُصدر الربط الشرطي "true" أو "false" من تحويل منطقي.

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

• ‏backgroundPdf لا تفتحه هذه الوحدة أبدًا ولا تفكّ الإشارة إليه. إنه سلسلة نصية معتمة تُسلَّم إلى أداة العرض.
• القيمة غير الرقمية المربوطة بعنصر نائب من نوع ⁨Number⁩ أو ⁨Currency⁩ تُنتج تحذيرًا؛ وتُحوَّل القيمة إلى سلسلة نصية، ولا تُرفض.
• تُحلَّل سلاسل التاريخ بصرامة. الرموز النسبية ورموز اللغة الطبيعية (⁨“now”⁩، ⁨“+1 year”⁩، ⁨“tomorrow”⁩) لا تطابق أي تنسيق مقبول، فتُطلق تحذيرًا وتمرّ القيمة الخام دون تغيير.
• تُقرأ قيمة التاريخ الصحيحة كختم زمني بنظام ⁨Unix⁩ عبر صيغة الحقبة @.
• دقّة format لنوع ⁨Number⁩ خارج المدى 0 إلى 30 التي تصل إلى أداة الربط تُرفض بتحذير؛ وترجع أداة الربط إلى الدقّة الافتراضية 2.
• لا تجري أي عملية تشفير في هذه الوحدة، لذا لا يوجد سلوك خاص بوضع ⁨FIPS⁩.

المطابقة

لا يوجد سطح مباشر لمواصفة ⁨PDF⁩. مفردات حجم الصفحة والاتجاه هي اصطلاحات ⁨NextPDF⁩، والوحدة تُصدر قيمًا مُنسّقة لا كائنات ⁨PDF⁩. تقبل قائمة السماح الصارمة لتاريخ السلاسل النصية ملفَّ تعريف التاريخ/الوقت للإنترنت من ⁨ISO 8601⁩ المُعرَّف في ⁨RFC 3339 §5.6⁩، إلى جانب تاريخ تقويمي Y-m-d وشكلين محليين للتاريخ والوقت. توثّق ⁨NextPDF⁩ القدرة على قراءة هذه التنسيقات؛ ولا تدّعي أي اعتماد مقابل ⁨RFC 3339⁩ أو ⁨ISO 8601⁩.

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

• ‏TemplateParser وTemplateDataBinder عديمتا الحالة. نسخة واحدة قابلة لإعادة الاستخدام وآمنة للمشاركة عبر عمليات الربط.
• كائنات القيمة الأربعة هي final readonly؛ أنشئها عبر المحلّل لا يدويًا لمدخلات الإنتاج.
• ‏validate تُبلّغ عن كل خطأ بنيوي في تمريرة واحدة، بينما تستدعي parse الدالة validate أولًا وتطرح استثناءً بالرسالة المجمّعة. استخدم validate للتغذية الراجعة على نمط النماذج وparse للاستيعاب سريع الفشل.
• تُفرَض حدود الطول والدقّة عند المحلّل بوصفه البوّابة المرجعية. تعيد TemplateDataBinder فحص دقّة الأرقام كحارس على جانب المصبّ ضد تضخيم الذاكرة في number_format.

حدود النشر

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

اطّلع أيضًا

• القالب (دليل القدرة)
• جدول المحتويات
• الدمج