نظرة عامة على تكامل NextPDF مع Symfony

لمحة سريعة

nextpdf/symfony هي الحزمة الرسمية لـ ⁨Symfony 7⁩ الخاصة بمحرّك ⁨NextPDF.⁩ تربط المحرّك بحاوية ⁨Symfony⁩ وتوفّر مصنع مستندات يمكنك حقنه في خدماتك. كما تتضمّن أدوات مساعدة لاستجابات بروتوكول نقل النص التشعّبي (⁨HTTP⁩) ومساراً لتوليد ملفات تنسيق المستندات المحمولة (⁨PDF⁩) بشكل غير متزامن، بحيث يمكن تنفيذ العمل في الخلفية.

ما الذي توفّره الحزمة

تربط ⁨NextPDF Symfony⁩ محرّك nextpdf/core بتطبيق ⁨Symfony⁩ بوصفها حزمة قياسية. وتضيف المكوّنات الأساسية التالية، وقد جرى التحقّق من كلٍّ منها مقابل مصدر الحزمة في src/Symfony/:

• نقطة دخول الحزمة — NextPDF\Symfony\NextPdfBundle تمدّد فئة ⁨Symfony⁩ الأساسية Bundle وتسجّل ممرّ مُجمِّع واحداً.
• امتداد حقن التبعيات — NextPDF\Symfony\DependencyInjection\NextPdfExtension يحمّل تعريفات الخدمات، ويحوّل شجرة التهيئة إلى معاملات الحاوية، ويكشف الاسم المستعار للتهيئة nextpdf.
• شجرة تهيئة محدّدة الأنواع — NextPDF\Symfony\DependencyInjection\Configuration تعرّف مخطّط تهيئة nextpdf. وتتحقّق من قيم التعدادات، وتضبط القيم الافتراضية، وتستخدم نواب معاملات %kernel.*%.
• مصنع مستندات قابل للحقن — NextPDF\Symfony\Service\PdfFactory ينشئ نسخ NextPDF\Core\Document جديدة ومهيّأة مسبقاً. وهو المقابل في ⁨Symfony⁩ للواجهة الساكنة.
• أدوات مساعدة لاستجابات ⁨HTTP⁩ — NextPDF\Symfony\Http\PdfResponse ينشئ استجابات للعرض المضمّن والتنزيل والتدفّق، مع مجموعة ثابتة من ترويسات الأمان المتوافقة مع مشروع أمان تطبيقات الويب المفتوح عالمياً (⁨OWASP⁩).
• مسار توليد غير متزامن — تتكامل NextPDF\Symfony\Message\GeneratePdfMessage، وNextPDF\Symfony\Message\GeneratePdfHandler، وNextPDF\Symfony\Message\PdfBuilderInterface مع ⁨Symfony Messenger⁩ بحيث يمكن تنفيذ عرض ⁨PDF⁩ ضمن عامل.
• كاشف امتدادات في وقت التجميع — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass يرصد امتدادات ⁨NextPDF⁩ الاختيارية ويسجّل خدماتها فقط عند توفّر تلك الامتدادات.

عقد الحاوية

تسجّل الحزمة مجموعة صغيرة ومستقرّة من خدمات الحاوية العامة. خدمة المستند nextpdf.document (المسمّاة على نحوٍ بديل NextPDF\Contracts\PdfDocumentInterface وNextPDF\Core\Document) غير مشتركة: كل عملية حلّ تُرجع مستنداً مستقلاً قابلاً للتخلّص منه. يتوافق هذا مع عقد الحاوية في توصية معيار ⁨PHP⁩ رقم 11 (⁨PSR-11⁩): قد يُرجع استدعاءان متتاليان لـ get() بالمعرّف نفسه قيماً مختلفة تبعاً لتهيئة الحاوية — راجع ⁨PSR-11⁩ §1.1.2. الربط غير المشترك مقصود. يراكم المستند حالة خاصة بكل عملية عرض، لذا فإنّ توفير نسخة جديدة لكل طلب يمنع تسرّب الحالة عبر الطلبات في العمّال طويلي التشغيل.

يعمل سجلّ الخطوط (NextPDF\Contracts\FontRegistryInterface) بالطريقة المعاكسة: فهو نسخة مفردة مشتركة. يحمل سجلّ الصور وسم kernel.reset، لذا تُمسح ذاكرته المؤقتة المحدودة بين الطلبات في عمّال ⁨FrankenPHP⁩ و⁨Messenger.⁩ توثّق صفحة التهيئة الجدول الكامل للخدمات والأسماء البديلة.

