تكامل NextPDF مع Symfony

لمحة سريعة

ثبّت nextpdf/symfony، واسمح لـ ⁨Flex⁩ بتسجيل الحزمة أو سجّلها يدويًا، وأضف config/packages/nextpdf.yaml، واحقن PdfFactory. استخدم هذه الصفحة بوصفها فهرسًا للربط؛ فكل خطوة تشير إلى دليل أكثر تفصيلًا.

التثبيت

composer require nextpdf/symfony

تتطلب الحزمة nextpdf/core^3.0 || ^5.2، وsymfony/*^7.2، و psr/log^3.0. تُحمَّل الأصناف تلقائيًا تحت بادئة ⁨PHP Standards Recommendation⁩ (⁨PSR⁩)-4، وهي NextPDF\Symfony\ المعيَّنة إلى src/Symfony/. يربط محمّل التحميل التلقائي وفق ⁨PSR-4⁩ بادئة مساحة الأسماء هذه بالدليل الأساسي (⁨PSR-4⁩ §2). للاطلاع على المتطلبات الكاملة والحزم الاختيارية، راجع /⁨integrations/symfony/install/.⁩

الإقلاع والاكتشاف التلقائي

مع ⁨Symfony Flex⁩، يسجّل المُدخَل extra.symfony.bundles في ملف composer.json الخاص بالحزمة NextPDF\Symfony\NextPdfBundle في جميع البيئات. من دون ⁨Flex⁩، أضفها يدويًا إلى config/bundles.php:

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

للاطلاع على تسلسل الإقلاع الكامل وسلوك ممرّ المُصرِّف، راجع /⁨integrations/symfony/boot-and-discovery/.⁩

روابط الحاوية

يسجّل ملف config/services.php الخاص بالحزمة الخدمات الآتية:

الخدمة / الاسم المستعار	دورة الحياة
`NextPDF\Symfony\Service\PdfFactory`	مشتركة، عامة؛ احقن هذه
`nextpdf.document` → `PdfDocumentInterface` → `Document`	غير مشتركة، عامة؛ نسخة جديدة عند كل تحليل
`NextPDF\Contracts\FontRegistryInterface`	مشتركة، مقفلة بعد الإحماء
`NextPDF\Graphics\ImageRegistry`	مشتركة، `kernel.reset`
`NextPDF\Contracts\DocumentFactoryInterface`	مشتركة
`NextPDF\Symfony\Http\PdfResponse`	مساعِد عام عديم الحالة

ربط المستند غير مشترك عن قصد. يسمح ⁨PSR-11⁩ للحاوية بإرجاع قيم مختلفة عند استدعاءات get() المتتالية للمعرّف نفسه. يمنع إنشاء مستند جديد تسرّب الحالة بين الطلبات في العمّال طويلي التشغيل (⁨PSR-11⁩ §1.1.2). للاطلاع على الجدول الكامل للخدمات والأسماء المستعارة، بما في ذلك روابط ⁨EInvoice⁩ الشرطية، راجع /⁨integrations/symfony/configuration/.⁩

نشر الإعدادات

الاسم المستعار للإعدادات هو nextpdf. أنشئ config/packages/nextpdf.yaml. عندما ينشر ⁨Flex⁩ وصفة، يضيف لك نسخة افتراضية. لكل مفتاح قيمة افتراضية، لذلك يكون الحد الأدنى للملف كما يأتي:

nextpdf: ~

شجرة الإعدادات الكاملة موثَّقة في /⁨integrations/symfony/configuration/.⁩

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

احقن PdfFactory، ثم أرجع المستند باستخدام PdfResponse:

<?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 PdfController
{
    #[Route('/hello.pdf', name: 'hello_pdf')]
    public function hello(PdfFactory $pdf): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->cell(0, 10, 'Hello from NextPDF on Symfony.');

        return PdfResponse::inline($doc, 'hello.pdf');
    }
}

للاطلاع على المتحكّم الكامل ومسار ⁨Messenger⁩ غير المتزامن، راجع /⁨integrations/symfony/quickstart/.⁩

اختبار تحقق سريع للحزمة

تحقّق من الربط من دون كتابة أي كود للتطبيق:

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console lint:container

ينبغي أن يسرد debug:container nextpdf الخدمة PdfFactory، والاسم المستعار nextpdf.document، والسجلّات. يتحقّق lint:container من أن كل وسيط خدمة قابل للحل. لاختبار التوليد، أضف المتحكّم أعلاه، ثم اطلب /hello.pdf.

نقاط الدخول العامة لـ ⁨API⁩

يدعم سطح واجهة برمجة التطبيقات ⁨application programming interface⁩ (⁨API⁩) الرموز العامة الآتية لكود التطبيق:

الرمز	الغرض
`NextPDF\Symfony\Service\PdfFactory::create()`	`Document` جديد ومُهيَّأ مسبقًا
`NextPDF\Symfony\Http\PdfResponse::inline()` / `download()`	استجابة مُخزَّنة مؤقتًا مع ترويسات أمان
`NextPDF\Symfony\Http\PdfResponse::streamInline()` / `streamDownload()`	استجابة متدفّقة مقسَّمة إلى أجزاء
`NextPDF\Symfony\Message\GeneratePdfMessage`	كائن نقل بيانات ⁨data transfer object⁩ (⁨DTO⁩) للتوليد غير المتزامن (مُتحقَّق منه)
`NextPDF\Symfony\Message\PdfBuilderInterface`	عقد البنّاء الذي يحلّه المعالِج

المطابقة

يسرد كل صف ادعاءً معياريًا واردًا في هذه الصفحة. يُثبَّت كل ادعاء إلى reference_id كامل من 64 رقمًا ست عشريًا مأخوذ من مجموعة منظمة تطوير المعايير ⁨standards development organization⁩ (⁨SDO⁩) المقيَّدة الوصول. يوجد المنشأ (بيان المجموعة وآلية نقل الاسترجاع) في _sidecars/rag-citations.yaml.

المواصفة	البند	⁨reference_id⁩	الادعاء
⁨PSR-11⁩	`psr_11_container#1.1.2.p4`		عقد المعرّف لدالّتي ⁨has⁩()/⁨get⁩() في الحاوية
⁨PSR-4⁩	`psr_4_autoload#x1.x2.p5`		تعيين مساحة الأسماء لمحمّل التحميل التلقائي

انظر أيضًا

/⁨integrations/symfony/install/⁩ — المتطلبات والتسجيل.
/⁨integrations/symfony/boot-and-discovery/⁩ — الاكتشاف والإقلاع وممرّ المُصرِّف.
/⁨integrations/symfony/configuration/⁩ — المخطط الكامل وجدول الخدمات.
/⁨integrations/symfony/quickstart/⁩ — متحكّم قابل للتشغيل ومثال غير متزامن.
/⁨integrations/symfony/production-usage/⁩ — أمان العمّال والبثّ المتدفّق.