تهيئة حزمة NextPDF لـ Symfony

لمحة سريعة

اضبط سلوك الحزمة كله تحت مفتاح الجذر nextpdf في config/packages/nextpdf.yaml. لكل مفتاح قيمة افتراضية، لذلك لا تضبط إلا القيم التي تريد تغييرها. تعكس هذه الصفحة Configuration.php بدقة.

شجرة الإعداد

يحدّد NextPDF\Symfony\DependencyInjection\Configuration المخطط. تفشل القيم غير الصالحة أثناء بناء الحاوية، مع طرح InvalidConfigurationException من ⁨Symfony.⁩

المفاتيح العليا

المفتاح	النوع	الافتراضي	التحقق
`page_format`	⁨enum⁩	`A4`	واحد من `A4`، `A3`، `A5`، `Letter`، `Legal`، `Tabloid`
`orientation`	⁨enum⁩	`P`	واحد من `P`، `L`
`unit`	⁨enum⁩	`mm`	واحد من `pt`، `mm`، `cm`، `in`
`pdfa`	⁨scalar⁩	`null`	واحد من `null`، `4`، `4e`، `4f`
`fonts_path`	⁨scalar⁩	`%kernel.project_dir%/resources/fonts`	—
`cache_path`	⁨scalar⁩	`%kernel.cache_dir%/nextpdf`	—
`image_cache_mb`	⁨integer⁩	`50`	الحد الأدنى `0`
`font_cache_locking`	⁨boolean⁩	`true`	—
`preload_fonts`	قائمة سلاسل نصية	`[]`	—

`icc_profile`

المفتاح	النوع	الافتراضي
`icc_profile.rgb`	⁨scalar⁩	`null`
`icc_profile.cmyk`	⁨scalar⁩	`null`

`defaults`

ينطبق هذا القسم على كل مستند يُنتجه PdfFactory.

المفتاح	النوع	الافتراضي
`defaults.creator`	⁨scalar⁩	`NextPDF`
`defaults.author`	⁨scalar⁩	(فارغ)
`defaults.language`	⁨scalar⁩	`en`
`defaults.margin_top`	⁨float⁩	`10.0`
`defaults.margin_right`	⁨float⁩	`10.0`
`defaults.margin_bottom`	⁨float⁩	`10.0`
`defaults.margin_left`	⁨float⁩	`10.0`
`defaults.font_family`	⁨scalar⁩	`dejavusans`
`defaults.font_size`	⁨float⁩	`12.0`
`defaults.trim_box`	⁨variable⁩	`null`
`defaults.bleed_box`	⁨variable⁩	`null`

يقرأ PdfFactory القيم creator وauthor وlanguage من هذا القسم ويطبّقها على كل مستند جديد. وتخزّن الحزمة المفاتيح المتبقية كمعامِلات للحاوية كي يستخدمها المحرّك.

`artisan`

ينطبق فقط عند تثبيت nextpdf/artisan واكتشافه بنجاح.

المفتاح	النوع	الافتراضي
`artisan.chrome_binary`	⁨scalar⁩	`null`
`artisan.render_timeout`	⁨integer⁩	`30`
`artisan.default_css`	⁨scalar⁩	(فارغ)
`artisan.no_sandbox`	⁨boolean⁩	`false`
`artisan.max_html_size`	⁨integer⁩	`5000000`

`signature`

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

المفتاح	النوع	الافتراضي	التحقق
`signature.enabled`	⁨boolean⁩	`false`	—
`signature.certificate`	⁨scalar⁩	`null`	—
`signature.private_key`	⁨scalar⁩	`null`	—
`signature.password`	⁨scalar⁩	(فارغ)	—
`signature.extra_certs`	قائمة سلاسل نصية	`[]`	—
`signature.level`	⁨enum⁩	`B-B`	المجموعة المقبولة: `B-B`، `B-T`، `B-LT`، `B-LTA` (⁨B-B⁩ مدعومة؛ `B-T`/`B-LT`/`B-LTA` قيم لتوافق المخطط، وليست قدرات ⁨Pro⁩ مدعومة)

لا تسجّل تمريرة المُصرِّف خدمة موقِّع إلا عندما يكون signature.enabled صحيحًا و يكون signature.certificate مضبوطًا؛ وإلا فيبقى القسم خاملًا.

