دليل المطوّر إلى CodeIgniter

لمحة سريعة

توفّر حزمة ⁨CodeIgniter⁩ مصانع خدمات ودوالًا مساعدة وغلافًا خفيفًا لمكتبة Pdf لمستند واحد بصيغة ⁨Portable Document Format⁩ (⁨PDF⁩). استخدم الغلاف داخل المتحكّمات. يعتمد عمل الطابور على كائنات بناء ساكنة وقابلة للاستدعاء، لأنّ حمولات طابور ⁨CodeIgniter⁩ يجب أن تكون بيانات قابلة للتسلسل.

استخدم هذا الدليل لتصميم تدفّقات المتحكّمات والخدمات وكائنات بناء الطابور والاختبارات الخاصة بـ nextpdf/codeigniter.

حدود المعمارية

الطبقة	مملوكة لـ	المسؤولية	ما لا يُوضَع هنا
المتحكّم	التطبيق	تحقّق من الصحة، واستدعِ كائن بناء أو خدمة، وأرجِع `DownloadResponse`.	منطق التخطيط المشترك.
غلاف المكتبة	`nextpdf/codeigniter`	غلِّف `Document` واحدًا ووفّر دوالًا مساعدة للاستجابة والحفظ.	تخزين المستندات طويل الأمد.
مصنع الخدمة	`nextpdf/codeigniter`	أنشئ سجلّات مشتركة ومستندات جديدة.	جذور التخزين الخاصة بمجال العمل.
كائن بناء الطابور	التطبيق	ابنِ مستندًا من مُدخَل قابل للاستدعاء وساكن.	كائنات الطلب أو الحالة التي لا يمكن تسلسلها.
المحرّك الأساسي	`nextpdf/nextpdf`	ابنِ ملف ⁨PDF⁩ وسلسِلْه.	استجابة ⁨CodeIgniter⁩ أو سياسة الطابور.

دورة حياة وقت التشغيل

المرحلة	السلوك	إجراء المطوّر
تسجيل التحميل التلقائي	تسجّل `Registrar::Autoload()` تحميل الدوال المساعدة للوحدة.	حمّل الوحدة عبر إعدادات ⁨CodeIgniter.⁩
حلّ الخدمة	تُرجِع `Services::pdf()` افتراضيًا غلافًا حول مستند جديد.	احلُل الخدمة مرّة واحدة لكلّ طلب.
التأليف	يستخدم كود التطبيق `Pdf::document()` لاستدعاءات المستند الأساسية.	أبقِ كود بناء المستندات داخل الخدمات أو كائنات البناء.
الاستجابة	تُرجِع `PdfResponse` كائن `DownloadResponse`.	دع الحزمة تضبط ترويسات ⁨PDF.⁩
تنفيذ الطابور	تتحقّق `GeneratePdfJob::process()` من كائن البناء ومسار الإخراج، ثم تحفظه.	ضع كائنات بناء الطابور ضمن `App\PdfBuilders`.

بنية التطبيق المُوصى بها

المسار	الغرض
`app/PdfBuilders/*`	كائنات بناء ساكنة وآمنة للطابور تقبلها `GeneratePdfJob`.
`app/Libraries/*`	أغلفة تطبيق اختيارية لتدفّقات عمل المستندات المتكرّرة.
`app/Services/*`	سياسة استرجاع بيانات المجال وتخزينها.
`app/Config/NextPdf.php`	تجاوزات التطبيق لإعدادات الحزمة.
`tests/app/PdfBuilders/*`	اختبارات كائن البناء وحمولات الطابور.

استخدم دوال الحزمة المساعدة للتدفّقات القصيرة. واستخدم استدعاءات الخدمة الصريحة عندما ينتمي بناء المستند إلى صنف يمكنك اختباره مباشرةً.

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

        return $pdf->download('invoice-' . $id . '.pdf');
    }
}

نمط كائن بناء الطابور

يجب أن تكون كائنات بناء الطابور ساكنة وحتمية وموجودة ضمن App\PdfBuilders. أبقِ مصفوفة السياق بسيطة بما يكفي لتسلسلها ومراجعتها.

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

تحصُر المهمة الإخراج في دليل ⁨PDF⁩ المُعَدّ للتطبيق. إذا احتاج تطبيقك إلى تخزين خاص بكلّ مستأجر، فضع تلك السياسة في خدمة واحدة، واختبرها قبل إرسال المهمة.

