تهيئة NextPDF مع CodeIgniter 4

لمحة سريعة

تقع تهيئة ⁨NextPDF⁩ في NextPDF\CodeIgniter\Config\NextPdf، وهي فئة فرعية من BaseConfig في ⁨CodeIgniter.⁩ يمكنك تجاوز القيم بتوسيع الفئة داخل app/Config/ أو بضبط مفاتيح .env بالبادئة nextpdf.. تعمل القيم الافتراضية دون أي تهيئة إضافية.

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

NextPdf هي BaseConfig ذات أنواع محدَّدة. وهي غير نهائية عمدًا. في ⁨CodeIgniter⁩، توسِّع تهيئة التطبيق فئة الحزمة حتى يستطيع تطبيقك تجاوز القيم الافتراضية. عند إنشاء ⁨CodeIgniter⁩ للتهيئة، تحلِّل BaseConfig تجاوزات البيئة لكل خاصية عامة، بما في ذلك مفاتيح المصفوفات المتداخلة.

يستخدم مسارا الخطوط والتخزين المؤقت الافتراضيان ثابت WRITEPATH في ⁨CodeIgniter⁩: WRITEPATH . 'fonts' وWRITEPATH . 'cache/nextpdf'.

مفاتيح التهيئة

كل مفتاح أدناه هو خاصية عامة في NextPdf. وقد تم التحقق من القيم الافتراضية مقابل مصدر الحزمة.

القيم الافتراضية للصفحة والمستند

المفتاح	النوع	الافتراضي	الوصف
pageFormat	string	A4	تنسيق الصفحة.
orientation	string	P	P طولي أو L عرضي.
unit	string	mm	وحدة القياس.
defaults.creator	string	NextPDF	بيانات وصفية لمنشئ مستند ⁨PDF⁩.
defaults.author	string	''	بيانات وصفية للمؤلف؛ تُتجاوَز عندما تكون فارغة.
defaults.language	string	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	string	dejavusans	عائلة الخط الافتراضية.
defaults.font_size	float	12.0	حجم الخط الافتراضي.
defaults.trim_box	list<float>|null	null	مربع الاقتصاص، عند ضبطه.
defaults.bleed_box	list<float>|null	null	مربع النزف، عند ضبطه.

تطبِّق الحزمة defaults.creator وdefaults.language على كل مستند. ولا تطبِّق defaults.author إلا عندما تكون القيمة غير فارغة.

المسارات والتخزين المؤقت

المفتاح	النوع	الافتراضي	الوصف
fontsPath	string	WRITEPATH/fonts	دليل ملفات الخطوط.
cachePath	string	WRITEPATH/cache/nextpdf	دليل التخزين المؤقت.
preloadFonts	list<string>	[]	مسارات خطوط مطلقة تُسخَّن عند بدء التشغيل.
imageCacheMb	int	50	حد ميزانية التخزين المؤقت للصور بنمط الأقل استخدامًا مؤخرًا (⁨LRU⁩)، بالميغابايت (⁨MB⁩).
fontCacheLocking	bool	true	قفل التخزين المؤقت للخطوط بعد التسخين.

