دليل مطوّر Symfony

لمحة سريعة

تتعامل حزمة ⁨Symfony⁩ مع الخدمات باعتبارها الأساس. احقِن PdfFactory، واستدعِ create() لكل مستند ⁨PDF⁩، واستخدم بُناة ⁨Messenger⁩ للتوليد غير المتزامن. يمكنك الإبقاء على المصنع كخدمة حاوية، لأن كل استدعاء يُرجع مستندًا جديدًا.

استخدم هذا الدليل عند تصميم المتحكّمات أو الخدمات أو معالِجات ⁨Messenger⁩ أو نقاط التوسيع على مستوى الحزمة لـ nextpdf/symfony.

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

الطبقة	مملوكة من	المسؤولية	لا تضع هنا
المتحكّم	التطبيق	عرّف الطلب واجمع المدخلات وأرجِع PdfResponse.	تخطيط ⁨PDF⁩ مشترك بين حالات الاستخدام.
خدمة التطبيق	التطبيق	تحميل بيانات المجال واختيار باني.	منطق مُجمِّع حاوية ⁨Symfony.⁩
خدمة الباني	التطبيق	طبّق PdfBuilderInterface لبناء المستندات المتزامن أو المصفوف في طابور.	كائنات الطلب أو مديرو الكيانات أو سياق غير قابل للتسلسل.
حزمة ⁨Symfony⁩	nextpdf/symfony	تسجيل الخدمات وشجرة الإعدادات وتمريرة التوسيع الاختيارية ومساعدات الاستجابة وكائنات نقل البيانات (⁨DTOs⁩) الخاصة بـ ⁨Messenger.⁩	سياسة تخزين خاصة بالمستأجر.
المحرّك الأساسي	nextpdf/nextpdf	إنشاء المستند وتسلسله.	استجابة ⁨Symfony⁩ أو سلوك ⁨Messenger.⁩

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

المرحلة	السلوك	إجراء المطوّر
إقلاع الحزمة	NextPdfBundle::build() يسجّل اكتشاف التوسيع الاختياري.	دع ⁨Symfony⁩ يكتشف الحزمة، أو سجّلها في bundles.php.
تحميل الإعدادات	NextPdfExtension::load() يعالج إعدادات nextpdf: ويحمّل تعريفات الخدمات.	أبقِ الإعدادات صريحة ومراعية للبيئة.
استخدام المصنع	PdfFactory::create() يُرجِع مستندًا جديدًا ومُهيّأ.	لا تخزّن المستندات في الخدمات.
مخرَج المتحكّم	PdfResponse يحوّل مستندًا مكتملًا إلى استجابة.	استخدم المساعِد بدلًا من تجميع الترويسات يدويًا.
إرسال ⁨Messenger⁩	GeneratePdfMessage يحمل صنف الباني ومسار المخرَج وسياقًا قابلًا للتسلسل.	أبقِ السياق محدودًا ومناسبًا للقيم القياسية.
معالجة الرسالة	GeneratePdfHandler يحلّ الباني من محدِّد موقع الخدمة ويحفظ المستند.	اجعل البُناة حتميين وعديمي التأثير الجانبي عند التكرار.

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