`tsa`

إعداد عميل سلطة الطابع الزمني (⁨Time Stamp Authority⁩، ⁨TSA⁩)، وتستخدمه ميزة توقيع ⁨Pro⁩ عند تهيئتها.

المفتاح	النوع	الافتراضي
`tsa.url`	⁨scalar⁩	`null`
`tsa.username`	⁨scalar⁩	(فارغ)
`tsa.password`	⁨scalar⁩	(فارغ)
`tsa.cert`	⁨scalar⁩	`null`
`tsa.key`	⁨scalar⁩	`null`
`tsa.timeout`	⁨integer⁩	`30`
`tsa.allow_insecure_http`	⁨boolean⁩	`false`
`tsa.pinned_public_keys`	قائمة سلاسل نصية	`[]`
`tsa.warn_on_key_rotation`	⁨boolean⁩	`true`

لا تسجّل الحزمة خدمة عميل ⁨TSA⁩ إلا عند ضبط tsa.url.

`ocsp_cache`

المفتاح	النوع	الافتراضي
`ocsp_cache.enabled`	⁨boolean⁩	`true`
`ocsp_cache.ttl`	⁨integer⁩	`86400`
`ocsp_cache.directory`	⁨scalar⁩	`null`

`messenger`

إعدادات التوليد غير المتزامن، وتُستخدم عند تثبيت symfony/messenger.

المفتاح	النوع	الافتراضي
`messenger.transport`	⁨scalar⁩	`async`
`messenger.timeout`	⁨integer⁩	`120`
`messenger.retries`	⁨integer⁩	`3`

إعداد مرجعي

ملف إعداد يعرض كل قسم مع قيمه الافتراضية:

nextpdf:
    page_format: A4
    orientation: P
    unit: mm
    pdfa: ~
    fonts_path: '%kernel.project_dir%/resources/fonts'
    cache_path: '%kernel.cache_dir%/nextpdf'
    image_cache_mb: 50
    font_cache_locking: true
    preload_fonts: []
    icc_profile:
        rgb: ~
        cmyk: ~
    defaults:
        creator: NextPDF
        author: ''
        language: en
        margin_top: 10.0
        margin_right: 10.0
        margin_bottom: 10.0
        margin_left: 10.0
        font_family: dejavusans
        font_size: 12.0
        trim_box: ~
        bleed_box: ~
    artisan:
        chrome_binary: ~
        render_timeout: 30
        default_css: ''
        no_sandbox: false
        max_html_size: 5000000
    signature:
        enabled: false
        certificate: ~
        private_key: ~
        password: ''
        extra_certs: []
        level: B-B
    tsa:
        url: ~
        username: ''
        password: ''
        cert: ~
        key: ~
        timeout: 30
        allow_insecure_http: false
        pinned_public_keys: []
        warn_on_key_rotation: true
    ocsp_cache:
        enabled: true
        ttl: 86400
        directory: ~
    messenger:
        transport: async
        timeout: 120
        retries: 3

خدمات الحاوية وأسماؤها البديلة

تحمّل الحزمة تعريفات خدماتها من config/services.php. يعكس الجدول أدناه ذلك الملف بدقة.

معرّف الخدمة	مشترك	عام	ملاحظات
`NextPDF\Typography\FontRegistry`	نعم	—	يُنشأ من `nextpdf.fonts_path`؛ مُسجِّل ⁨PHP Standard Recommendation 3⁩ (⁨PSR-3⁩) اختياري
`NextPDF\Contracts\FontRegistryInterface`	(اسم بديل)	نعم	اسم بديل لـ `FontRegistry`
`NextPDF\Graphics\ImageRegistry`	نعم	—	الأقل استخدامًا مؤخرًا (⁨LRU⁩) محدود؛ موسوم بـ `kernel.reset` (`reset`)
`NextPDF\Core\DocumentFactory`	نعم	—	يشارك السجلّين
`NextPDF\Contracts\DocumentFactoryInterface`	(اسم بديل)	نعم	اسم بديل لـ `DocumentFactory`
`NextPDF\Symfony\Service\PdfFactory`	نعم	نعم	يقرأ المعامِلات `defaults` و`pdfa` و`artisan`
`NextPDF\Contracts\PdfDocumentInterface`	لا	نعم	مصنع `[PdfFactory, create]`
`NextPDF\Core\Document`	(اسم بديل)	—	اسم بديل لـ `PdfDocumentInterface`
`nextpdf.document`	(اسم بديل)	نعم	اسم بديل لـ `PdfDocumentInterface`
`NextPDF\Symfony\Http\PdfResponse`	—	نعم	مساعد بلا حالة

