ข้อมูลอ้างอิง API สำหรับ Symfony

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

แพ็กเกจ Symfony เปิดให้ใช้การลงทะเบียนบันเดิล โครงสร้างการกำหนดค่า แฟกทอรีที่ฉีด (inject) ได้สำหรับสร้างเอกสารใหม่ ตัวช่วยตอบสนองตาม Hypertext Transfer Protocol (HTTP) และชนิดต่าง ๆ ของ Messenger สำหรับการสร้างแบบอะซิงโครนัส โค้ดแอปพลิเคชันส่วนใหญ่ใช้สัญลักษณ์เพียงสองรายการ ได้แก่บริการ PdfFactory ที่คุณฉีดเข้ามาเพื่อสร้าง Document และตัวช่วย PdfResponse ที่แปลงเอกสารนั้นให้เป็นการตอบสนอง HTTP ที่ปลอดภัย สัญลักษณ์อื่น ๆ เช่นบันเดิล เอ็กซ์เทนชัน คอมไพเลอร์พาส โครงสร้างการกำหนดค่า ดาตาทรานสเฟอร์ออบเจกต์ (DTO) ของ Messenger และแฮนด์เลอร์ เป็นส่วนการเชื่อมต่อ (wiring) ที่คุณกำหนดค่าเพียงครั้งเดียวหรือปล่อยให้เฟรมเวิร์กจัดการ

เริ่มต้นที่นี่: ฉีด NextPDF\Symfony\Service\PdfFactory เรียก create() เพื่อรับ Document ใหม่ แล้วส่งกลับด้วย NextPDF\Symfony\Http\PdfResponse::download() ตัวอย่างแรกแสดงโฟลว์นี้

งานที่พบบ่อย

ใช้สนิปเพ็ตที่รันได้สามชิ้นนี้สำหรับงานที่พบบ่อยที่สุด สนิปเพ็ตแต่ละชิ้นใช้เฉพาะสัญลักษณ์ที่ได้รับการยืนยันและบันทึกไว้ในตารางถัดไป

