تكامل NextPDF مع CodeIgniter

لمحة سريعة

ثبّت الحزمة، وسيتولى ⁨CodeIgniter 4⁩ ربطها نيابةً عنك. استخدم هذه الصفحة للتحقق من الربط: الاكتشاف، ونموذج الربط، ونشر الإعدادات، واختبار تحقق سريع ضمن مسار واحد يثبت أن التكامل يعمل.

التثبيت

composer require nextpdf/codeigniter

لا تحتاج إلى تحرير مزوّد خدمة أو تغيير ملف إقلاع. راجع /⁨integrations/codeigniter/install/⁩ للاطلاع على قيود الإصدارات التي جرى التحقق منها.

الإقلاع / الاكتشاف التلقائي

يعثر ⁨CodeIgniter 4⁩ على الحزمة عبر اكتشاف حزم ⁨Composer⁩ عندما تكون قيمة Config\Modules::$discoverInComposer مضبوطة على true، وهي القيمة الافتراضية لإطار العمل. تربط قاعدة التحميل التلقائي في ⁨PSR-4⁩ البادئة NextPDF\CodeIgniter\ بالمسار src/CodeIgniter/، بحيث يستطيع إطار العمل تحليل NextPDF\CodeIgniter\Config\Services إلى ملفه (⁨PSR-4⁩ §⁨x1.x3⁩). توثّق /⁨integrations/codeigniter/boot-and-discovery/⁩ التسلسل الكامل وخصائص Config\Modules التي تتحكم فيه.

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

لا يأتي ⁨CodeIgniter 4⁩ مزوّدًا بحاوية ⁨PSR-11⁩. يثبّط البند §1.3 من ⁨PSR-11⁩ نمط محدِّد موقع الخدمة بصيغة ⁨SHOULD NOT⁩. تتبع الحزمة عُرف المحدِّد الخاص بإطار العمل وتُبقي استخدامه في أضيق نطاق. كل رابط هو دالة مصنع ساكنة مُسمّاة لها معامل bool $getShared.

اسم الخدمة	القيمة المُعادة	مدة الحياة الافتراضية
`fontRegistry`	`FontRegistryInterface`	مشتركة
`imageRegistry`	`ImageRegistry`	مشتركة
`documentFactory`	`DocumentFactoryInterface`	مشتركة
`pdfDocument`	`Document`	جديدة
`pdf`	`Pdf`	جديدة
`tsaClient`	`?TsaClient`	مشتركة
`pdfSigner`	`?SignerInterface`	جديدة

استخدم أيًّا من نقطتَي الدخول؛ فهما متكافئتان:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;

$a = Services::pdf(false);   // direct
$b = \service('pdf');        // helper → Services::pdf()

تغلّف الدالتان المساعدتان العامتان pdf() وpdf_document() كلًّا من Services::pdf(false) وServices::pdfDocument(false).

نشر الإعدادات

توجد إعدادات الحزمة في NextPDF\CodeIgniter\Config\NextPdf، وهي BaseConfig غير نهائية. يمكنك تجاوزها بإحدى طريقتين مدعومتين:

1. وسِّع الصنف (مُحدَّد الأنواع وخاضع للتحكم في الإصدارات). أنشئ app/Config/NextPdf.php:

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

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

يحمّل ⁨CodeIgniter⁩ صنف التطبيق لديك بدلًا من الصنف الافتراضي للحزمة.

2. تجاوزها عبر .env (لكل بيئة على حدة). استخدم اسم الصنف القصير بأحرف صغيرة، nextpdf، كبادئة:

nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem

توثّق /⁨integrations/codeigniter/configuration/⁩ كل مفتاح وقواعد تجاوز المصفوفات.

اختبار التحقق السريع لمزوّد الخدمة / الحزمة

لا يوفّر ⁨CodeIgniter⁩ مزوّد خدمة أو صنف حزمة مستقلًا لاختباره. استخدم اختبار التحقق السريع المكافئ للتأكد من أمرين: أن الاكتشاف حلّ الخدمات، وأن مدد الحياة تتصرف كما هو محدد. إجراء المتحكم أدناه قابل للتشغيل ويعكس التوكيدات الوظيفية الخاصة بالحزمة نفسها.

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\ResponseInterface;
use NextPDF\CodeIgniter\Config\Services;
use NextPDF\CodeIgniter\Libraries\Pdf;
use NextPDF\Core\Document;

final class NextPdfSmokeController extends BaseController
{
    public function check(): ResponseInterface
    {
        // Discovery resolved the services.
        $document = Services::pdfDocument(false);
        $library = Services::pdf(false);

        // Documents are fresh per call (no cross-request leakage).
        $freshIsolated = Services::pdfDocument(false) !== $document;

        // Registries are shared singletons.
        $registrySingleton = Services::fontRegistry() === Services::fontRegistry();

        // Optional services degrade to null without Premium / TSA config.
        $signerOptional = Services::pdfSigner(false) === null;

        $ok = $document instanceof Document
            && $library instanceof Pdf
            && $freshIsolated
            && $registrySingleton
            && $signerOptional;

        return $this->response
            ->setStatusCode($ok ? 200 : 500)
            ->setJSON([
                'discovery' => $document instanceof Document,
                'document_fresh_per_call' => $freshIsolated,
                'registry_shared' => $registrySingleton,
                'signer_optional_null' => $signerOptional,
            ]);
    }
}

اربط مسارًا بهذا الإجراء، ثم استدعِه. استجابة 200 مع ضبط جميع الأعلام على true تثبت صحة التكامل. كل توكيد هنا يطابق سلوكًا جرى التحقق منه في مجموعة الاختبارات الوظيفية الخاصة بالحزمة.

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

إذا عطّل التطبيق المضيف اكتشاف ⁨Composer⁩، فأضف nextpdf/codeigniter إلى Config\Modules::$composerPackages['only'].
تُعيد Services::pdfDocument(true) مستندًا مشتركًا. وهذا السلوك موجود لإعادة ضبط الاختبارات فقط. لا تطلب المستند المشترك مطلقًا في شيفرة الطلبات أو المهام.
تُعيد Services::pdfSigner() وServices::tsaClient() القيمة null إلى أن تُهيَّأ إعدادات التوقيع أو نقطة نهاية سلطة الختم الزمني (⁨TSA⁩). هذا تراجع سلس مقصود، وليس فشلًا.

المطابقة

ربط مسار الصنف لاكتشاف الوحدات (⁨PSR-4 Autoloader⁩ §⁨x1.x3⁩).
إرشادات محدِّد موقع الخدمة لنموذج الربط (⁨PSR-11 Container⁩ §1.3).

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

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

انظر أيضًا

/⁨integrations/codeigniter/boot-and-discovery/⁩ — تفاصيل الاكتشاف الداخلية.
/⁨integrations/codeigniter/install/⁩ — قيود الإصدارات والتحقق.
/⁨integrations/codeigniter/quickstart/⁩ — أول ملف ⁨PDF⁩.
/⁨integrations/codeigniter/production-usage/⁩ — وحدات تحكم مربوطة عبر حقن التبعيات ومهمة الطابور.
/⁨integrations/codeigniter/configuration/⁩ — كل مفتاح إعداد.