تكوين حزمة NextPDF لـ Laravel

لمحة سريعة

يُنشر config/nextpdf.php باستخدام php artisan vendor:publish --tag=nextpdf-config. لكل مفتاح متغير بيئة بديل وقيمة افتراضية مضمّنة في الشيفرة. تسرد هذه الصفحة كل مفتاح كما يظهر في config/nextpdf.php الخاص بالحزمة.

التثبيت

php artisan vendor:publish --tag=nextpdf-config

في أثناء register()، يدمج المزوِّد أيضًا القيم الافتراضية للحزمة ضمن مفتاح التكوين nextpdf. عندئذٍ ترجع المفاتيح غير المضبوطة إلى القيم أدناه، حتى قبل نشر ملف التكوين.

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

تقبل معظم متغيرات البيئة إمّا اسمًا بصيغة NEXTPDF_* وإمّا اسمًا قديمًا بصيغة TCPDF_*. تظل البادئة القديمة متاحة خلال الفترة الانتقالية الموثَّقة في UPGRADE.md. استخدم NEXTPDF_* في عمليات النشر الجديدة. يحلّ ملف التكوين القيم بهذا الترتيب: متغير البيئة ← قيمة الملف المنشور ← القيمة الافتراضية للحزمة.

سطح الواجهة البرمجية — مفاتيح التكوين

تخطيط المستند

المفتاح	متغير البيئة (الأساسي)	الافتراضي	الأثر
page_format	NEXTPDF_PAGE_FORMAT	A4	تنسيق الصفحة الافتراضي: ⁨A4⁩ أو ⁨A3⁩ أو ⁨A5⁩ أو ⁨Letter⁩ أو ⁨Legal⁩ أو ⁨Tabloid⁩
orientation	NEXTPDF_ORIENTATION	P	عمودي (P) أو أفقي (L)
unit	NEXTPDF_UNIT	mm	وحدة القياس: ⁨pt⁩ أو ⁨mm⁩ أو ⁨cm⁩ أو ⁨in⁩
defaults.creator	NEXTPDF_CREATOR	NextPDF	بيانات تعريف منشئ المستند؛ تُطبَّق على رابط PdfDocumentInterface
defaults.author	NEXTPDF_AUTHOR	(فارغ)	بيانات تعريف المؤلف؛ تُطبَّق فقط عندما تكون غير فارغة
defaults.language	NEXTPDF_LANG	en	لغة المستند؛ تُطبَّق على رابط المستند
defaults.margin_top / _right / _bottom / _left	—	10	الهوامش الافتراضية
defaults.font_family	—	dejavusans	عائلة الخط الافتراضية
defaults.font_size	—	12	حجم الخط الافتراضي
defaults.trim_box	—	null	⁨TrimBox⁩ بصيغة [left, bottom, right, top] بالنقاط، أو null
defaults.bleed_box	—	null	⁨BleedBox⁩ بصيغة [left, bottom, right, top] بالنقاط، أو null

يطبّق المزوِّد defaults.creator وdefaults.language، و(عند ضبطه) defaults.author على كل مستند يُحلّ حديثًا. ويتخطّى المزوِّد defaults.author عندما تكون القيمة فارغة.

الأرشفة واللون

المفتاح	متغير البيئة (الأساسي)	الافتراضي	الأثر
pdfa	NEXTPDF_PDFA	null	مستوى الأرشفة ⁨PDF/A⁩: null أو 4 أو 4e أو 4f. تُفعِّل أي قيمة غير ⁨null⁩ خاصية ⁨PDF/A⁩ على رابط المستند وتتطلّب nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	دليل خطوط ⁨TrueType⁩ الإضافية؛ يضبط مسار بحث سجلّ الخطوط
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	دليل ذاكرة التخزين المؤقتة للخطوط المُحلَّلة والملفات المؤقتة
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	مسار ملف تعريف ⁨ICC⁩ بنظام ⁨RGB⁩؛ مطلوب لـ ⁨PDF/A⁩
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	ملف تعريف ⁨ICC⁩ اختياري بنظام ⁨CMYK⁩ لسير عمل الطباعة
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	استخدم flock لذاكرة التخزين المؤقتة للخطوط لمنع التلف عند كتابة عمّال الطابور المتزامنين إليها

