تمهيد NextPDF واكتشافه في CodeIgniter

لمحة سريعة

يكتشف ⁨CodeIgniter 4⁩ فئة Services الخاصة بالحزمة والدوال المساعدة وأداة التسجيل عبر اكتشاف حزم ⁨Composer.⁩ توضّح هذه الصفحة التسلسل والإعدادات التي تتحكّم بهذا السلوك.

كيف يعمل اكتشاف الخدمات في ⁨CodeIgniter⁩

يحلّ ⁨CodeIgniter 4⁩ الخدمة بفحص كل فئة Config\Services مُكتشَفة بحثًا عن دالة ثابتة تطابق اسم الخدمة المطلوبة. عندما يستدعي تطبيقك service('pdf')، يعثر إطار العمل على أول فئة Services مُكتشَفة تُصرّح عن دالة pdf، ثم يستدعيها.

يتحكّم Config\Modules في الاكتشاف:

• $enabled — المفتاح الرئيسي للاكتشاف التلقائي. القيمة الافتراضية true.
• $discoverInComposer — يوسّع الاكتشاف ليشمل حزم ⁨Composer.⁩ القيمة الافتراضية true. يتيح هذا العَلَم لإطار العمل العثور على nextpdf/codeigniter.
• $composerPackages — مرشّح only / exclude اختياري لمجموعة حزم ⁨Composer.⁩
• $aliases — أنواع العناصر التي تشارك في الاكتشاف. يشمل الإعداد الافتراضي لإطار العمل services وregistrars، وتستخدم هذه الحزمة كليهما.

فئة الحزمة هي NextPDF\CodeIgniter\Config\Services. يربط ⁨Composer⁩ البادئة NextPDF\CodeIgniter\ الخاصة بـ ⁨PHP Standards Recommendation 4⁩ ‏(⁨PSR-4⁩) بـ src/CodeIgniter/. يجب أن يحتوي اسم الفئة المؤهَّل بالكامل على فضاء أسماء عُلوي (⁨PSR-4⁩ §⁨x1.x2.p5⁩، بصيغة الإلزام ⁨MUST⁩). ترتبط بادئة فضاء الأسماء بالدليل الأساسي، فتُحلّ الفئة إلى ملفها (⁨PSR-4⁩ §⁨x1.x3⁩).

تسلسل الإقلاع

1. التحميل التلقائي عبر ⁨Composer.⁩ يسجّل ⁨Composer⁩ خريطة ⁨PSR-4⁩ ومُدخلات التحميل التلقائي files. في هذه المرحلة، يحمّل الملف المساعد src/CodeIgniter/Helpers/pdf_helper.php.
2. تمهيد إطار العمل. يقرأ ⁨CodeIgniter⁩ ملف Config\Modules. وعند تفعيل الاكتشاف، يبني قائمة بالعناصر المُكتشَفة عبر حزم ⁨Composer.⁩
3. اكتشاف أداة التسجيل. يجمع إطار العمل فئات Registrar. تُعلن دالة Registrar::Autoload() الخاصة بالحزمة عن الدالة المساعدة pdf لمُحمِّل الدوال المساعدة في ⁨CodeIgniter.⁩
4. تحليل الخدمة عند أول استدعاء. تعمل مصانع الخدمات بأسلوب كسول. يشغّل أول استدعاء لـ service('pdf') أو Services::pdf() المصنع. تُخزَّن الخدمات المشتركة مؤقتًا في المُحدِّد طوال عمر العملية.

ارتباطات الحاوية

لا يوفّر ⁨CodeIgniter 4⁩ حاوية ⁨PSR-11.⁩ وبدلًا من ذلك، تؤدّي دوال المصنع الثابتة في فئة Services دور الارتباطات. تقبل كل دالة مُعاملًا من النوع bool $getShared:

الخدمة	مشتركة افتراضيًا	ملاحظات
fontRegistry	نعم	تُسخَّن مسبقًا ثم تُقفَل.
imageRegistry	نعم	ذاكرة تخزين مؤقت محدودة بسياسة الأقل استخدامًا مؤخرًا (⁨LRU⁩).
documentFactory	نعم	عديمة الحالة.
pdfDocument	لا	نسخة جديدة في كل استدعاء.
pdf	لا	نسخة جديدة في كل استدعاء.
tsaClient	نعم	null عندما لا يكون عنوان ⁨URL⁩ لسلطة الطابع الزمني (⁨TSA⁩) مُهيَّأً.
pdfSigner	لا	null عند تعطيل التوقيع.

تبقى النسخ المشتركة في ذاكرة تخزين النسخ المؤقتة BaseService الخاصة بـ ⁨CodeIgniter⁩ طوال عمر العملية. تمسح بنية اختبار إطار العمل تلك الذاكرة المؤقتة عبر BaseService::reset()، وتعتمد الاختبارات الوظيفية للحزمة على هذا التصفير بين الحالات.

ترتيب تحليل الإعدادات

تُحلّ الإعدادات الفعّالة بهذا الترتيب:

1. القيم الافتراضية للحزمة في NextPDF\CodeIgniter\Config\NextPdf.
2. فئة تطبيق Config\NextPdf التي تُوسّع فئة الحزمة، عند وجودها. يحمّلها ⁨CodeIgniter⁩ بدلًا من القيمة الافتراضية للحزمة.
3. تجاوزات بيئية يطبّقها BaseConfig، مُفهرَسة باسم الفئة القصير بأحرف صغيرة nextpdf (مفاتيح متداخلة مفصولة بنقاط، أو صيغة الفئة المؤهَّلة بالكامل).

يُصرّح ملف امتداد إعدادات التطبيق عن فئة واحدة ولا تترتّب عليه آثار جانبية. وهذا يبقيه متوافقًا مع توقّع ⁨PSR-1⁩ بأن الملف إمّا يُصرّح عن رموز أو يُنفّذ منطقًا ذا آثار جانبية، لكن ليس كليهما (⁨PSR-1⁩ §⁨x1.x1.p3⁩). أما الملف المساعد، فهو النظير المتعمَّد ذو الآثار الجانبية. يُصرّح عن الدالتين العامتين pdf() وpdf_document()، وكلٌّ منهما محمية بفحص function_exists بحيث يكون التحميل المزدوج آمنًا.

التشخيص

• composer dump-autoload — يعيد بناء خريطة ⁨PSR-4⁩ وقائمة التحميل التلقائي files بعد الترقية.
• لفحص الاكتشاف بسرعة، استخدم مُتحكِّمًا يستدعي Services::pdfDocument(false) ويتحقّق من إرجاع Document.
• افحص vendor/composer/autoload_files.php للتأكّد من تسجيل الملف المساعد.
• راجع /⁨integrations/codeigniter/troubleshooting/⁩ لمعرفة كيفية ربط الأعطال بأسبابها.

المطابقة

• يتطلّب اسم الفئة المؤهَّل بالكامل فضاء أسماء عُلويًّا (⁨PSR-4 Autoloader⁩ §⁨x1.x2.p5⁩).
• ترتبط بادئة فضاء الأسماء بمسار فئة الدليل الأساسي (⁨PSR-4 Autoloader⁩ §⁨x1.x3⁩).
• الملف إمّا يُصرّح عن رموز أو يُسبّب آثارًا جانبية — تصميم الملف المساعد (⁨PSR-1 Basic Coding Standard⁩ §⁨x1.x1.p3⁩).

انظر أيضًا

• /⁨integrations/codeigniter/integration/⁩ — مرجع التوصيل واختبار التدخين.
• /⁨integrations/codeigniter/install/⁩ — التثبيت والتحقّق من الاكتشاف.
• /⁨integrations/codeigniter/overview/⁩ — السطح الكامل لواجهة برمجة التطبيقات (⁨API⁩).
• /⁨integrations/codeigniter/troubleshooting/⁩ — أنماط فشل الاكتشاف.