دليل مطوّري Laravel

نظرة سريعة

تتكيف حزمة ⁨Laravel NextPDF⁩ مع أعراف ⁨Laravel⁩ دون تغيير دورة حياة المستند الأساسية. تملك الحاوية السجلّات والمصانع المشتركة. كل مستند ⁨PDF⁩ قابل للتخلص منه، لذا يجب بناؤه أو إرجاعه أو دفقه أو حفظه مرة واحدة فقط.

استخدم هذا الدليل عند تصميم خدمات التطبيق أو مهام قائمة الانتظار أو تدفقات الاستجابة أو تغطية الاختبارات لـ nextpdf/laravel.

حدود البنية

الطبقة	مملوكة من	المسؤولية	لا تضع هنا
المتحكّم	التطبيق	تفويض الطلب، واختيار باني المستند، وإرجاع الاستجابة.	قواعد تخطيط ⁨PDF⁩ المشتركة بين حالات الاستخدام.
خدمة التطبيق	التطبيق	جمع بيانات المجال واستدعاء كود بناء المستند.	منطق إقلاع الحاوية أو إعدادات الحزمة.
باني المستند	التطبيق	ترجمة بيانات المجال إلى استدعاءات مستند ⁨NextPDF.⁩	كائنات الطلب، أو منطق استعلام ⁨Eloquent⁩، أو تفاصيل نقل قائمة الانتظار.
تكامل ⁨Laravel⁩	nextpdf/laravel	ربط المصانع، والسجلّات، والموقّع، وعميل ⁨TSA⁩، والواجهة، والاستجابات، ومهمة قائمة الانتظار.	مسارات التخزين الخاصة بالأعمال أو سياسة المستأجر.
المحرّك الأساسي	nextpdf/nextpdf	بناء ملف ⁨PDF⁩ وتسلسله.	سياسة استجابة ⁨Laravel⁩، أو قائمة الانتظار، أو نظام الملفات.

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

المرحلة	السلوك	إجراء المطوّر
تسجيل مزوّد الخدمة	يسجّل NextPdfServiceProvider::register() السجلّات المشتركة، ومصنع المستندات، وربط المستند، وعميل ⁨HTTP⁩، وعميل سلطة الطوابع الزمنية (⁨TSA⁩)، والموقّع، وعقود الفاتورة الإلكترونية الاختيارية.	انشر config/nextpdf.php وراجعه قبل الإنتاج.
دقة المستند	تحلّ واجهة Pdf وربط PdfDocumentInterface مستندًا جديدًا عبر DocumentFactoryInterface.	حلّ مستندًا مرة واحدة لكل طلب، أو أمر، أو مهمة في قائمة الانتظار.
التأليف	يستدعي كود التطبيق واجهات برمجة المستند الأساسية عبر الواجهة أو المستند المحقون.	أبقِ استخراج بيانات المجال خارج باني المستند.
الخرج النهائي	يصدر PdfResponse خرج ⁨HTTP⁩، أو يُحفظ المستند على القرص.	اختر مسار خرج نهائيًا واحدًا لكل مستند.
تنفيذ قائمة الانتظار	يعيد GeneratePdfJob بناء المستند في العامل ويتحقق من مسار الخرج مرة أخرى.	مرّر سياقًا عدديًا وأبقِ ردود النداء عديمة التأثير الجانبي عند التكرار.

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