تتطلّب أي قيمة غير ⁨null⁩ لـ pdfa طبقة ⁨Premium.⁩ من دون nextpdf/premium، يؤدّي حلّ ربط المستند مع ضبط pdfa إلى رفع خطأ ⁨class-not-found⁩ لنوع إصدار ⁨PDF/A.⁩ هذه الصفحة لا توثّق سلوك الأرشفة في ⁨Premium.⁩ راجع وثائق ⁨Premium.⁩

ذاكرة العامل (أوقات التشغيل الطويلة الأمد)

المفتاح	متغير البيئة (الأساسي)	الافتراضي	الأثر
preload_fonts	—	[]	مسارات ملفات الخطوط المطلقة التي تُحلَّل عند إقلاع العامل. يُقفَل سجلّ الخطوط بعد التهيئة
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	ميزانية ذاكرة التخزين المؤقتة للصور بنظام الأقل استخدامًا مؤخرًا (⁨LRU⁩) بالميغابايت (⁨MB⁩). 0 يُعطِّل التخزين المؤقت. لا يُفرَض أي حدّ أعلى على مستوى المزوِّد

لا يفرض المزوِّد حدًا أعلى على ميزانية ذاكرة التخزين المؤقتة للصور. استخدم حدّ ذاكرة الحاوية أو php.inimemory_limit لتقييدها. يوصي ملف التكوين بحدّ أقصى عملي قدره 256 ⁨MB.⁩

التوقيع الرقمي (⁨Premium⁩)

المفتاح	متغير البيئة (الأساسي)	الافتراضي	الأثر
signature.enabled	NEXTPDF_SIGN_ENABLED	false	عندما تكون ⁨false⁩، أو تكون الشهادة فارغة، يُحلّ SignerInterface إلى null
signature.certificate	NEXTPDF_SIGN_CERT	null	مسار شهادة التوقيع
signature.private_key	NEXTPDF_SIGN_KEY	null	مسار المفتاح الخاص
signature.password	NEXTPDF_SIGN_PASSWORD	(فارغ)	عبارة مرور المفتاح
signature.extra_certs	—	[]	مسارات شهادات هيئة التصديق الوسيطة
signature.level	NEXTPDF_SIGN_LEVEL	B-B	مستوى الأساس للتوقيعات الإلكترونية المتقدمة لـ ⁨PDF⁩ (⁨PAdES⁩) الذي يُمرَّر إلى الموقِّع

لا تشحن الحزمة ⁨Core⁩ الموثَّقة هنا تنفيذًا للموقِّع؛ يُحلّ SignerInterface إلى null حتى يوفّر nextpdf/premium تنفيذًا له. مع ⁨Premium⁩، يُنتِج level: B-B توقيعًا بمستوى الأساس ⁨PAdES B-B.⁩ تعتمد مستويات الأساس ⁨PAdES⁩ الأعلى على هيئة طوابع زمنية مُكوَّنة وقدرة ⁨Premium⁩؛ هذه الصفحة لا توثّق تلك المستويات.

هيئة الطوابع الزمنية

المفتاح	متغير البيئة (الأساسي)	الافتراضي	الأثر
tsa.url	NEXTPDF_TSA_URL	null	نقطة نهاية هيئة الطوابع الزمنية (⁨TSA⁩). عندما تكون فارغة، يُحلّ TsaClient إلى null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(فارغ)	بيانات اعتماد ⁨TSA⁩ عبر ⁨HTTP⁩
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	شهادة العميل / مفتاحه لأمان طبقة النقل المتبادل (⁨mTLS⁩) مع ⁨TSA⁩
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	مهلة ⁨HTTP⁩ بالثواني لعميل ⁨PSR-18⁩
tsa.pinned_public_keys	—	[]	تثبيتات ⁨Base64 SHA-256⁩ لمعلومات المفتاح العام للموضوع (⁨SPKI⁩) (⁨RFC 7469⁩). القيمة الفارغة تُعطِّل التثبيت
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	إصدار تحذير عندما تقدّم ⁨TSA⁩ معلومات ⁨SPKI⁩ غير مُثبَّتة
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	السماح بـ ⁨HTTP⁩ نصّي صريح إلى ⁨TSA.⁩ اترك القيمة ⁨false⁩ في بيئة الإنتاج

ذاكرة التخزين المؤقتة لاستجابات ⁨OCSP⁩

