مرجع API لـ Symfony

لمحة سريعة

تتيح حزمة ⁨Symfony⁩ تسجيل الحزمة، وشجرة الإعداد، ومصنعًا قابلًا للحقن لإنشاء مستندات جديدة، ومساعدات استجابة ⁨HTTP⁩، وأنواع ⁨Messenger⁩ للإنشاء غير المتزامن. يستخدم معظم كود التطبيق رمزين فقط: خدمة PdfFactory التي تحقنها لإنشاء Document، ومساعد PdfResponse الذي يحوّل ذلك المستند إلى استجابة ⁨HTTP⁩ آمنة. أما الرموز المتبقية (الحزمة، والامتداد، وممر المُجمِّع، وشجرة الإعداد، وكائن نقل البيانات (⁨DTO⁩) الخاص بـ ⁨Messenger⁩، والمعالِج) فهي توصيل تُعِدّه مرة واحدة أو يديره إطار العمل نيابةً عنك.

ابدأ من هنا: احقن NextPDF\Symfony\Service\PdfFactory، واستدعِ create() للحصول على Document جديد، وأعِده باستخدام NextPDF\Symfony\Http\PdfResponse::download(). يوضّح المثال الأول هذا التدفق.

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

استخدم هذه المقتطفات الثلاثة القابلة للتشغيل لأكثر المهام شيوعًا. لا يستخدم كل مقتطف إلا الرموز المتحقَّق منها والموثَّقة في الجداول التالية.

إرجاع تنزيل ⁨PDF⁩ من وحدة تحكُّم: احقن المصنع، وأنشئ مستندًا، ومرّره إلى مساعد الاستجابة:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

ما الذي يفعله: يُرجِع PdfFactory::create() مستند Document جديدًا ومُهيَّأً مسبقًا. يرسله PdfResponse::download() مع Content-Type: application/pdf، وتصرُّف ملحق، وترويسات الأمان الثابتة للحزمة.

بثُّ ملف ⁨PDF⁩ كبير لإبقاء ذروة استهلاك الذاكرة منخفضة: استخدم مساعد البث وأرجِع StreamedResponse:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\Routing\Attribute\Route;

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

ما الذي يفعله: يبثُّ PdfResponse::streamDownload() ملف ⁨PDF⁩ المُجسَّد على هيئة أجزاء ويُسقِط Content-Length؛ استخدم streamInline() للمكافئ المضمَّن.

إرسال ملف ⁨PDF⁩ للإنشاء غير المتزامن: أرسِل GeneratePdfMessage إلى وسيلة نقل ⁨Messenger⁩ كي يُنفَّذ التصيير على عامل:

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

ما الذي يفعله: يحمل كائن نقل البيانات (⁨DTO⁩) سلسلة نصية لاسم صنف المُنشئ ومسار إخراج متحقَّقًا منه. يحلُّ المعالِج المُنشئ، ثم يُنشئ المستند ويحفظه على العامل. يطبِّق صنف المُنشئ PdfBuilderInterface ويُسجَّل في مُحدِّد موقع خدمات (راجع دليل البدء السريع لـ ⁨Symfony⁩ للاطلاع على توصيل مُحدِّد الموقع والعامل).

المصنع

استخدم هذا الجدول للاطلاع على المُنشئ الدقيق وعقد create() للخدمة القابلة للحقن التي تُنشئ مستندات جديدة.

الرمز	المعاملات	السلوك الافتراضي	يُرجِع	يطرح استثناءً أو يفشل بـ	ملاحظات
`new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)`	`factory`: المصنع الأساسي؛ `defaults`: المُنشئ، والمؤلف، واللغة، والهوامش؛ `pdfa`: ملف ⁨PDF/A⁩ اختياري؛ `artisanConfig`: إعداد مُصيِّر ⁨Chrome⁩ اختياري.	لا تُطبَّق الإعدادات الافتراضية إلا عند ضبطها.	`PdfFactory`	أخطاء توصيل الحاوية.	يمكن أن تكون الخدمة مفردة لأن `create()` يُرجِع مستندًا جديدًا.
`PdfFactory::create()`	لا شيء.	يطبِّق المُنشئ واللغة؛ ويطبِّق المؤلف فقط عندما لا يكون فارغًا؛ ويطبِّق ⁨PDF/A⁩ وإعداد ⁨Artisan⁩ فقط عند توفُّرهما.	`NextPDF\Core\Document`	أخطاء الإعداد الأساسي.	استخدمه مرة واحدة لكل طلب أو أمر أو رسالة.
`PdfFactory::setArtisanAvailable(bool $available)`	`available`: راية توفُّر وقت الترجمة.	مُعطَّل حتى يُمكِّنه ممر المُجمِّع.	`void`	لا شيء متوقَّع.	خُطّاف داخلي يستدعيه ممر مُجمِّع الامتداد الاختياري.
`PdfFactory::setProAvailable(bool $available)`	`available`: راية توفُّر وقت الترجمة.	مُعطَّل حتى يُمكِّنه ممر المُجمِّع.	`void`	لا شيء متوقَّع.	خُطّاف داخلي لتوفُّر ⁨Premium.⁩

