مرجع واجهة CodeIgniter البرمجية

لمحة سريعة

توفِّر حزمة ⁨CodeIgniter⁩ واجهة برمجية (⁨API⁩) صغيرة موجَّهة إلى وحدات التحكم. وتتضمن غلاف المكتبة Pdf لمستند واحد (Services::pdf() والمساعد العام pdf())، ومساعدات الاستجابة التي تحوِّل مستندًا مُنشأً إلى DownloadResponse (PdfResponse)، ومصانع Services التي تستند إليها (سجلّات الخطوط والصور، ومصنع المستندات، وعميل اختياري للموقِّع وسلطة الطابع الزمني (⁨TSA⁩))، وفئة الإعداد NextPdf، وGeneratePdfJob للإنشاء غير المتزامن من دوال بانٍ ثابتة قابلة للاستدعاء.

ابدأ بمسار وحدة التحكم الرئيسي: استدعِ Services::pdf() (أو المساعد pdf())، وأضف المحتوى إلى $pdf->document()، وأرجِع $pdf->download('file.pdf'). يغطي هذا المسار الحالة الشائعة. جداول المرجع منظَّمة حسب الواجهة؛ ويعرض قسم “المهام الشائعة” الأشكال القابلة للتشغيل أولًا.

المهام الشائعة

هذه هي أكثر التدفقات الإنتاجية شيوعًا. كل عيِّنة موثَّقة من المصدر مقابل nextpdf/codeigniter.

استخدم مسار العرض القانوني لإرجاع ملف بتنسيق المستندات المحمولة (⁨PDF⁩) قابل للتنزيل من وحدة تحكم:

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

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

ما يفعله: ينشئ Pdf جديدًا حول Document جديد، ويكتب خلية واحدة، ويُرجِع DownloadResponse بترتيب attachment ورؤوس الأمان الخاصة بالحزمة.

اعرض ملف ⁨PDF⁩ بشكل مضمّن في المتصفح باستخدام الغلاف نفسه وinline() بدلًا من download():

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

ما يفعله: يستخدم المساعد العام pdf() (المكافئ لـ Services::pdf()) ويُرجِع DownloadResponse بترتيب inline ليعرض المتصفح ملف ⁨PDF⁩ بدلًا من تنزيله.

أنشئ ملف ⁨PDF⁩ بشكل غير متزامن على قائمة الانتظار باستخدام GeneratePdfJob وبانٍ ثابت:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

ما يفعله: يضع عملية الإنشاء في قائمة الانتظار. يتحقق العامل من البانِي (يجب أن يكون دالة استدعاء ثابتة من النوع App\PdfBuilders\...::method) ومن مسار الإخراج (يجب أن يُحَلّ ضمن WRITEPATH/pdfs/ وأن ينتهي بـ .pdf)، ثم يبني مستندًا جديدًا ويحفظه.

غلاف المكتبة

استخدم هذا الجدول عندما يكون لديك غلاف Pdf وتحتاج إلى أساليب الاستجابة أو الحفظ التابعة له.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُرجَعة	يطرح أو يفشل بـ	ملاحظات
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: مستند نواة جديد.	يغلِّف المستند المُمرَّر لعملية استجابة أو حفظ واحدة.	`Pdf`	لا شيء متوقَّع.	لا تُعِد استخدام الغلاف بعد إخراج الناتج.
`Pdf::document()`	لا شيء.	يُرجِع المستند المغلَّف.	`NextPDF\Core\Document`	لا شيء متوقَّع.	استخدم هذا لاستدعاء واجهات تأليف النواة.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: اسم ملف الاستجابة.	يستخدم ترتيب العرض المضمّن في المتصفح.	`CodeIgniter\HTTP\DownloadResponse`	أخطاء تسلسل النواة.	يمرِّر التنفيذ إلى `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: اسم ملف الاستجابة.	يستخدم ترتيب المرفق في المتصفح.	`DownloadResponse`	أخطاء تسلسل النواة.	يمرِّر التنفيذ إلى `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: اسم ملف الاستجابة.	يوفِّر تكافؤًا في الواجهة البرمجية مع حزم أطر العمل الأخرى.	`DownloadResponse`	أخطاء تسلسل النواة.	يتعامل ⁨CodeIgniter⁩ مع الإخراج الثنائي بشكل أصيل.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: اسم ملف الاستجابة.	يوفِّر تكافؤًا في الواجهة البرمجية مع حزم أطر العمل الأخرى.	`DownloadResponse`	أخطاء تسلسل النواة.	استخدم عناصر التحكم نفسها في الحجم مثل الاستجابات غير المتدفقة.
`Pdf::save(string $path)`	`path`: هدف نظام الملفات.	يكتب المستند المغلَّف.	`void`	أخطاء نظام الملفات أو أخطاء كتابة النواة.	تحقَّق من جذور التخزين قبل الحفظ.

الخدمات والمساعدات