يرفض سجل الخطوط أي fontsPath يحتوي على مغلِّف تدفق (://) أو بايت فارغ (⁨null byte⁩)، ويطرح خطأ وقت تشغيل. راجع /⁨integrations/codeigniter/security-and-operations/.⁩

الأرشفة والألوان (⁨NextPDF Pro⁩)

المفتاح	النوع	الافتراضي	الوصف
pdfa	string|null	null	إصدار ⁨PDF/A⁩: 4، 4e، 4f.
iccProfile.rgb	string|null	null	مسار ملف تعريف اتحاد الألوان الدولي (⁨ICC⁩) للأحمر والأخضر والأزرق (⁨RGB⁩).
iccProfile.cmyk	string|null	null	مسار ملف تعريف ⁨ICC⁩ للسماوي والأرجواني والأصفر والأسود (⁨CMYK⁩).

لا يسري مفعول pdfa إلا عند تثبيت ⁨NextPDF Pro⁩ وتوفُّر قدرة الأرشفة. عند استخدام النواة وحدها، يجري تجاهل المفتاح.

التوقيع الرقمي (⁨NextPDF Pro⁩ / ⁨Enterprise⁩)

المفتاح	النوع	الافتراضي	الوصف
signature.enabled	bool	false	تفعيل خدمة الموقِّع.
signature.certificate	string|null	null	مسار ملف الشهادة.
signature.private_key	string|null	null	مسار ملف المفتاح الخاص.
signature.password	string	''	كلمة مرور المفتاح الخاص.
signature.extra_certs	list<string>	[]	مسارات شهادات إضافية للسلسلة.
signature.level	string	B-B	مُعرِّف مستوى التوقيع.

تُرجع Services::pdfSigner() القيمة null ما لم تكن signature.enabled بقيمة true وكانت signature.certificate غير فارغة. المستوى الافتراضي هو B-B. يوفِّر ⁨NextPDF Pro⁩ توقيع ⁨B-B⁩ الأساسي. أما مستويات التحقق طويل الأمد فهي قدرة ⁨Enterprise⁩ منفصلة، وهي موثَّقة في مرجع ⁨Premium⁩، وليس هنا.

يُنتِج محرك ⁨Core⁩ التوقيعات الإلكترونية المتقدمة لـ ⁨PDF⁩ (⁨PAdES⁩) ⁨B-T⁩. لا يضيف تكامل ⁨CodeIgniter⁩ بذاته ⁨B-T⁩، ويقدِّم ⁨Pro⁩ التوقيع الأساسي ⁨B-B⁩ فقط. سيجري تحديث هذه الوثائق إذا ومتى ما صدر ⁨B-T⁩ في ⁨Pro.⁩

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

المفتاح	النوع	الافتراضي	الوصف
tsa.url	string|null	null	عنوان ⁨URL⁩ لنقطة نهاية هيئة الطوابع الزمنية (⁨TSA⁩).
tsa.username	string	''	اسم مستخدم المصادقة الأساسية لـ ⁨TSA.⁩
tsa.password	string	''	كلمة مرور المصادقة الأساسية لـ ⁨TSA.⁩
tsa.cert	string|null	null	مسار شهادة العميل.
tsa.key	string|null	null	مسار مفتاح العميل.
tsa.timeout	int	30	مهلة الطلب بالثواني.
tsa.pinned_public_keys	list<string>	[]	مفاتيح ⁨TSA⁩ العامة المثبَّتة.
tsa.warn_on_key_rotation	bool	true	التحذير عند تدوير مفتاح ⁨TSA.⁩
tsa.allow_insecure_http	bool	false	السماح بـ ⁨HTTP⁩ بنص صريح إلى ⁨TSA.⁩

تُرجع Services::tsaClient() القيمة null عندما تكون tsa.url هي null أو سلسلة فارغة. عند اختيار مستوى توقيع يتطلب طابعًا زمنيًا، يُرفِق الموقِّع عميل ⁨TSA⁩ تلقائيًا.

التخزين المؤقت لـ ⁨OCSP⁩

المفتاح	النوع	الافتراضي	الوصف
ocspCache.enabled	bool	true	تفعيل التخزين المؤقت لاستجابات بروتوكول حالة الشهادة عبر الإنترنت (⁨OCSP⁩).
ocspCache.ttl	int	86400	مدة بقاء التخزين المؤقت (⁨TTL⁩) بالثواني.
ocspCache.directory	string|null	null	دليل التخزين المؤقت؛ يستخدم المحرك قيمته الافتراضية عندما تكون القيمة ⁨null.⁩

مُصيِّر ⁨HTML⁩ بمتصفح ⁨Chrome⁩ (⁨NextPDF Artisan⁩)

المفتاح	النوع	الافتراضي	الوصف
artisan.chrome_binary	string|null	null	مسار الملف التنفيذي لـ ⁨Chrome/Chromium.⁩
artisan.render_timeout	int	30	مهلة التصيير، بالثواني.
artisan.default_css	string	''	صفحة الأنماط الافتراضية.
artisan.no_sandbox	bool	false	تمرير --no-sandbox إلى ⁨Chrome.⁩
artisan.max_html_size	int	5000000	الحد الأقصى لحجم ⁨HTML⁩ المُدخَل، بالبايت.

لا يُهيَّأ مُصيِّر ⁨Chrome⁩ للمستند إلا عندما تُضبَط artisan.chrome_binary و يكون nextpdf/artisan مثبَّتًا.

التجاوز بـ .env

تحلِّل BaseConfig تجاوزات البيئة لكل خاصية. مفتاح البحث هو اسم الفئة القصير بالأحرف الصغيرة، nextpdf، ثم مسار الخاصية. استخدم النقاط للوصول إلى مفاتيح المصفوفات المتداخلة. تقبل الصيغتان، بالنقاط وبالشرطة السفلية.

.env

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

البادئة هي اسم الفئة القصير بالأحرف الصغيرة. لذلك تبقى nextpdf رغم أن الفئة مكتوبة NextPdf. يمكنك أيضًا استخدام الصيغة المؤهَّلة بالكامل (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

التجاوز بتمديد الفئة

للحصول على تهيئة ذات أنواع محدَّدة وخاضعة للتحكم في الإصدارات، وسِّع فئة الحزمة في app/Config/. يحمِّل ⁨CodeIgniter⁩ فئة التطبيق بدلًا من القيمة الافتراضية للحزمة. يصرِّح هذا الملف بفئة ولا يسبِّب أي آثار جانبية. وبذلك يبقى الملف متوافقًا مع توقع ⁨PSR-1⁩ بأن الملف إما يصرِّح بالرموز وإما ينفِّذ منطقًا ذا آثار جانبية، لكن ليس كليهما (⁨PSR-1⁩ §⁨x1.x1.p3⁩).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

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

• تجاوز مفتاح متداخل واحد عبر .env يغيِّر ذلك المفتاح فقط؛ وتحتفظ بقية المصفوفة بقيمتها الافتراضية.
• قيم .env هي سلاسل نصية. يحوِّل ⁨CodeIgniter⁩ true/false والسلاسل الرقمية. ضع علامات اقتباس حول القيم التي يجب أن تبقى سلاسل نصية حرفية.
• توسيع الفئة بمصفوفة defaults جزئية يستبدل المصفوفة بأكملها. ضمِّن كل مفتاح، كما هو موضَّح أعلاه.

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

أبقِ مساري الشهادة والمفتاح خارج نظام التحكم في المصدر. وفِّرهما عبر .env أو مدير أسرار. يجب أن تبقى tsa.allow_insecure_http بقيمة false في الإنتاج. راجع /⁨integrations/codeigniter/security-and-operations/.⁩

المطابقة

• يصرِّح ملف توسيع تهيئة التطبيق بفئة واحدة، ودون آثار جانبية (⁨PSR-1⁩ §⁨x1.x1.p3⁩).

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

نواة ⁨NextPDF⁩ مرخَّصة بموجب ⁨Apache-2.0.⁩ لا يسري مفعول مفاتيح ⁨signature.⁩* و⁨pdfa⁩ إلا عند تثبيت ⁨NextPDF Pro⁩ أو ⁨Enterprise.⁩ تكشف حزمة ⁨CodeIgniter⁩ عن أساليب الخدمة المقابلة. وتُرجع تلك الأساليب null إلى أن تثبِّت حزمة ⁨Premium⁩ المطابقة. راجع </get-license/?intent=codeigniter-signing>.

انظر أيضًا

• /⁨integrations/codeigniter/install/⁩ — تثبيت الحزمة.
• /⁨integrations/codeigniter/quickstart/⁩ — أول ملف ⁨PDF.⁩
• /⁨integrations/codeigniter/production-usage/⁩ — متحكمات موصولة بحقن التبعيات ومهام صف انتظار.
• /⁨integrations/codeigniter/security-and-operations/⁩ — تقوية تهيئة التوقيع والمسارات.