การผสาน NextPDF เข้ากับ Symfony

ภาพรวมโดยย่อ

ติดตั้ง nextpdf/symfony เพื่อให้ Flex ลงทะเบียน bundle หรือจะลงทะเบียนด้วยตนเอง เพิ่ม config/packages/nextpdf.yaml แล้วฉีด PdfFactory ใช้หน้านี้เป็นดัชนีสำหรับการผสานรวม โดยแต่ละขั้นตอนชี้ไปยังคู่มือที่ลงรายละเอียดมากกว่า

การติดตั้ง

composer require nextpdf/symfony

bundle นี้ต้องใช้ nextpdf/core^3.0 || ^5.2, symfony/*^7.2 และ psr/log^3.0 คลาสต่าง ๆ จะถูกโหลดอัตโนมัติภายใต้คำนำหน้า PHP Standards Recommendation (PSR)-4 คือ NextPDF\Symfony\ ซึ่งแมปไปยัง src/Symfony/ ตัวโหลดอัตโนมัติ PSR-4 จะแมปคำนำหน้า namespace นี้กับไดเรกทอรีฐาน (PSR-4 §2) สำหรับข้อกำหนดทั้งหมดและแพ็กเกจเสริม โปรดดู /integrations/symfony/install/

การบูตและการค้นพบอัตโนมัติ

เมื่อใช้ Symfony Flex รายการ extra.symfony.bundles ใน composer.json ของ bundle จะลงทะเบียน NextPDF\Symfony\NextPdfBundle สำหรับทุกสภาพแวดล้อม หากไม่ได้ใช้ Flex ให้เพิ่มรายการนี้ใน config/bundles.php ด้วยตนเอง:

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

สำหรับลำดับการบูตทั้งหมดและพฤติกรรมของ compiler pass โปรดดู /integrations/symfony/boot-and-discovery/

การผูก container

ไฟล์ config/services.php ของ bundle จะลงทะเบียนบริการต่อไปนี้:

บริการ / alias	วงจรชีวิต
`NextPDF\Symfony\Service\PdfFactory`	shared, public; ให้ฉีดบริการนี้
`nextpdf.document` → `PdfDocumentInterface` → `Document`	non-shared, public; สร้างใหม่ทุกครั้งที่มีการ resolve
`NextPDF\Contracts\FontRegistryInterface`	shared, ล็อกหลังจาก warmup
`NextPDF\Graphics\ImageRegistry`	shared, `kernel.reset`
`NextPDF\Contracts\DocumentFactoryInterface`	shared
`NextPDF\Symfony\Http\PdfResponse`	public, helper แบบ stateless

การผูกเอกสารถูกกำหนดให้เป็น non-shared โดยเจตนา PSR-11 อนุญาตให้ container คืนค่าที่แตกต่างกันเมื่อเรียก get() ต่อเนื่องกันด้วยตัวระบุเดียวกัน เอกสารที่สร้างใหม่ช่วยหลีกเลี่ยงสถานะข้ามคำขอใน worker ที่ทำงานยาวนาน (PSR-11 §1.1.2) สำหรับตารางบริการและ alias ทั้งหมด รวมถึงการผูก EInvoice แบบมีเงื่อนไข โปรดดู /integrations/symfony/configuration/

เผยแพร่การกำหนดค่า

alias ของการกำหนดค่าคือ nextpdf ให้สร้าง config/packages/nextpdf.yaml เมื่อ Flex เผยแพร่ recipe ระบบจะเพิ่มสำเนาเริ่มต้นให้โดยอัตโนมัติ ทุกคีย์มีค่าเริ่มต้น ดังนั้นไฟล์ขั้นต่ำจึงมีลักษณะดังนี้:

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');
    }
}

สำหรับ controller แบบครบถ้วนและเส้นทางแบบอะซิงโครนัสด้วย Messenger โปรดดู /integrations/symfony/quickstart/

smoke test ของ bundle

ตรวจสอบการเชื่อมต่อโดยไม่ต้องเขียนโค้ดแอปพลิเคชัน:

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

debug:container nextpdf ควรแสดงรายการ PdfFactory alias nextpdf.document และ registry ต่าง ๆ ส่วน lint:container จะตรวจสอบว่าอาร์กิวเมนต์ของบริการทั้งหมด resolve ได้ หากต้องการทดสอบการสร้าง ให้เพิ่ม controller ด้านบน แล้วร้องขอ /hello.pdf

จุดเข้าใช้งาน API สาธารณะ

ขอบเขตของ application programming interface (API) รองรับสัญลักษณ์สาธารณะต่อไปนี้สำหรับโค้ดแอปพลิเคชัน:

สัญลักษณ์	วัตถุประสงค์
`NextPDF\Symfony\Service\PdfFactory::create()`	เอกสาร `Document` ที่สร้างใหม่และกำหนดค่าไว้ล่วงหน้า
`NextPDF\Symfony\Http\PdfResponse::inline()` / `download()`	การตอบสนองแบบบัฟเฟอร์พร้อม security header
`NextPDF\Symfony\Http\PdfResponse::streamInline()` / `streamDownload()`	การตอบสนองแบบสตรีมเป็นชิ้น (chunked)
`NextPDF\Symfony\Message\GeneratePdfMessage`	data transfer object (DTO) สำหรับการสร้างแบบอะซิงโครนัส (ผ่านการตรวจสอบความถูกต้องแล้ว)
`NextPDF\Symfony\Message\PdfBuilderInterface`	สัญญา builder ที่ resolve โดย handler

ความสอดคล้องตามมาตรฐาน

แต่ละแถวแสดงข้อกำหนดเชิงบรรทัดฐานที่กล่าวถึงในหน้านี้ ข้อกำหนดแต่ละข้อถูกตรึงไว้กับ reference_id แบบ 64-hex เต็มจาก corpus ขององค์กรพัฒนามาตรฐาน (SDO) แบบ gated แหล่งที่มา (corpus manifest และ retrieval transport) อยู่ใน _sidecars/rag-citations.yaml

มาตรฐาน	ข้อ	รหัสอ้างอิง (reference_id)	ข้อกำหนด
PSR-11	`psr_11_container#1.1.2.p4`		สัญญาของตัวระบุ has()/get() ของ container
PSR-4	`psr_4_autoload#x1.x2.p5`		การแมป namespace ของตัวโหลดอัตโนมัติ

ดูเพิ่มเติม

/integrations/symfony/install/ — ข้อกำหนดและการลงทะเบียน
/integrations/symfony/boot-and-discovery/ — การค้นพบ การบูต และ compiler pass
/integrations/symfony/configuration/ — สคีมาทั้งหมดและตารางบริการ
/integrations/symfony/quickstart/ — controller ที่รันได้และตัวอย่างแบบอะซิงโครนัส
/integrations/symfony/production-usage/ — ความปลอดภัยของ worker และการสตรีม