المسار	الغرض
src/Pdf/Builder/*	الخدمات التي تطبّق PdfBuilderInterface.
src/Pdf/Data/*	كائنات ⁨DTO⁩ صغيرة أو مصفوفات تُستخدم كسياق للباني.
src/Pdf/Storage/*	اختيار جذر التخزين وسياسة اسم ملف المخرَج.
src/Controller/*	نقاط دخول الاستجابة المتزامنة.
tests/Pdf/*	اختبارات الباني والاستجابة و⁨Messenger⁩ والإعدادات.

فضّل خدمات الباني على دوال المساعدة الساكنة؛ فهي أسهل في الوسم والتزيين والاختبار والاستخدام من ⁨Messenger.⁩

<?php

namespace App\Pdf\Builder;

use NextPDF\Core\Document;
use NextPDF\Symfony\Message\PdfBuilderInterface;

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

        return $document;
    }
}

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

<?php

namespace App\Controller;

use App\Pdf\Builder\InvoicePdfBuilder;
use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;

final readonly class InvoiceController
{
    public function __invoke(
        PdfFactory $factory,
        InvoicePdfBuilder $builder,
    ) {
        $document = $builder->build($factory->create(), [
            'title' => 'Invoice 1234',
            'html' => '<h1>Invoice 1234</h1>',
        ]);

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

أبقِ سياق المتحكّم صغيرًا. عندما يحتاج الباني إلى كائنات مجال كثيرة، انقل التنسيق إلى خدمة تطبيق، ومرِّر إلى الباني كائن ⁨DTO⁩ أو مصفوفة مُسوّاة.

نمط ⁨Messenger⁩

يتحقق GeneratePdfMessage من صنف الباني ومسار المخرَج قبل الإرسال. ويتحقق المعالِج من المسار مرة أخرى عند تشغيله.

<?php

use App\Pdf\Builder\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;

$bus->dispatch(new GeneratePdfMessage(
    builderClass: InvoicePdfBuilder::class,
    outputPath: $projectDir . '/var/pdfs/invoice-1234.pdf',
    builderContext: [
        'title' => 'Invoice 1234',
        'html' => '<h1>Invoice 1234</h1>',
    ],
));

لا تضع كيانات ⁨Doctrine⁩ أو الدفقات المفتوحة أو الإغلاقات أو كائنات الطلب أو كائنات الخدمة في builderContext.

نقاط التوسيع

نقطة التوسيع	استخدمها من أجل	القيد
تزيين خدمة PdfFactory	تطبيق الإعدادات الافتراضية للتطبيق قبل وصول المستندات إلى المتحكّمات.	يجب أن يحافظ على دلالات المستند الجديد.
PdfBuilderInterface	تعريف بُناة مستندات مصفوفين في طابور أو قابلين لإعادة الاستخدام.	يجب أن يُرجِع Document.
OptionalExtensionPass	تمكين ميزات ⁨Artisan⁩ أو ⁨Premium⁩ الاختيارية في وقت التصريف.	الإتاحة هي حالة تصريف الحاوية، وليست حالة الطلب.
شجرة إعدادات ⁨Symfony⁩	الإعدادات الافتراضية، و⁨PDF/A⁩، وإعدادات العارض، والتوقيع، وسلطة الختم الزمني (⁨TSA⁩)، و⁨Messenger.⁩	يجب أن تفشل الإعدادات غير الصالحة أثناء بناء الحاوية.
ربط خدمة GeneratePdfHandler	تقييد البُناة الذين يمكن الوصول إليهم من الرسائل المصفوفة في طابور.	يجب أن يُتيح محدِّد موقع الخدمة خدمات الباني المعتمدة فقط.

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

1. أضف خدمة باني بمدخلات حتمية.
2. استخدم PdfFactory::create() في متحكّم أو خدمة.
3. أضف اختبار استجابة لاسم الملف ونوع المحتوى والترويسات.
4. سجّل الباني مع ⁨Messenger⁩ عندما يلزم توليد المستند نفسه بشكل غير متزامن.
5. أضف اختبارات للرسائل غير الصالحة من أجل اسم الصنف ومسار المخرَج وشكل السياق.
6. أضف اختبار تصريف حاوية بإعدادات أدنى وإعدادات إنتاج.
7. قِس زمن العرض والذاكرة تحت إعدادات ⁨PHP⁩ نفسها المستخدمة في الإنتاج.

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

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

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

الاهتمام	الافتراضي	متى تتجاوزه
عمر المصنع	خدمة حاوية.	أبقِ هذا؛ فالمصنع آمن لأنه يُنشئ مستندات جديدة.
عمر المستند	وحدة عمل واحدة.	لا تشاركه أبدًا عبر الطلبات أو الرسائل.
التحقق من مسار المخرَج	مُنشئ الرسالة والمعالِج.	أضف قيود المستأجر أو جذر التخزين في شيفرة التطبيق.
اسم ملف الاستجابة	document.pdf.	تجاوزه بمُعرّفات أعمال مُنقّاة.
نقل ⁨Messenger⁩	async.	استخدم نقلًا مخصّصًا عندما يكون عمل ⁨PDF⁩ كثيفًا.

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

• تُصرّف اختبارات الحاوية الحزمة بإعدادات أدنى وإعدادات إنتاج.
• تؤكّد اختبارات الاستجابة على ترويسات الأمان ومعالجة اسم الملف.
• تؤكّد اختبارات ⁨Messenger⁩ على فشل المسارات غير الصالحة وأسماء أصناف الباني غير الصالحة قبل الإرسال.
• تستخدم اختبارات المعالِج خدمة باني حقيقية ومجلد مخرَج مؤقت.
• تعرض اختبارات الباني مستندًا تمثيليًا وتحفظه تحت أذونات نظام ملفات شبيهة بالإنتاج.
• تغطّي اختبارات التوسيع الاختياري حالات عدم توفر ⁨Artisan⁩ وعدم توفر ⁨Premium⁩ وسلوك ملف تعريف ⁨PDF/A⁩ المُعدّ.