تثبيت حزمة NextPDF لـ Symfony

لمحة سريعة

ثبّت الحزمة باستخدام ⁨Composer.⁩ إذا كان تطبيقك يستخدم ⁨Symfony Flex⁩، فستسجّل الحزمة نفسها تلقائيًا. أما بدون ⁨Flex⁩، فسجّلها مرة واحدة في config/bundles.php.

المتطلبات

يحدّد ملف composer.json الخاص بالحزمة هذه القيود.

الاعتمادية	القيد
`php`	`>=8.4 <9.0`
`nextpdf/core`	`^3.0 \|\| ^5.2`
`symfony/framework-bundle`	`^7.2`
`symfony/dependency-injection`	`^7.2`
`symfony/config`	`^7.2`
`symfony/http-foundation`	`^7.2`
`psr/log`	`^3.0`

تتحقّق الحزمة أيضًا من امتدادين لـ ⁨PHP⁩ عند إنشاء الحاوية: ext-mbstring وext-zlib. تُفعّل كل بيئة تشغيل ⁨PHP⁩ مدعومة كليهما. وإذا غاب أي من الامتدادين، يفشل حارس التحقّق مبكرًا مع رسالة واضحة.

الحزم الاختيارية

يُعلن ملف composer.json الخاص بالحزمة عن هذه الحزم ضمن suggest. أضِفها عندما تحتاج إلى السلوك الذي توفّره:

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

التثبيت باستخدام ⁨Composer⁩

composer require nextpdf/symfony

تُحمّل الحزمة تلقائيًا ضمن البادئة NextPDF\Symfony\ وفق توصية ⁨PHP⁩ المعيارية 4 (⁨PSR-4⁩)، وهي مرتبطة بـ src/Symfony/. يُعلَن عن هذا الارتباط في composer.jsonautoload.psr-4. يربط المُحمّل التلقائي الذي يُولّده ⁨Composer⁩ بادئة مساحة الأسماء بذلك الدليل الأساسي، كما يعرّفه ⁨PSR-4⁩ §2.

تسجيل الحزمة

⁨Symfony Flex⁩ (مُستحسَن)

تتضمّن الحزمة تلميحًا للتسجيل التلقائي داخل composer.json:

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

في تطبيق مُفعَّل فيه ⁨Flex⁩، يُضيف هذا المُدخل الحزمة إلى config/bundles.php لكل بيئة (all). لا تحتاج إلى تحرير الملف يدويًا. للاطّلاع على نموذج التسجيل، راجع وثائق حزم ⁨Symfony⁩ الرسمية (https://symfony.com/doc/current/bundles.html).

التسجيل اليدوي (بدون ⁨Flex⁩)

إذا كان تطبيقك لا يستخدم ⁨Symfony Flex⁩، فأضِف الحزمة إلى config/bundles.php بنفسك:

return [
    // ... other bundles
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

صنف الحزمة هو NextPDF\Symfony\NextPdfBundle. وهو يرث من الصنف الأساسي Symfony\Component\HttpKernel\Bundle\Bundle في ⁨Symfony.⁩ تُعيد طريقة getPath() الخاصة بالحزمة جذر الحزمة. وتُسجّل طريقة build() الخاصة به ممرّ المُترجِم OptionalExtensionPass.

توفير ملف الإعداد

الاسم المُستعار لإعداد الحزمة هو nextpdf. أنشئ config/packages/nextpdf.yaml. عند النشر، تُضيف وصفة ⁨Flex⁩ نسخة افتراضية هنا نيابةً عنك. ويبدو الملف المُصغّر الذي يعتمد كليًا على القيم الافتراضية المُدمجة كما يلي:

nextpdf: ~

لكل مفتاح قيمة افتراضية، لذا يكون الإعداد الفارغ صالحًا. توثّق صفحة /⁨integrations/symfony/configuration/⁩ شجرة الإعداد الكاملة.

التحقّق من التثبيت

تأكّد من أن الحاوية تستطيع رؤية خدمات الحزمة:

php bin/console debug:container nextpdf

من المُفترض أن ترى خدمات تتضمّن الاسم المُستعار nextpdf.document وNextPDF\Symfony\Service\PdfFactory. ولفحص الإعداد بعد تحليله، نفّذ:

php bin/console debug:config nextpdf

يطبع هذا شجرة الإعداد المُدمجة: تجاوزاتك مع القيم الافتراضية.

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

نطاق قيد النواة — تقبل الحزمة nextpdf/core^3.0 || ^5.2. يحلّ ⁨Composer⁩ الإصدار الذي يلبّي بقية مخطط اعتمادياتك. ثبّت إصدارًا رئيسيًا واحدًا في composer.json الخاص بتطبيقك إذا احتجت إلى إصدار محرّك حتمي.
حارس الامتداد المفقود — إذا فشل php bin/console عند الإقلاع مع رسالة بخصوص ext-mbstring أو ext-zlib، فعّل الامتداد المذكور في php.ini. سلوك الفشل المبكر هذا مقصود، وليس عيبًا في الحزمة.
لم يسجّل ⁨Flex⁩ الحزمة — امسح ذاكرة ⁨Composer⁩ المؤقتة وأعِد التثبيت. إذا كنت لا تستخدم ⁨Flex⁩، فاتّبع خطوة config/bundles.php اليدوية.

المطابقة

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

المواصفة	البند	⁨reference_id⁩	الادّعاء
⁨PSR-4⁩	`psr_4_autoload#x1.x2.p5`		ربط بادئة مساحة الأسماء بالدليل في المُحمّل التلقائي

انظر أيضًا

/⁨integrations/symfony/overview/⁩ — ما تقدّمه الحزمة.
/⁨integrations/symfony/configuration/⁩ — شجرة الإعداد الكاملة وجدول الخدمات.
/⁨integrations/symfony/quickstart/⁩ — أول وحدة تحكّم قابلة للتشغيل.
/⁨integrations/symfony/boot-and-discovery/⁩ — تسلسل الاكتشاف والإقلاع بالتفصيل.