ส่งกลับการดาวน์โหลด Portable Document Format (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 การกำหนดการแสดงผลแบบไฟล์แนบ (attachment disposition) และเฮดเดอร์ความปลอดภัยแบบคงที่ของบันเดิล

สตรีม 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 ที่ทำให้เป็นรูปธรรมแล้ว (materialized) ออกมาเป็นช่วง ๆ และไม่ใส่ Content-Length ใช้ streamInline() สำหรับรูปแบบ inline ที่เทียบเท่ากัน

ส่ง 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 บรรจุ class-string ของบิลเดอร์และพาทเอาต์พุตที่ตรวจสอบแล้ว แฮนด์เลอร์จะรีโซลฟ์บิลเดอร์ สร้างเอกสาร และบันทึกบนเวิร์กเกอร์ คลาสบิลเดอร์ต้องอิมพลิเมนต์ PdfBuilderInterface และลงทะเบียนไว้ในเซอร์วิสโลเคเตอร์ (ดู Symfony quickstart สำหรับการเชื่อมต่อโลเคเตอร์และเวิร์กเกอร์)

แฟกทอรี

ใช้ตารางนี้เพื่อตรวจสอบสัญญาที่แน่นอนของคอนสตรักเตอร์และ 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	เรียกเมท็อด build ของพาเรนต์และลงทะเบียน `OptionalExtensionPass`	`void`	ข้อผิดพลาดในการลงทะเบียนคอมไพเลอร์พาส	เปิดใช้การตรวจจับฟีเจอร์ Artisan และ Premium เสริม
`NextPdfBundle::getPath()`	ไม่มี	ส่งคืนพาทรากของแพ็กเกจ	`string`	ไม่คาดว่าจะมี	ใช้โดยการค้นพบบันเดิลของ Symfony และการโหลดทรัพยากร
`NextPdfExtension::load(array $configs, ContainerBuilder $container)`	อาร์เรย์การกำหนดค่าของผู้ใช้และตัวสร้างคอนเทนเนอร์	ประมวลผลการกำหนดค่า `nextpdf` จัดเก็บพารามิเตอร์ที่รีโซลฟ์แล้ว โหลดนิยามบริการ และตรวจสอบเอ็กซ์เทนชันที่จำเป็น	`void`	ข้อผิดพลาดในการตรวจสอบการกำหนดค่า การโหลดบริการ หรือเอ็กซ์เทนชันที่ขาดหายไป	เอ็กซ์เทนชันที่จำเป็นคือ `mbstring` และ `zlib`
`NextPdfExtension::getAlias()`	ไม่มี	ใช้ `nextpdf` เป็นคีย์การกำหนดค่าราก (root config key)	`string`	ไม่คาดว่าจะมี	กำหนดค่าบันเดิลภายใต้ `nextpdf:`
`Configuration::getConfigTreeBuilder()`	ไม่มี	กำหนดโครงสร้างการกำหนดค่า `nextpdf` ที่ตรวจสอบแล้ว	`TreeBuilder`	ข้อผิดพลาดในการกำหนดนิยามการกำหนดค่าของ Symfony	สะท้อนรูปแบบการกำหนดค่าของ Laravel เท่าที่ทำได้
`OptionalExtensionPass::process(ContainerBuilder $container)`	ตัวสร้างคอนเทนเนอร์ของ Symfony	ตรวจจับบริการ Artisan และ Premium เสริม และสลับแฟล็กความพร้อมใช้งานของแฟกทอรี	`void`	ข้อผิดพลาดในการเชื่อมต่อคอมไพเลอร์พาส	ทำงานระหว่างการคอมไพล์คอนเทนเนอร์

คีย์การกำหนดค่า	ชนิด	พฤติกรรมค่าเริ่มต้น	หมายเหตุ
`page_format`	enum	`A4`; ค่าที่อนุญาตรวมถึง `A3`, `A5`, `Letter`, `Legal`, และ `Tabloid`	นำไปใช้กับการสร้างเอกสารค่าเริ่มต้น
`orientation`	enum	`P`; ค่าที่อนุญาตคือ `P` และ `L`	ใช้การเรียกเอกสารแบบชัดเจนเมื่อหน้าต้องใช้การวางแนวต่างออกไป
`unit`	enum	`mm`; ค่าที่อนุญาตคือ `pt`, `mm`, `cm`, และ `in`	รักษาค่าเริ่มต้นของเฟรมเวิร์กให้สอดคล้องกับหน่วยของคอร์
`pdfa`	`string	null`	`null`; ค่าที่อนุญาตคือ `4`, `4e`, และ `4f`
`fonts_path` / `cache_path`	`string`	พาทฟอนต์ของโปรเจกต์และพาทแคชของเคอร์เนล	ให้แต่ละพาทอ่านหรือเขียนได้ตามบทบาทขณะรันไทม์ของพาทนั้น
`signature.*`	`array`	ปิดใช้งานตามค่าเริ่มต้นด้วยระดับลายเซ็น `B-B`	ระบุใบรับรอง คีย์ รหัสผ่าน ใบรับรองเพิ่มเติม และระดับ
`tsa.*`	`array`	ปิดใช้งานเมื่อ Uniform Resource Locator (URL) เป็น `null`; ค่าเริ่มต้นของไทม์เอาต์คือ 30 วินาที	รองรับข้อมูลรับรอง (credentials) ไฟล์ mutual Transport Layer Security (mTLS) การปักหมุดคีย์สาธารณะ (public-key pins) และนโยบาย HTTP
`ocsp_cache.*`	`array`	เปิดใช้งานด้วย time to live (TTL) 86400 วินาที	ใช้โดยโฟลว์การตรวจสอบและลายเซ็นระยะยาวเมื่อมีให้ใช้งาน
`messenger.*`	`array`	ทรานสปอร์ต `async`, ไทม์เอาต์ 120, จำนวนรีทราย 3	ใช้โดยเวิร์กโฟลว์การสร้างแบบอะซิงโครนัส
`artisan.*`	`array`	ตัวเรนเดอร์ Chrome จะถูกปิดใช้งานเว้นแต่มีการกำหนดค่าและติดตั้งไว้	แมปไปยัง `ChromeRendererConfig` เมื่อมีตัวเรนเดอร์เสริมให้ใช้งาน
`defaults.*`	`array`	ผู้สร้าง `NextPDF`, ผู้เขียนว่าง, ภาษา `en`, ระยะขอบและฟอนต์ค่าเริ่มต้น	นำไปใช้โดย `PdfFactory::create()`

การตอบสนอง HTTP

ใช้ตารางนี้เพื่อเลือกตัวช่วยตอบสนองตามโหมดการแสดงผลและการบัฟเฟอร์ ได้แก่การแสดงผลแบบ inline หรือการดาวน์โหลด และแบบบัฟเฟอร์หรือแบบสตรีม ตารางนี้ยังแสดงพฤติกรรมของชื่อไฟล์และเฮดเดอร์ด้วย

สัญลักษณ์	พารามิเตอร์	พฤติกรรมค่าเริ่มต้น	ส่งคืน	โยนข้อยกเว้นหรือล้มเหลวจาก	หมายเหตุ
`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`: class-string ที่อิมพลิเมนต์ `PdfBuilderInterface`; `outputPath`: เป้าหมาย `.pdf`; `builderContext`: ข้อมูลที่ซีเรียลไลซ์ได้	อาร์เรย์คอนเท็กซ์ว่าง	DTO ของข้อความ	`InvalidArgumentException` สำหรับ fully qualified class name (FQCN) ที่ไม่ถูกต้อง สตรีมแรปเปอร์, null byte, การทราเวอร์ซัล, พาทว่าง หรือเป้าหมายที่ไม่ใช่ `.pdf`	ทรานสปอร์ตของ Messenger บรรจุข้อมูล ไม่ใช่โคลเชอร์
`PdfBuilderInterface::build(Document $document, array $context): Document`	`document`: เอกสารใหม่ที่กำหนดค่าแล้ว; `context`: ข้อมูลข้อความที่ซีเรียลไลซ์ได้	ไม่มีคอนเท็กซ์ค่าเริ่มต้นนอกเหนือจากค่าของข้อความ	เอกสาร `Document` ที่กำหนดค่าแล้ว	ข้อยกเว้นเฉพาะของบิลเดอร์	ทำให้บิลเดอร์ทำงานแบบกำหนดได้แน่นอน (deterministic) และอีเดมโพเทนต์ (idempotent)
`new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)`	แฟกทอรี PDF และเซอร์วิสโลเคเตอร์ของบิลเดอร์ที่ติดแท็ก	ไม่สร้างเอกสารระหว่างการก่อสร้าง (construction)	`GeneratePdfHandler`	ข้อผิดพลาดในการเชื่อมต่อคอนเทนเนอร์	โลเคเตอร์ควรเปิดให้ใช้เฉพาะการอิมพลิเมนต์ `PdfBuilderInterface` เท่านั้น
`GeneratePdfHandler::__invoke(GeneratePdfMessage $message)`	`message`: DTO ของข้อความที่ตรวจสอบแล้ว	รีโซลฟ์บิลเดอร์จากคอนเทนเนอร์ สร้างเอกสาร และบันทึก	`void`	บริการบิลเดอร์ที่ขาดหายไป ผลลัพธ์ของบิลเดอร์ที่ไม่ถูกต้อง ข้อผิดพลาดในการเขียนของคอร์	ควรใช้เซอร์วิสบิลเดอร์มากกว่าสแตติกคอลแบ็ก

หมายเหตุการพัฒนา

อย่าจัดเก็บ Document เป็นบริการ ให้จัดเก็บ PdfFactory และเรียก create() สำหรับงานแต่ละหน่วย
เข้าคิวเฉพาะคอนเท็กซ์ที่ซีเรียลไลซ์ได้ อย่าใส่สตรีมที่เปิดอยู่ โคลเชอร์ หรือออบเจกต์คำขอลงใน builderContext
ใช้นโยบายพาทเอาต์พุตที่เข้มงวดกว่า DTO เมื่อการดีพลอยมีรากการจัดเก็บเฉพาะเทแนนต์ (tenant-specific storage roots)