القالب

لمحة سريعة

يحلّل NextPDF\Pro\Template تعريف قالب ⁨JSON⁩ إلى كائن قيمة مكتوب النوع ويربط مصفوفة بيانات ترابطية بعناصره النائبة بتنسيق مدرك للنوع. وهو يُنتِج نتيجة ربط منظَّمة؛ ولا يُصيِّر ملف ⁨PDF⁩ بنفسه.

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

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

التثبيت

composer require nextpdf/pro:^3

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

القالب مستند ⁨JSON⁩ يصف إعداد صفحة وقائمة عناصر نائبة مُموضَعة. ويتحقّق TemplateParser من ⁨JSON⁩ ويُنتِج TemplateDefinition غير قابل للتغيير. والتحقّق صارم: يفحص حجم الصفحة مقابل قائمة سماح (⁨A3⁩–⁨A6⁩، و⁨B4⁩، و⁨B5⁩، و⁨Letter⁩، و⁨Legal⁩، و⁨Tabloid⁩)، والاتجاه (P أو L)، واسم كل عنصر نائب ونوعه وإحداثياته العددية، ويرفض أسماء العناصر النائبة المكرَّرة.

يربط TemplateDataBinder مصفوفة بيانات (تُطابَق بصورة غير حسّاسة لحالة الأحرف بأسماء العناصر النائبة) ويُنسِّق كل قيمة حسب PlaceholderType:

• ⁨Text / Image / Barcode⁩ — تُمرَّر القيمة كما هي سلسلةً.
• ⁨Date⁩ — تُنسَّق بتنسيق العنصر النائب (الافتراضي Y-m-d)، وتقبل السلاسل، أو الطوابع الزمنية لـ⁨Unix⁩، أو DateTimeInterface.
• ⁨Number⁩ — number_format بمنازل عشرية من التنسيق (الافتراضي 2).
• ⁨Currency⁩ — رقم مُنسَّق مع سلسلة التنسيق بادئةً (الافتراضي $).
• ⁨Conditional⁩ — "true" أو "false" بناءً على الصدق المنطقي.

النتيجة BindingResult يحمل القيم المربوطة، وقائمة الحقول المطلوبة المفقودة، وأي تحذيرات تنسيق. وتحويل القيم المربوطة إلى ملف ⁨PDF⁩ مُصيَّر مسؤولية المُستدعي، باستخدام واجهات مستند ⁨Core⁩ وكاتبها ومرجع backgroundPdf الاختياري.

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

المحلّل هو البوّابة المرجعية الوحيدة. فهو يحوّل ⁨JSON⁩ غير الموثوق إلى TemplateDefinition غير قابل للتغيير ومكتوب النوع بالكامل، ثم يجري الربط بوصفه دالّة خالصة لتلك القيمة. وكل حقل يصل لاحقًا إلى مصرف تنسيق يكون مُدرَجًا في قائمة سماح ومحدود الطول في وقت التحليل. وحجم الصفحة، والاتجاه، ودقّة الأرقام، وأحرف التحكّم كلها تفشل هنا لا في أثناء التصيير. وتُطابَق سلاسل التاريخ مقابل مجموعة ثابتة من التنسيقات المعيارية، فلا تستطيع قيمة مثل now أو +1 year أن تجعل المخرَج معتمِدًا على ساعة الحائط. وتتوقّف الوحدة عمدًا عند BindingResult وتترك التصيير، وحلّ المسارات، وتركيب الخلفية للمُستدعي، ما يبقي حدّ الثقة صريحًا.

خلفية التصميم: الفواتير والفوترة الإلكترونية.

عقد السلوك

• المُدخَل. سلسلة ⁨JSON⁩ (TemplateParser) ومصفوفة بيانات (TemplateDataBinder).
• المخرَج. TemplateDefinition من التحليل؛ وBindingResult من الربط.
• التحقّق. يُرجِع validate() قائمة أخطاء مقروءة بشريًا ولا يرفع استثناءً أبدًا؛ ويرفع parse() استثناء InvalidArgumentException عند فشل التحقّق.
• البيانات المفقودة. يُبلَّغ عن عنصر نائب بلا بيانات وبافتراضي فارغ في missingFields؛ والعنصر ذو الافتراضي غير الفارغ يستخدم الافتراضي.
• الحتمية. التحليل والربط دالّتان خالصتان لمُدخَلَيهما.

سطح واجهة برمجة التطبيقات العامة

