إقلاع NextPDF واكتشافه داخل Symfony

لمحة سريعة

تسجّل النواة NextPdfBundle. يحمّل امتداد حقن التبعيات (⁨DI⁩) الخاص بالحزمة الملف services.php، ويحلّ شجرة التهيئة إلى معاملات الحاوية. بعد ذلك، يربط ممرّ مُصرِّف واحد الامتدادات الاختيارية والإحماء المسبق للخطوط.

كيف يلتقط ⁨Symfony Flex⁩ الحزمة

يُعلن ملف composer.json الخاص بالحزمة عن تلميح للتسجيل التلقائي:

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

في تطبيق ⁨Symfony Flex⁩، يضيف هذا التلميح NextPDF\Symfony\NextPdfBundle إلى config/bundles.php لكل بيئة (all). من دون ⁨Flex⁩، أضف الحزمة يدويًا في config/bundles.php. يوثّق ⁨Symfony⁩ نموذج تسجيل الحزم في (https://symfony.com/doc/current/bundles.html). تُحمَّل أصناف الحزمة تلقائيًا تحت بادئة توصية ⁨PHP⁩ المعيارية (⁨PSR⁩)‏-4، وهي NextPDF\Symfony\، المرتبطة بـ src/Symfony/. يربط محمِّل ⁨PSR-4⁩ التلقائي بادئة فضاء الأسماء بهذا الدليل الأساسي (⁨PSR-4⁩ §2).

تسلسل الإقلاع

تسلسل الإقلاع، بعد التحقّق منه مقابل مصدر الحزمة:

1. النواة تُسجّل الحزم. يقرأ Kernel::registerBundles() الملف config/bundles.php وينشئ نسخة من NextPDF\Symfony\NextPdfBundle، الذي يَرِث من Symfony\Component\HttpKernel\Bundle\Bundle.
2. بناء الحزمة. يستدعي NextPdfBundle::build() الطريقة الأم، ثم يسجّل ممرّ مُصرِّف واحدًا: OptionalExtensionPass. يعيد NextPdfBundle::getPath() جذر الحزمة.
3. تحميل الامتداد. يشغّل امتداد حقن التبعيات NextPDF\Symfony\DependencyInjection\NextPdfExtension (اللقب nextpdf) الدالة processConfiguration() مقابل Configuration. يخزّن القيم المحلولة بوصفها معاملات حاوية nextpdf.*، ثم يحمّل config/services.php عبر PhpFileLoader.
4. حارس الامتدادات المطلوبة. يُنهي NextPdfExtension::load() عمله بالتأكد من توفّر ext-mbstring وext-zlib، ويفشل فورًا إذا لم يكونا موجودين.
5. ممرّ المُصرِّف يعمل. أثناء تصريف الحاوية، يهيّئ OptionalExtensionPass::process() أعلام توفّر الامتدادات على PdfFactory، ويسجّل شرطيًا عميل المُوقِّع وسلطة الختم الزمني (⁨TSA⁩)، ويجدول الإحماء المسبق لسجلّ الخطوط وقفله.
6. الحاوية مُصرَّفة ومُخزَّنة مؤقتًا. يكتب ⁨Symfony⁩ الحاوية المُصرَّفة. ينفّذ cache:warmup هذه الخطوة قبل وصول حركة المرور إلى التطبيق.

ممرّات المُصرِّف

تُسجّل الحزمة ممرًّا واحدًا بالضبط، وهو NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass، في NextPdfBundle::build(). يعمل ضمن مجموعة الممرّات الافتراضية (ما قبل التحسين). ينفّذ الممرّ أربع خطوات. كل خطوة محروسة، فلا تفعل شيئًا عند غياب مدخلاتها:

• أعلام الامتدادات — يضيف استدعاءَي الطريقتين setArtisanAvailable(...) وsetProAvailable(...) إلى تعريف PdfFactory. تأتي القيم من فحوص class_exists وقت التصريف لمصنع متصفّح ⁨Artisan⁩ وصنف ⁨PDF/A⁩ في إصدار ⁨Pro.⁩
• تسجيل المُوقِّع — يسجّل مصنع معلومات الشهادة وخدمة مُوقِّع لملف التعريف الأساسي ⁨B-B⁩ عندما يكون nextpdf.signature موجودًا، وenabled صحيحًا، وكانت الشهادة مضبوطة.
• عميل ⁨TSA⁩ — يسجّل خدمة عميل ⁨TSA⁩ عندما يكون لدى nextpdf.tsa محدِّد موارد موحّد (⁨URL⁩).
• الإحماء المسبق للخطوط — يضيف استدعاءَي الطريقتين warmup() وlock() إلى تعريف سجلّ الخطوط عندما يكون nextpdf.preload_fonts غير فارغ.

ارتباطات الحاوية

يعرّف config/services.php الخدمات. خدمة المستند nextpdf.document (المُلقَّبة بـ NextPDF\Contracts\PdfDocumentInterface وNextPDF\Core\Document) غير مشتركة: تعيد كل عملية حلٍّ مستندًا جديدًا. يجيز ⁨PSR-11⁩ هذا السلوك صراحةً؛ فقد تعيد استدعاءات get() المتتالية لمعرّف واحد قيمًا مختلفة (⁨PSR-11⁩ §1.1.2). سجلّ الخطوط مشترك ومقفول بعد الإحماء المسبق. سجلّ الصور مشترك ومُوسَّم بـ kernel.reset. الجدول الكامل موجود في /⁨integrations/symfony/configuration/.⁩

ترتيب حلّ التهيئة

1. القيم الافتراضية المضمّنة من Configuration (getConfigTreeBuilder()).
2. تجاوزات التطبيق في config/packages/nextpdf.yaml، بالإضافة إلى تجاوزات البيئة تحت config/packages/<env>/.
3. يحلّ ⁨Symfony⁩ العناصر النائبة للمعاملات %kernel.*%. على سبيل المثال، يحصل fonts_path على القيمة الافتراضية %kernel.project_dir%/resources/fonts.
4. يكتب NextPdfExtension::load() النتيجة المدموجة إلى معاملات الحاوية nextpdf.* التي يستهلكها services.php وممرّ المُصرِّف.

تفشل القيم غير الصالحة في الخطوة 1–2 عندما يرمي ⁨Symfony⁩ استثناء InvalidConfigurationException.

التشخيص

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

يسرد الأمر الأول الخدمات المسجَّلة. ويطبع الثاني التهيئة المدموجة. ويعيد الثالث بناء الحاوية وتشغيل فحوص الامتدادات وقت التصريف من جديد.

المطابقة

كل صف يمثّل ادعاءً معياريًا في هذه الصفحة، مُثبَّتًا بـ reference_id كامل من 64 خانة سداسية عشرية من متن منظمة تطوير المعايير (⁨SDO⁩) المُقيَّد. يوجد المنشأ (بيان المتن، نقل الاسترجاع) في _sidecars/rag-citations.yaml.

المواصفة	البند	⁨reference_id⁩	الادعاء
⁨PSR-11⁩	psr_11_container#1.1.2.p3.b		قد يختلف حلّ الحاوية مع كل استدعاء
⁨PSR-4⁩	psr_4_autoload#x1.x2.p5		ربط بادئة فضاء الأسماء بالدليل الأساسي

انظر أيضًا

• /⁨integrations/symfony/integration/⁩ — مرجع الربط الكامل من البداية إلى النهاية.
• /⁨integrations/symfony/install/⁩ — التثبيت والتسجيل.
• /⁨integrations/symfony/configuration/⁩ — شجرة التهيئة الكاملة وجدول الخدمات.
• /⁨integrations/symfony/overview/⁩ — ملخّص القدرات.