الحزمة والامتداد والإعداد

استخدم الجدول الأول لطبقة التوصيل: تسجيل الحزمة، وشجرة إعداد nextpdf، واكتشاف الامتداد الاختياري. ويسرد الجدول الثاني مفاتيح الإعداد.

الرمز	المعاملات	السلوك الافتراضي	يُرجِع	يطرح استثناءً أو يفشل بـ	ملاحظات
`NextPdfBundle::build(ContainerBuilder $container)`	باني حاوية ⁨Symfony.⁩	يستدعي طريقة البناء الأصلية ويسجِّل `OptionalExtensionPass`.	`void`	أخطاء تسجيل ممر المُجمِّع.	يُمكِّن اكتشاف ميزتَي ⁨Artisan⁩ و⁨Premium⁩ الاختياريتين.
`NextPdfBundle::getPath()`	لا شيء.	يُرجِع المسار الجذري للحزمة.	`string`	لا شيء متوقَّع.	يُستخدم لاكتشاف حزم ⁨Symfony⁩ وتحميل الموارد.
`NextPdfExtension::load(array $configs, ContainerBuilder $container)`	مصفوفات إعداد المستخدم وباني الحاوية.	يعالج إعداد `nextpdf`، ويخزِّن المعاملات المُحلَّلة، ويحمِّل تعريفات الخدمات، ويتحقق من الامتدادات المطلوبة.	`void`	أخطاء التحقق من الإعداد، أو تحميل الخدمات، أو الامتداد المفقود.	الامتدادان المطلوبان هما `mbstring` و`zlib`.
`NextPdfExtension::getAlias()`	لا شيء.	يستخدم `nextpdf` بوصفه مفتاح الإعداد الجذري.	`string`	لا شيء متوقَّع.	أعِدّ الحزمة تحت `nextpdf:`.
`Configuration::getConfigTreeBuilder()`	لا شيء.	يُعرِّف شجرة إعداد `nextpdf` المتحقَّق منها.	`TreeBuilder`	أخطاء تعريف إعداد ⁨Symfony.⁩	يحاكي شكل إعداد ⁨Laravel⁩ كلما كان ذلك عمليًّا.
`OptionalExtensionPass::process(ContainerBuilder $container)`	باني حاوية ⁨Symfony.⁩	يكتشف خدمتَي ⁨Artisan⁩ و⁨Premium⁩ الاختياريتين ويبدِّل رايات توفُّر المصنع.	`void`	أخطاء توصيل ممر المُجمِّع.	يُجرى أثناء تجميع الحاوية.

مفتاح الإعداد	النوع	السلوك الافتراضي	ملاحظات
`page_format`	تعداد	`A4`؛ تشمل القيم المسموح بها `A3`، و`A5`، و`Letter`، و`Legal`، و`Tabloid`.	ينطبق على إنشاء المستند الافتراضي.
`orientation`	تعداد	`P`؛ القيم المسموح بها هي `P` و`L`.	استخدم استدعاءات مستند صريحة عندما تحتاج الصفحة إلى اتجاه مختلف.
`unit`	تعداد	`mm`؛ القيم المسموح بها هي `pt`، و`mm`، و`cm`، و`in`.	يُبقي الإعدادات الافتراضية لإطار العمل متوافقة مع الوحدات الأساسية.
`pdfa`	`string	null`	`null`؛ القيم المسموح بها هي `4`، و`4e`، و`4f`.
`fonts_path` / `cache_path`	`string`	مسار خطوط المشروع ومسار ذاكرة التخزين المؤقت للنواة.	أبقِ كل مسار قابلًا للقراءة أو الكتابة بحسب دوره في وقت التشغيل.
`signature.*`	`array`	مُعطَّل افتراضيًّا بمستوى توقيع `B-B`.	يوفِّر الشهادة، والمفتاح، وكلمة المرور، والشهادات الإضافية، والمستوى.
`tsa.*`	`array`	مُعطَّل عندما يكون مُحدِّد موقع الموارد الموحَّد (⁨URL⁩) `null`؛ تبلغ المهلة الافتراضية 30 ثانية.	يدعم بيانات الاعتماد، وملفات أمان طبقة النقل المتبادل (⁨mTLS⁩)، وتثبيتات المفتاح العام، وسياسة ⁨HTTP.⁩
`ocsp_cache.*`	`array`	مُفعَّل بمدة بقاء (⁨TTL⁩) قدرها 86400 ثانية.	يُستخدم بواسطة تدفقات التحقق والتوقيع طويل الأمد عند توفُّرها.
`messenger.*`	`array`	وسيلة النقل `async`، المهلة 120، عدد المحاولات 3.	يُستخدم بواسطة تدفقات الإنشاء غير المتزامن.
`artisan.*`	`array`	مُصيِّر ⁨Chrome⁩ مُعطَّل ما لم يُهيَّأ ويُثبَّت.	يرتبط بـ `ChromeRendererConfig` عند توفُّر المُصيِّر الاختياري.
`defaults.*`	`array`	المُنشئ `NextPDF`، والمؤلف فارغ، واللغة `en`، والهوامش والخط الافتراضية.	يُطبَّق بواسطة `PdfFactory::create()`.