تسجّل الحزمة أيضًا روابط عقد ⁨EInvoice⁩ (EmbedderInterface، ValidatorInterface، ProfileInterface، SchematronRunnerInterface) فقط عند وجود فئات التنفيذ المقابلة في ⁨Premium.⁩ كل خدمة غير مشتركة، لذلك يتلقى المستدعون نسخة جديدة. ولا تتسرب حالة المحلّل الخاصة بكل استدعاء عبر الطلبات أبدًا.

المشترك مقابل غير المشترك

nextpdf.document (وأسماؤه البديلة) غير مشترك: تعيد كل عملية تحليل في الحاوية مستندًا مستقلًا. بموجب ⁨PHP Standard Recommendation 11⁩ (⁨PSR-11⁩)، يجوز للحاوية أن تعيد قيمة مختلفة عند استدعاءات get() المتتالية بالمعرّف نفسه؛ انظر ⁨PSR-11⁩ §1.1.2. سجل الخطوط مشترك ويُقفَل بعد الإحماء. تُحلَّل بيانات الخط البنيوية مرة واحدة لكل عملية، ولا يمكن تغييرها أثناء الطلب.

تقبل خدمتا FontRegistry وImageRegistry كائن Psr\Log\LoggerInterface اختياريًا؛ ويربطه ⁨Symfony⁩ بـ nullOnInvalid(). يبقى المُسجِّل متعاونًا اختياريًا قابلًا للاستبدال، بما يتوافق مع عقد المُسجِّل في ⁨PSR-3.⁩

الربط التلقائي

PdfFactory وPdfResponse وواجهة مصنع المستند وواجهة سجل الخطوط كلها عامة. يمكنك جلبها من الحاوية أو التصريح بأنواعها في وحدات التحكم والخدمات المربوطة تلقائيًا. حقن NextPDF\Symfony\Service\PdfFactory عبر المُنشئ هو نقطة الدخول المُوصى بها.

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

pdfa مضبوط دون ⁨Pro⁩ — تُخزَّن القيمة لكنها تُهمَل. يطبّق PdfFactory صيغة ⁨Portable Document Format/Archival⁩ (⁨PDF/A⁩) فقط عند اكتشاف امتداد ⁨Pro⁩ وقت التصريف.
image_cache_mb: 0 — صالح؛ يعطّل ذاكرة التخزين المؤقت ⁨LRU⁩ للصور. تُرفَض القيم السالبة وقت البناء.
signature.enabled: true دون signature.certificate — لا تُسجَّل خدمة الموقِّع؛ يبقى الإعداد خاملًا بصمت وفق التصميم.
عناصر %kernel.*% النائبة — تستخدم القيم الافتراضية لـ fonts_path وcache_path معامِلات حاوية ⁨Symfony⁩؛ تجاوزها بمسارات مطلقة فقط عند الحاجة إلى المسار الحرفي.

المطابقة

كل صف هو ادعاء معياري في هذه الصفحة، ومدعوم بـ 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⁩ اختياري

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

ينطبق قسما ⁨signature⁩ و⁨tsa⁩ فقط عند تثبيت ⁨nextpdf/premium⁩ (⁨Pro⁩). لا تتطلب قدرة ⁨Pro⁩ الاختيارية هذه أي تغيير في التعليمات البرمجية داخل حزمة ⁨Core⁩ الموثّقة هنا. انظر </get-license/?intent=symfony-pro>.

انظر أيضًا

/⁨integrations/symfony/install/⁩ — ثبّت الحزمة وسجّلها.
/⁨integrations/symfony/overview/⁩ — راجع ملخص القدرات.
/⁨integrations/symfony/production-usage/⁩ — سلامة العمال والأنماط غير المتزامنة.
/⁨integrations/symfony/boot-and-discovery/⁩ — تعرّف إلى كيفية حلّ الإعداد أثناء الإقلاع.