تثبيت NextPDF مع إطار العمل CodeIgniter 4

لمحة سريعة

ثبّت الحزمة باستخدام ⁨Composer.⁩ يكتشف ⁨CodeIgniter 4⁩ فئة ⁨Services⁩ ودوال المساعدة تلقائيًا، لذلك لن تحتاج إلى تسجيلها يدويًا.

المتطلبات

يُعد ملف composer.json الخاص بالحزمة المرجع لهذه القيود. يعرضها الجدول التالي للرجوع السريع.

التبعية	القيد	ملاحظات
⁨PHP⁩	>=8.4 <9.0	يستهدف ⁨PHP 8.4.⁩
nextpdf/core	^3.0 || ^5.2	محرّك ⁨NextPDF.⁩
codeigniter4/framework	^4.6	جرى التحقق منه مع ⁨CodeIgniter 4.7.0.⁩
ext-mbstring	مطلوب في وقت التشغيل	يجري التحقق منه مرة واحدة لكل عملية.
ext-zlib	مطلوب في وقت التشغيل	يجري التحقق منه مرة واحدة لكل عملية.

الحزم الاختيارية المُعلَنة ضمن suggest تضيف الميزات التالية:

الحزمة	تضيف
nextpdf/artisan	مُصيِّر ⁨HTML⁩ عبر بروتوكول ⁨Chrome DevTools Protocol⁩ ‏(⁨CDP⁩)، ويُكتشف تلقائيًا عند بناء المستند.
nextpdf/premium	ميزات ⁨NextPDF Pro⁩ و ⁨Enterprise⁩: التوقيع، ⁨PDF/A⁩، ⁨Factur-X.⁩
codeigniter4/queue	توليد ⁨PDF⁩ بشكل غير متزامن باستخدام GeneratePdfJob.

التثبيت

ثبّت الحزمة باستخدام ⁨Composer⁩:

composer require nextpdf/codeigniter

يحلّ ⁨Composer⁩ nextpdf/core و codeigniter4/framework وفق القيود المذكورة أعلاه. لن تحتاج إلى تعديل مزوّد خدمة أو حزمة أو ملف تهيئة أولية.

كيفية عمل الاكتشاف

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

يسجّل مدخل التحميل التلقائي files في ⁨Composer⁩ الخاص بالحزمة (src/CodeIgniter/Helpers/pdf_helper.php) دالتي المساعدة pdf() و pdf_document(). كما يُعرِّف Registrar الخاص بالحزمة مساعد pdf لمُحمّل المساعدات في ⁨CodeIgniter.⁩ راجع /⁨integrations/codeigniter/boot-and-discovery/⁩ للاطّلاع على التسلسل الكامل.

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

تأكّد من أن ⁨Composer⁩ حلّ الحزمة:

composer show nextpdf/codeigniter

تأكّد من أن ⁨CodeIgniter⁩ اكتشف فئة ⁨Services.⁩ من أي وحدة تحكّم، أو من مسار php spark قصير، استدعِ الخدمة وتحقّق من نوعها:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;
use NextPDF\Core\Document;

$document = Services::pdfDocument(false);

// $document is a fresh NextPDF\Core\Document instance.
\assert($document instanceof Document);

إذا أعادت Services::pdfDocument() كائن Document، فهذا يعني أن الاكتشاف يعمل. إذا أعادت null، فهذا يعني أن الاكتشاف لم يُشغَّل. راجع /⁨integrations/codeigniter/troubleshooting/.⁩

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

• إذا ضبط التطبيق المضيف Config\Modules::$discoverInComposer على false، فأضِف nextpdf/codeigniter إلى قائمة $composerPackages['only']. وإلا فسيتخطّى ⁨CodeIgniter⁩ الحزمة.
• قد يحجب مُحمّل التحميل التلقائي القديم في ⁨Composer⁩ فئة ⁨Services.⁩ شغّل composer dump-autoload بعد الترقية.
• تُعلِن الحزمة عن codeigniter4/queue كتبعية تطوير فقط. يجب على تطبيق الإنتاج الذي يُرسل GeneratePdfJob طلب codeigniter4/queue مباشرةً.

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

ثبّت من ⁨Packagist⁩ عبر ⁨HTTPS.⁩ ثبّت الإصدارات المُحلّة في composer.lock. لا تضيف الحزمة أي نصوص برمجية تُنفَّذ في وقت التثبيت. راجع /⁨integrations/codeigniter/security-and-operations/.⁩

المطابقة

• يعتمد اكتشاف ⁨Composer⁩ على التحميل التلقائي وفق ⁨PSR-4.⁩

انظر أيضًا

• /⁨integrations/codeigniter/overview/⁩ — قدرات الحزمة.
• /⁨integrations/codeigniter/quickstart/⁩ — أنشئ أول ملف ⁨PDF⁩ لك من وحدة تحكّم.
• /⁨integrations/codeigniter/configuration/⁩ — مفاتيح التهيئة وتجاوزاتها.
• /⁨integrations/codeigniter/boot-and-discovery/⁩ — تسلسل الاكتشاف المفصّل.