المسار	الغرض
app/Pdf/Builders/*	بناة مستندات خالصون يتلقون البيانات ويُرجعون مستندًا مكتملًا.
app/Pdf/Data/*	كائنات نقل بيانات صغيرة (⁨DTOs⁩) تحمل مدخلات المستند المُفوّضة مسبقًا.
app/Services/*	تنسيق التطبيق، والاستعلامات، وتسليم التفويض، واختيار مسار التخزين.
app/Jobs/*	أغلفة اختيارية حول GeneratePdfJob عندما يحتاج التطبيق إلى مهام مُسمّاة.
tests/Feature/Pdf/*	اختبارات استجابة ⁨HTTP⁩، وإرسال قائمة الانتظار، والتفويض.
tests/Unit/Pdf/*	اختبارات الباني بمدخلات حتمية صغيرة.

أبقِ البناة مستقلين عن كائنات طلب ⁨Laravel.⁩ ينبغي أن تتمكّن من استدعاء الباني من متحكّم، أو أمر، أو اختبار، أو عامل قائمة انتظار بالمدخلات نفسها.

<?php

namespace App\Pdf\Builders;

use App\Pdf\Data\InvoicePdfData;
use NextPDF\Contracts\PdfDocumentInterface;

final readonly class InvoicePdfBuilder
{
    public function build(PdfDocumentInterface $pdf, InvoicePdfData $data): PdfDocumentInterface
    {
        $pdf->setTitle($data->title)
            ->addPage()
            ->setFont('dejavusans', '', 12)
            ->writeHtml($data->html);

        return $pdf;
    }
}

نمط الاستجابة المتزامن

استخدم حقن المُنشئ عندما يكون تدفق ⁨PDF⁩ جزءًا من منطق التطبيق. استخدم الواجهة فقط في تدفقات المتحكّم القصيرة عندما يكون النمط الساكن أسهل قراءة.

<?php

namespace App\Http\Controllers;

use App\Pdf\Builders\InvoicePdfBuilder;
use App\Pdf\Data\InvoicePdfData;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final readonly class DownloadInvoiceController
{
    public function __invoke(
        PdfDocumentInterface $pdf,
        InvoicePdfBuilder $builder,
    ) {
        $document = $builder->build(
            $pdf,
            InvoicePdfData::fromInvoiceId(1234),
        );

        return PdfResponse::download($document, 'invoice-1234.pdf');
    }
}

تجسّد مساعدات الاستجابة بايتات المستند قبل بناء استجابة ⁨Laravel.⁩ فهي مساعدات استجابة، وليست مُصيّرات تعمل في الخلفية.

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

يقبل GeneratePdfJob قابلًا للاستدعاء للباني ومسار خرج. تتحقق المهمة من المسارات غير الآمنة وقت التنفيذ. ومع ذلك، ينبغي لكود التطبيق اختيار جذر تخزين آمن للمستأجر قبل الإرسال.

<?php

use App\Pdf\Builders\QueuedInvoiceBuilder;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    outputPath: storage_path('app/pdfs/invoice-1234.pdf'),
    builder: [QueuedInvoiceBuilder::class, 'build'],
)->onQueue(config('nextpdf.queue.queue', 'pdf'));

أبقِ ردود نداء قائمة الانتظار صغيرة. يُفضّل كتابة الحالة الدائمة من مستمع مهام التطبيق بدل تخزين إغلاقات معقّدة في حمولة قائمة الانتظار.

نقاط التوسيع

نقطة التوسيع	استخدمها لـ	القيد
ربط PdfDocumentInterface	استبدال إنشاء المستند أو تزيينه لإعدادات افتراضية على مستوى التطبيق.	يجب أن يُرجع نسخة مستند جديدة.
DocumentFactoryInterface	أنشئ مستندات جديدة صراحةً في الخدمات والاختبارات.	لا تخزّن المستندات المُرجَعة مؤقتًا.
config/nextpdf.php	الإعدادات الافتراضية، وإعدادات قائمة الانتظار، وإعدادات مُصيّر ⁨Chrome⁩، وخطافات التوقيع، و⁨TSA⁩، وذاكرة ⁨OCSP⁩ المؤقتة.	تعامل مع متغيرات البيئة بوصفها إعدادات نشر، وليست مدخلات طلب.
باني GeneratePdfJob	بناء المستندات بشكل غير متزامن.	يجب أن يكون القابل للاستدعاء قابلًا للتسلسل عبر ناقل قائمة انتظار ⁨Laravel.⁩
ردود نداء النجاح/الفشل	إشعار ما بعد التوليد أو التنظيف.	أبقِ ردود النداء عديمة التأثير عند التكرار وواعية بالآثار الجانبية.
عقود ⁨Premium⁩ الاختيارية	مُضمِّن الفاتورة الإلكترونية، والمدقّق، والملف الشخصي، ومشغّل ⁨Schematron.⁩	حلّها فقط حيث تكون الحزمة الاختيارية مثبّتة ومرخّصة.

سير عمل التطوير

1. ابنِ المستند الأول بشكل متزامن في متحكّم أو اختبار ميزة.
2. انقل كود التخطيط إلى صنف بانٍ ضمن app/Pdf/Builders.
3. انقل منطق الاستعلام والتفويض إلى خدمة تطبيق.
4. أضف اختبارات PdfResponse للترويسات وأسماء الملفات.
5. انقل التوليد البطيء أو كبير الحجم إلى GeneratePdfJob.
6. أضف اختبارات قائمة انتظار للسياق المُسلسل، وسياسة مسار الخرج، ومعالجة الفشل.
7. قِس الذاكرة وزمن التصيير ببيانات إنتاج تمثيلية.

معالجة الفشل

الفشل	حيث ينبغي معالجته	الاستجابة الموصى بها
طلب غير صالح أو مستند غير مُفوّض	المتحكّم أو السياسة.	أرجِع استجابة التفويض أو التحقق المعتادة في التطبيق.
خط مفقود أو صورة غير صالحة	اختبار الباني وتسجيل التطبيق.	أفشِل الطلب أو المهمة؛ لا تُصدِر ملفات ⁨PDF⁩ جزئية.
مسار خرج غير آمن	خدمة تخزين التطبيق وGeneratePdfJob.	ارفض قبل الإرسال واعتمد على التحقق من جانب العامل بوصفه دفاعًا في العمق.
فشل التوقيع أو ⁨TSA⁩	حدود خدمة التوقيع.	قرّر ما إذا كان يجوز ترك المستند دون توقيع؛ والافتراضي هو الفشل المغلق للمستندات المنظّمة.
انتهاء مهلة قائمة الانتظار	إعدادات عامل قائمة الانتظار وقابلية المراقبة.	أعِد المحاولة فقط عندما يكون الباني حتميًا ويكون مسار الخرج آمنًا للكتابة فوقه.

الإعدادات الافتراضية الآمنة

الجانب المعني	الافتراضي	متى تتجاوزه
اسم قائمة الانتظار	pdf	استخدم قائمة انتظار مخصصة عندما يتنافس التوليد مع المهام الموجّهة إلى المستخدم.
مهلة المهمة	120 ثانية	زِدها فقط بعد قياس حجم المستند وسعة العامل.
اسم ملف الاستجابة	document.pdf	استخدم معرّفات أعمال مُطهّرة.
سجلّ الخطوط	مشترك ومقفل بعد الإحماء.	أضف preload_fonts للخطوط المستخدمة في المسارات الساخنة.
سجلّ الصور	ذاكرة مؤقتة مشتركة ومحدودة.	خفّض image_cache_mb للعمّال المحدودي الذاكرة.
تقسيم الاستجابة المدفوقة إلى كتل	كتل بحجم 64 ⁨KB.⁩	لا تعتمد على حدود الكتل؛ فهي تفصيل من تفاصيل الخرج.

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

• تتحقق اختبارات المتحكّم من Content-Type، وContent-Disposition، والترويسات الدفاعية.
• تستخدم اختبارات الباني كائنات ⁨DTO⁩ حتمية ولا تستعلم من قاعدة البيانات.
• تتحقق اختبارات قائمة الانتظار من أن الباني يتلقى مستندًا جديدًا.
• تغطي اختبارات المسار الاجتياز، ومُغلِّف الدفق، والبايت الصفري، ورفض غير .pdf.
• تُصيّر اختبارات العامل مستندات تمثيلية ضمن حد الذاكرة نفسه المستخدم في الإنتاج.
• تغطي اختبارات التوقيع الاختيارية الشهادة المفقودة، وكلمة المرور غير الصالحة، وعدم توفر ⁨TSA⁩، ومستوى التوقيع المُهيّأ.