Type	Kind	Key members
NextPDF\Pro\Template\TemplateParser	final class	parse(string $json): TemplateDefinition, validate(string $json): list<string>
NextPDF\Pro\Template\TemplateDataBinder	final class	bind(TemplateDefinition $template, array $data): BindingResult
NextPDF\Pro\Template\TemplateDefinition	final readonly class	string $name, string $pageSize, string $orientation, array $placeholders, string $backgroundPdf, getPlaceholder(string $name): ?TemplatePlaceholder, requiredFields(): list<string>
NextPDF\Pro\Template\TemplatePlaceholder	final readonly class	name, PlaceholderType $type, coordinates, default, format
NextPDF\Pro\Template\BindingResult	final readonly class	array $bindings, array $missingFields, array $warnings
NextPDF\Pro\Template\PlaceholderType	enum	Text, Image, Barcode, Date, Number, Currency, Conditional; requiresFormatting(): bool

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

$json = '{"name":"Invoice","pageSize":"A4","orientation":"P","placeholders":'
 . '[{"name":"total","type":"currency","x":400,"y":700,"width":120,'
 . '"height":18,"format":"$"}]}';

$template = (new TemplateParser())->parse($json);
$result = (new TemplateDataBinder())->bind($template, ['total' => 1299.5]);

foreach ($result->bindings as $bound) {
 echo $bound->placeholder->name, ' => ', $bound->formattedValue, "\n";
}

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

function bindOrReject(string $json, array $data): array
{
 $parser = new TemplateParser();

 $errors = $parser->validate($json);
 if ($errors !== []) {
 throw new InvalidArgumentException(implode('; ', $errors));
 }

 $template = $parser->parse($json);
 $result = (new TemplateDataBinder())->bind($template, $data);

 if ($result->missingFields !== []) {
 throw new RuntimeException(
 'missing required fields: ' . implode(', ', $result->missingFields),
 );
 }

 return $result->bindings; // hand to the renderer
}

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

• تُنتِج سلسلة تاريخ غير قابلة للتحليل تحذيرًا وتُحفَظ السلسلة الأصلية، بدلًا من رفع استثناء.
• تُستخدَم سلسلة تنسيق العملة بادئةً حرفية (مثل "$" أو "EUR ")، لا مُعرِّف لغة محلية.
• backgroundPdf مرجع مسار محمول على التعريف؛ ولا تفتح هذه الوحدة هذا المسار، ولا تتحقّق منه، ولا تركّبه — فذلك من عمل المُصيِّر.
• تُطابَق أسماء العناصر النائبة بصورة غير حسّاسة لحالة الأحرف؛ والأسماء المكرَّرة في ⁨JSON⁩ خطأ تحقّق.

الأداء

التحليل عملية فكّ ترميز ⁨JSON⁩ واحدة مع تحقّق بنيوي؛ والربط خطّي في عدد العناصر النائبة. راجِع performance_budget.

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

يُفكّ ترميز ⁨JSON⁩ بـJSON_THROW_ON_ERROR ويُتحقَّق منه مقابل قوائم سماح ثابتة قبل إنشاء TemplateDefinition. ولا تؤدّي الوحدة أي إدخال/إخراج ملفّي أو شبكي؛ ولا يُحلّ مسار backgroundPdf هنا، فتعود معالجة المسار وضبط الوصول إلى المُصيِّر.

المطابقة

لا يوجد لهذه الوحدة سطح مواصفة ⁨PDF⁩ مباشر: فهي تحلّل قالب ⁨JSON⁩ وتُنسِّق القيم. ومفردات حجم الصفحة والاتجاه اصطلاحات ⁨NextPDF⁩، لا بُنى ⁨PDF⁩ معيارية.

تراجُع ⁨Core⁩ / البديل

لا توجد طبقة تعريف قوالب في ⁨Core⁩. ولأجل بناء مستند أمري بالكامل، استخدم واجهات مستند ⁨Core⁩ وكاتبها مفتوحة المصدر مباشرةً. راجِع /modules/core/document/.

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

تعرّف هذه الوحدة القوالب وتربطها. ولا تؤدّي تنسيق دمج المراسلات، ولا جدولة المهام الدفعية، ولا التصيير؛ فتلك الشؤون خارج النطاق وتُعالَج في موضع آخر.

حدّ النشر

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

انظر أيضًا

• مرجع ⁨Template⁩
• ‏⁨Toc⁩
• ‏⁨Merge⁩
• نموذج مستند ⁨Core⁩