المفتاح	متغير البيئة (الأساسي)	الافتراضي	الأثر
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	تخزين استجابات بروتوكول حالة الشهادة عبر الإنترنت (⁨OCSP⁩) مؤقتًا في أثناء التحقق
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	مدة بقاء ذاكرة التخزين المؤقتة (⁨TTL⁩) بالثواني
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	دليل ذاكرة التخزين المؤقتة؛ null يُبقي ذاكرة التخزين المؤقتة في الذاكرة فقط

الطابور

المفتاح	متغير البيئة (الأساسي)	الافتراضي	الأثر
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	اتصال الطابور؛ null يستخدم الاتصال الافتراضي
queue.queue	NEXTPDF_QUEUE_NAME	pdf	الطابور الذي تُدفَع إليه GeneratePdfJob
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	المهلة لكل مهمة بالثواني

مُصيِّر ⁨Chrome CDP⁩ (امتداد ⁨Artisan⁩)

المفتاح	متغير البيئة (الأساسي)	الافتراضي	الأثر
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	قيمة البيئة أو غير مضبوط	مسار ثنائي ⁨Chrome/Chromium⁩
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	مهلة التصيير بالثواني
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(فارغ)	⁨CSS⁩ الافتراضي المحقون في ⁨HTML⁩ المُصيَّر
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	تعطيل صندوق حماية ⁨Chrome⁩
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	الحجم الأقصى لإدخال ⁨HTML⁩ بالبايت

ينطبق القسم artisan على رابط المستند فقط عند وجود صنف مصنع متصفح ⁨Chrome⁩ (امتداد nextpdf/artisan). وعند غياب ذلك الصنف، يُتجاهَل القسم.

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

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

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

• signature.enabled = true مع signature.certificate فارغة يظل يحلّ SignerInterface إلى null؛ يجب ضبط كلتا القيمتين.
• tsa.url = null يفرض TsaClient إلى null، حتى لو كانت مفاتيح tsa.* الأخرى مملوءة.
• signature.level = null يعود إلى ⁨PAdES B-B⁩ على الموقِّع.
• ضبط image_cache_mb على null (وليس 0) يعود إلى القيمة الافتراضية 50 ⁨MB⁩؛ 0 يُعطِّل التخزين المؤقت صراحةً.
• تظلّ متغيرات البيئة القديمة TCPDF_* قابلة للقراءة لكنها مهملة. انتقل إلى NEXTPDF_*.

الأداء

تستخدم قراءة التكوين وصولًا إلى المصفوفة بزمن ⁨O⁩(1). يبادل preload_fonts تحليلًا لمرة واحدة بزمن ⁨O⁩(⁨f⁩) عند إقلاع العامل بزمن استجابة أقل لأول طلب. وتقلّل قيمة image_cache_mb الأكبر إعادة فكّ ترميز الصور على حساب الذاكرة المقيمة في العملية.

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

يُضعِف tsa.allow_insecure_http الثقة بالطوابع الزمنية ويجب أن يبقى false في بيئة الإنتاج. يجب أن تأتي عناوين ⁨TSA⁩ من تكوين موثوق فقط. إذا كشفتها عبر سطح إداري، فاستخدم جدار حماية للصادر أو سياسة ⁨DNS⁩ للتخفيف من تزوير الطلبات. راجع /⁨integrations/laravel/security-and-operations/.⁩

المطابقة

لا يحكم أي معيار قياسي شكل ملف التكوين. جميع المفاتيح مُتحقَّق منها مقابل config/nextpdf.php الخاص بالحزمة عند المراجعة الموثَّقة. تضبط ⁨Premium⁩ دلالات مستوى التوقيع، وهي خارج نطاق صفحة ⁨Core⁩ هذه.

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

يقود قسما ⁨signature⁩ و⁨tsa⁩ التوقيع في ⁨Premium⁩ عند تثبيت ⁨nextpdf/premium.⁩ لا تتطلّب هذه القدرة الاختيارية على مستوى ⁨Enterprise⁩ أي تغييرات في شيفرة حزمة ⁨Core.⁩ راجع https://nextpdf.dev/get-license/?intent=laravel-signing.

انظر أيضًا

• /⁨integrations/laravel/install/⁩ — انشر ملف التكوين
• /⁨integrations/laravel/production-usage/⁩ — اطّلع على التكوين مطبَّقًا في وحدة تحكّم حقيقية
• /⁨integrations/laravel/security-and-operations/⁩ — عزّز أمان إعدادات ⁨TSA⁩ والطابور
• /⁨integrations/laravel/boot-and-discovery/⁩ — اطّلع على الربط الذي يقوده كل مفتاح