نقاط التوسيع

نقطة التوسيع	استخدمها من أجل	القيد
`Services::pdfDocument()`	خصّص إنشاء المستند.	يجب أن تُرجِع مستندًا جديدًا.
`Services::fontRegistry()`	سخّن الخطوط وادخل إلى السجلّ.	ارفض المسارات غير الآمنة، وأبقِ السجلّ مقفلًا بعد التسخين.
`Services::pdfSigner()`	فعّل التوقيع الرقمي الاختياري.	أرجِع `null` عند تعطيل التوقيع.
`NextPDF\CodeIgniter\Libraries\Pdf`	غلِّف عمل المستندات الموجَّه إلى المتحكّمات.	يقابل كلّ غلاف مستندًا واحدًا.
`App\PdfBuilders::*`	كائنات بناء مستندات آمنة للطابور.	يلزم سلسلة استدعاء ساكنة.
`app/Config/NextPdf.php`	القيم الافتراضية للتطبيق وإعدادات التكامل.	أبقِ قيم الإنتاج صريحة.

تدفّق عمل التطوير

ابدأ بمتحكّم يستدعي pdf() أو service('pdf').
انقل بناء المستندات المتكرّر إلى app/PdfBuilders أو خدمة تطبيق.
استخدم GeneratePdfJob عندما يكون التوليد أبطأ من أن يناسب مسار الطلب.
أبقِ سياق الطابور قابلًا للتسلسل وصغيرًا.
خزّن الإخراج ضمن جذر تخزين ⁨PDF⁩ المعتمد، إلّا إذا وسّعت السياسة عمدًا.
أضف اختبارات للدوال المساعدة والخدمات وحمولات الطابور والمسارات غير الآمنة.

معالجة الإخفاق

الإخفاق	المكان الذي ينبغي معالجته فيه	الاستجابة المُوصى بها
امتداد مفقود أو مسار خط غير آمن	مصنع الخدمة.	أخفِق سريعًا أثناء حلّ الخدمة.
كائن بناء قابل للاستدعاء غير صالح	التحقّق من مهمة الطابور.	ارفض المهمة وسجّل سلسلة كائن البناء دون أسرار.
مسار إخراج غير آمن	خدمة التخزين ومهمة الطابور.	ارفض قبل الإرسال، وأبقِ التحقّق من المهمة.
خطأ تسلسل الاستجابة	معالجة الأخطاء في المتحكّم أو إطار العمل.	لا ترسل جسم استجابة جزئيًا.
صنف ⁨Premium⁩ اختياري غير متاح	القيمة المُرجَعة من دالة الخدمة.	عالِج `null` صراحةً قبل استخدام ميزات الفوترة الإلكترونية الاختيارية.

القيم الافتراضية الآمنة

الجانب المعنيّ	الافتراضي	متى تتجاوز
فضاء أسماء كائن بناء الطابور	`App\PdfBuilders`.	أبقِ القيمة الافتراضية، إلّا إذا حدّثت سياسة الأمان أيضًا.
جذر الإخراج	`WRITEPATH/pdfs`.	لا تتجاوز إلّا بقائمة سماح أقوى.
اسم ملف الاستجابة	`document.pdf`.	استخدم أسماء ملفات عمل مُنقّاة.
دوال الدفق	تكافؤ واجهة برمجة التطبيقات (⁨API⁩) مع أطر العمل الأخرى.	لا تعتمد على التدفّق بوصفه حدًّا للذاكرة في ⁨CodeIgniter.⁩
خدمة المستند	جديد افتراضيًا.	لا تطلب مستندات مشتركة من كود الطلب.

قائمة تحقّق الاختبار

تتحقّق اختبارات الخدمة من أنّ كلّ عملية حلّ لـ Services::pdf() تُرجِع مستندًا مستقلًّا.
تتحقّق اختبارات الدوال المساعدة من أنّ pdf() وpdf_document() تُرجِعان كائنات جديدة.
تتحقّق اختبارات الاستجابة من الترويسات وتطبيع اسم الملف.
تغطّي اختبارات الطابور سلاسل كائن البناء غير الصالحة ومسارات الإخراج غير الآمنة.
تستخدم اختبارات كائن البناء بيانات سياق تمثيلية.
تغطّي اختبارات الإعداد مسار الخط ومسار التخزين المؤقّت وحالة تعطيل التوقيع وحالة تعطيل سلطة الطابع الزمني (⁨TSA⁩).