التسجيل الاختياري

يقبل سجلّا الخطوط والصور مُسجِّلاً اختيارياً متوافقاً مع توصية معيار ⁨PHP⁩ رقم 3 (⁨PSR-3⁩). لا تربط الحزمة Psr\Log\LoggerInterface إلا عندما يوفّر التطبيق واحداً (nullOnInvalid()). لذلك يكون التسجيل دعماً تعاونياً اختيارياً، لا تبعية صارمة. يتّسق هذا مع عقد المُسجِّل في ⁨PSR-3⁩، حيث يكون المُسجِّل متعاوناً محقوناً وقابلاً للاستبدال (⁨PSR-3⁩).

الإمكانات الأساسية مقابل الاختيارية

الحزمة نفسها برمجية أساسية مرخّصة بموجب ⁨Apache-2.0.⁩ لا تظهر بعض الإمكانات إلا عند تثبيت حزمة اختيارية إلى جانبها:

الإمكانية	يتطلّب	الكشف
توليد ⁨PDF⁩، وPdfFactory، وPdfResponse	الأساسية فقط	متاحة دائماً
التوليد غير المتزامن	symfony/messenger	يُفعَّل المعالِج عند تثبيت ⁨Messenger⁩
عرض ⁨HTML⁩ عبر بروتوكول ⁨Chrome DevTools⁩ (⁨CDP⁩)	nextpdf/artisan	فحص class_exists في وقت التجميع
أرشفة ⁨PDF/A⁩، والتواقيع الرقمية	nextpdf/premium (يثبّت ⁨Pro⁩)	فحص class_exists في وقت التجميع

عند تثبيت nextpdf/premium، يمكن للحزمة تطبيق تهيئة توقيع أساسية وفق التواقيع الإلكترونية المتقدّمة لـ ⁨PDF⁩ (⁨PAdES⁩) ⁨B-B⁩. ملفّات تعريف التوقيع الأعلى مستوى خارج نطاق توثيق هذه الحزمة. للاطّلاع على مصفوفة الإصدارات، راجع توثيق ⁨NextPDF Premium.⁩

متى تستخدم هذه الحزمة

استخدم nextpdf/symfony عندما تنشئ ملفات ⁨PDF⁩ داخل تطبيق ⁨HTTP⁩ أو عامل على ⁨Symfony 7.⁩ تمنحك الحزمة خدمات مُدارة بالحاوية، وسجلّات آمنة للاستخدام في العمّال، واستجابات تنزيل آمنة، بحيث لا تحتاج إلى ربط المحرّك يدوياً. إذا كنت بحاجة فقط إلى توليد لمرّة واحدة داخل سكربت، فإنّ حزمة nextpdf/core الأساسية وحدها كافية.

المطابقة

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

المواصفة	البند	⁨reference_id⁩	الادّعاء
⁨PSR-11⁩	psr_11_container#1.1.2.p3.b		عقد قيمة الإرجاع لـ ⁨get⁩() في الحاوية
⁨PSR-3⁩	psr_3_logger#x3.p17		تبعية ⁨LoggerInterface⁩ الاختيارية

السياق التجاري

تصبح التواقيع الرقمية وأرشفة ⁨PDF/A⁩ متاحة عند تثبيت ⁨nextpdf/premium⁩ (⁨Pro⁩) إلى جانب الحزمة. لا تتطلّب إمكانية ⁨Pro⁩ الاختيارية هذه أيّ تغيير في شفرة الحزمة الأساسية الموثَّقة هنا. راجع </get-license/?intent=symfony-pro>.

انظر أيضاً

• /⁨integrations/symfony/install/⁩ — تثبيت الحزمة وتسجيلها.
• /⁨integrations/symfony/configuration/⁩ — شجرة تهيئة nextpdf الكاملة وجدول الخدمات.
• /⁨integrations/symfony/quickstart/⁩ — متحكّم قابل للتشغيل ومثال غير متزامن.
• /⁨integrations/symfony/boot-and-discovery/⁩ — كيف يكتشف ⁨Symfony⁩ الحزمة ويُشغّلها.
• /⁨integrations/symfony/production-usage/⁩ — أمان العمّال، والتدفّق، وأنماط التنفيذ غير المتزامن.