استخدم هذا الجدول عندما تحتاج إلى مصنع خدمة محدد أو دالة مساعدة عامة، بما في ذلك سلوك المشاركة ونوع القيمة المُرجَعة.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُرجَعة	يطرح أو يفشل بـ	ملاحظات
`Services::fontRegistry(bool $getShared = true)`	`getShared`: علم خدمة ⁨CodeIgniter⁩ المشتركة.	يُرجِع سجلًّا مشتركًا، ويُحمِّله مسبقًا بالخطوط المُعدَّة، ثم يقفله.	`FontRegistryInterface`	`RuntimeException` لامتدادات مفقودة أو مسار خطوط غير آمن.	يرفض أغلفة التدفق وأحرف ⁨null⁩ البايتية في `fontsPath`.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: علم الخدمة المشتركة.	يُرجِع سجل صور مقيَّدًا مشتركًا بنظام الأقل استخدامًا مؤخرًا (⁨LRU⁩).	`ImageRegistry`	لا شيء متوقَّع.	يتحكم في حجم ذاكرة التخزين المؤقت `imageCacheMb`.
`Services::documentFactory(bool $getShared = true)`	`getShared`: علم الخدمة المشتركة.	يُرجِع مصنعًا مشتركًا يستخدم سجلّات مشتركة.	`DocumentFactoryInterface`	أخطاء إعداد السجل.	المصنع قابل لإعادة الاستخدام؛ أما المستندات فلا.
`Services::tsaClient(bool $getShared = true)`	`getShared`: علم الخدمة المشتركة.	يُرجِع `null` عندما يكون `tsa.url` فارغًا.	`TsaClient	null`	أخطاء عميل بروتوكول نقل النص التشعبي (⁨HTTP⁩) أو أخطاء إعداد ⁨TSA.⁩
`Services::pdfSigner(bool $getShared = false)`	`getShared`: علم الخدمة المشتركة.	يُرجِع `null` عند تعطيل التوقيع.	`SignerInterface	null`	أخطاء على مستوى الشهادة أو التوقيع.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: علم الخدمة المشتركة.	ينشئ مستندًا جديدًا، ويطبِّق الإعدادات الافتراضية، ويُعدّ ⁨PDF/A⁩ أو ⁨Artisan⁩ اختياريًا.	`Document`	أخطاء امتداد اختياري أو أخطاء إعداد المستند.	أبقِ الافتراضي `false` من أجل أمان الطلب.
`Services::pdf(bool $getShared = false)`	`getShared`: علم الخدمة المشتركة.	ينشئ غلاف `Pdf` جديدًا حول مستند جديد.	`NextPDF\CodeIgniter\Libraries\Pdf`	أخطاء إعداد المستند.	الخدمة الرئيسية الموجَّهة إلى وحدات التحكم.
`Services::eInvoiceEmbedder()`	لا شيء.	يُرجِع `null` ما لم تكن فئة مُضمِّن الفواتير الإلكترونية لـ ⁨Premium Pro⁩ موجودة.	`EmbedderInterface	null`	أخطاء إنشاء حزمة اختيارية.
`Services::eInvoiceValidator()`	لا شيء.	يُرجِع `null` ما لم تكن فئة المُحقِّق لـ ⁨Premium Enterprise⁩ موجودة.	`ValidatorInterface	null`	أخطاء إنشاء حزمة اختيارية.
`Services::eInvoiceProfile()`	لا شيء.	يُرجِع ملف ⁨EN16931⁩ الشخصي عند تثبيت ⁨Premium Pro.⁩	`ProfileInterface	null`	أخطاء حزمة اختيارية.
`Services::schematronRunner()`	لا شيء.	يُرجِع `null` ما لم يكن مُحقِّق ⁨Schematron⁩ لـ ⁨Premium Enterprise⁩ موجودًا.	`SchematronRunnerInterface	null`	أخطاء إنشاء حزمة اختيارية.
`Registrar::Autoload()`	لا شيء.	يضيف مساعد الحزمة إلى إعداد التحميل التلقائي في ⁨CodeIgniter.⁩	`array`	لا شيء متوقَّع.	يُمكِّن `pdf()` و`pdf_document()` عند تحميل الوحدة.
`pdf()`	لا شيء.	يستدعي `Services::pdf(false)`.	`Pdf`	أخطاء إعداد المستند.	مساعد ميسِّر لوحدات التحكم.
`pdf_document()`	لا شيء.	يستدعي `Services::pdfDocument(false)`.	`Document`	أخطاء إعداد المستند.	مساعد ميسِّر عند تفضيل الواجهة البرمجية لمستند النواة.

استجابات ⁨HTTP⁩