استجابات ⁨HTTP⁩

استخدم هذا الجدول لاختيار مساعد الاستجابة بحسب وضع العرض والتخزين المؤقت: العرض المضمَّن أو التنزيل، المخزَّن مؤقتًا أو المبثوث. كما يوضّح سلوك اسم الملف والترويسات.

الرمز	المعاملات	السلوك الافتراضي	يُرجِع	يطرح استثناءً أو يفشل بـ	ملاحظات
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: المستند المُنشأ؛ `filename`: اسم ملف الاستجابة.	يضيف `.pdf` عند غيابه.	`Symfony\Component\HttpFoundation\Response`	أخطاء التسلسل الأساسي.	يضبط نوع محتوى ⁨PDF⁩ والترويسات الدفاعية.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	كما في `inline`؛ التصرُّف ملحق.	استجابة تنزيل عبر المتصفِّح.	`Response`	كما في `inline`.	استخدمه للتنزيلات الصريحة.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	كما في `inline`.	يبثُّ بايتات ملف ⁨PDF⁩ المُجسَّد على هيئة أجزاء.	`StreamedResponse`	كما في `inline`.	لا يتجنَّب تجسيد المستند.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	كما في `streamInline`؛ التصرُّف ملحق.	استجابة بث تنزيل.	`StreamedResponse`	كما في `streamInline`.	طبِّق سياسة حجم الإخراج قبل التصيير.

⁨Messenger⁩

استخدم هذا الجدول للمسار غير المتزامن: كائن نقل البيانات (⁨DTO⁩) الخاص بالرسالة التي ترسلها، وواجهة المُنشئ التي تطبِّقها، والمعالِج الذي يعمل على العامل.

الرمز	المعاملات	السلوك الافتراضي	يُرجِع	يطرح استثناءً أو يفشل بـ	ملاحظات
`new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])`	`builderClass`: سلسلة نصية لاسم صنف يطبِّق `PdfBuilderInterface`؛ `outputPath`: هدف `.pdf`؛ `builderContext`: بيانات قابلة للتسلسل.	مصفوفة سياق فارغة.	كائن نقل بيانات (⁨DTO⁩) للرسالة.	`InvalidArgumentException` عند اسم صنف مؤهَّل بالكامل (⁨FQCN⁩) غير صالح، أو مُغلِّف دفق، أو بايت فارغ، أو اجتياز، أو مسار فارغ، أو هدف لا ينتهي بـ `.pdf`.	تحمل وسائل نقل ⁨Messenger⁩ بيانات، لا دوالَّ مغلَقة.
`PdfBuilderInterface::build(Document $document, array $context): Document`	`document`: مستند جديد مُهيَّأ؛ `context`: بيانات رسالة قابلة للتسلسل.	لا يوجد سياق افتراضي يتجاوز قيمة الرسالة.	`Document` مُهيَّأ.	استثناءات خاصة بالمُنشئ.	اجعل المُنشئات حتمية وغير متأثرة بالتكرار.
`new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)`	مصنع ⁨PDF⁩ ومُحدِّد موقع خدمة المُنشئ الموسوم.	لا يُنشأ أي مستند أثناء الإنشاء.	`GeneratePdfHandler`	أخطاء توصيل الحاوية.	ينبغي ألا يكشف مُحدِّد الموقع إلا تطبيقات `PdfBuilderInterface`.
`GeneratePdfHandler::__invoke(GeneratePdfMessage $message)`	`message`: كائن نقل بيانات (⁨DTO⁩) للرسالة متحقَّق منه.	يحلُّ المُنشئ من الحاوية، ويُنشئ المستند، ويحفظه.	`void`	خدمة مُنشئ مفقودة، أو نتيجة مُنشئ غير صالحة، أو أخطاء كتابة أساسية.	فضِّل مُنشئات الخدمة على ردود النداء الساكنة.

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

لا تخزِّن Document بوصفه خدمة. خزِّن PdfFactory واستدعِ create() لكل وحدة عمل.
ضع في قائمة الانتظار السياق القابل للتسلسل فقط. لا تضع تدفقات مفتوحة، أو دوالَّ مغلَقة، أو كائنات طلب داخل builderContext.
استخدم سياسة مسار إخراج أكثر صرامة من كائن نقل البيانات (⁨DTO⁩) عندما تكون للنشر جذور تخزين خاصة بكل مستأجر.