استخدم هذا الجدول عندما يكون لديك بالفعل Document مُنشأ وتريد إنشاء DownloadResponse بنفسك بدلًا من استخدام غلاف Pdf.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُرجَعة	يطرح أو يفشل بـ	ملاحظات
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: مستند مُنشأ؛ `filename`: اسم ملف الاستجابة.	يضمن امتداد `.pdf` وترتيب العرض المضمّن.	`DownloadResponse`	أخطاء تسلسل النواة.	يضيف نوع محتوى ⁨PDF⁩ ورؤوسًا دفاعية.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	مثل `inline`؛ والترتيب هو مرفق.	يضمن امتداد `.pdf`.	`DownloadResponse`	مثل `inline`.	استخدمه لتنزيلات المتصفح.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	مثل `inline`.	نفس سلوك `inline` في ⁨CodeIgniter 4⁩ (⁨CI4⁩).	`DownloadResponse`	مثل `inline`.	موجود من أجل تكافؤ الواجهة البرمجية عبر أطر العمل.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	مثل `download`.	نفس سلوك `download` في ⁨CI4.⁩	`DownloadResponse`	مثل `download`.	موجود من أجل تكافؤ الواجهة البرمجية عبر أطر العمل.

مهمة قائمة الانتظار

استخدم هذا الجدول عند ربط الإنشاء غير المتزامن وتحتاج إلى مفاتيح بيانات المهمة الدقيقة وعقد دالة البانِي القابلة للاستدعاء.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُرجَعة	يطرح أو يفشل بـ	ملاحظات
`GeneratePdfJob::process()`	مفاتيح بيانات المهمة: `builder` و`outputPath` و`context` الاختياري.	يستخدم مصفوفة سياق فارغة عند الحذف.	`void`	`InvalidArgumentException` لبانٍ غير آمن أو مسار إخراج غير آمن؛ وأخطاء كتابة النواة.	يجب أن يكون البانِي `App\PdfBuilders\...\*::method`.
دالة البانِي القابلة للاستدعاء	`Document $doc`، `array $context`.	لا سياق افتراضي يتجاوز بيانات المهمة.	`Document`	استثناءات خاصة بالبانِي.	يتطلب دالة استدعاء ثابتة لأن حمولات قائمة انتظار ⁨CI4⁩ بيانات مُسلسَلة.

الإعداد

استخدم هذا الجدول عند تغيير الإعدادات الافتراضية لتنسيق الصفحة والمسارات والتوقيع و⁨TSA⁩ أو بيانات المستند الوصفية على فئة الإعداد NextPdf.

الخاصية	النوع	السلوك الافتراضي	ملاحظات
`pageFormat`	`string`	`A4`.	يضبط تنسيق الصفحة الافتراضي.
`orientation`	`string`	`P`.	يضبط الاتجاه الافتراضي.
`unit`	`string`	`mm`.	يضبط الوحدة الافتراضية.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` و`WRITEPATH . 'cache/nextpdf'`.	أبقِ المسارات داخل مساحة تخزين يتحكم فيها التطبيق.
`signature`	`array`	مُعطَّل بمستوى `B-B`.	الشهادة والمفتاح وكلمة المرور والشهادات الإضافية والمستوى.
`tsa`	`array`	مُعطَّل عندما يكون محدِّد موقع الموارد الموحَّد (⁨URL⁩) هو `null`؛ المهلة 30 ثانية.	بيانات الاعتماد، وملفات أمان طبقة النقل المتبادل (⁨mTLS⁩)، وتثبيتات المفاتيح العامة، وسياسة ⁨HTTP.⁩
`ocspCache`	`array`	مُفعَّل بمدة بقاء (⁨TTL⁩) قدرها 86400 ثانية.	تستخدمه تدفقات التحقق من التوقيع عند توفُّره.
`preloadFonts`	`list<string>`	فارغة.	تُحمَّل مسبقًا قبل قفل السجل.
`imageCacheMb`	`int`	`50`.	يتحكم في ذاكرة التخزين المؤقت للصور طوال عمر العملية.
`fontCacheLocking`	`bool`	`true`.	يُبقي تعديلات سجل الخطوط خارج معالجة الطلبات.
`artisan`	`array`	مُصيِّر ⁨Chrome⁩ مُعطَّل ما لم يكن مُعدًّا ومُثبَّتًا.	يُطابِق `ChromeRendererConfig::fromArray()`.
`defaults`	`array`	المُنشئ `NextPDF`، ومؤلف فارغ، واللغة `en`، وهوامش افتراضية، وخط افتراضي.	يطبِّق `Services::pdfDocument()` فقط `creator` و`language` و(عند عدم كونه فارغًا) `author`؛ أما `margin_top`/`right`/`bottom`/`left` و`font_family` و`font_size` و`trim_box` و`bleed_box` فهي إعدادات افتراضية معرَّفة، لكنه لا يطبِّقها حاليًا.

ملاحظات التطوير

يحصر GeneratePdfJob الإخراج في WRITEPATH . 'pdfs' ويتطلب .pdf.
تُرفَض دوال البانِي القابلة للاستدعاء خارج App\PdfBuilders لتجنُّب تنفيذ تعليمات برمجية عشوائية من حمولات قائمة انتظار مُعدَّلة.
استخدم service('pdf') أو مساعد الحزمة لتدفقات وحدات التحكم؛ واستخدم مهام قائمة الانتظار للإنشاء طويل الأمد.