Tham khảo API Symfony

Tổng quan nhanh

Gói Symfony đăng ký bundle, cung cấp cây cấu hình, một factory có thể inject để tạo tài liệu mới, các response helper Hypertext Transfer Protocol (HTTP) và các kiểu Messenger để sinh tài liệu bất đồng bộ. Hầu hết mã ứng dụng chỉ cần dùng hai symbol: service PdfFactory để inject và dựng một Document, cùng helper PdfResponse để biến tài liệu đó thành phản hồi HTTP an toàn. Các symbol còn lại (bundle, extension, compiler pass, cây cấu hình, Messenger data transfer object (DTO) và handler) là lớp kết nối bạn cấu hình một lần hoặc để framework quản lý.

Bắt đầu tại đây: Inject NextPDF\Symfony\Service\PdfFactory, gọi create() để lấy một Document mới, rồi trả về bằng NextPDF\Symfony\Http\PdfResponse::download(). Ví dụ đầu tiên minh họa đúng luồng này.

Tác vụ thường gặp

Dùng ba đoạn mã chạy được này cho các tác vụ thường gặp nhất. Mỗi đoạn mã chỉ dùng các symbol đã được xác minh và ghi lại trong các bảng phía sau.

Trả về một bản tải xuống Portable Document Format (PDF) từ controller: inject factory, dựng tài liệu rồi chuyển tài liệu đó cho response helper:

<?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");
    }
}

Tác dụng: PdfFactory::create() trả về một Document mới đã được cấu hình sẵn. PdfResponse::download() gửi tài liệu đó kèm Content-Type: application/pdf, disposition dạng đính kèm và các header bảo mật cố định của bundle.

Phát luồng một PDF lớn để giữ mức tiêu thụ bộ nhớ đỉnh ở mức thấp: dùng helper phát luồng và trả về 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');
    }
}

Tác dụng: PdfResponse::streamDownload() phát PDF đã dựng theo từng đoạn và bỏ qua Content-Length; dùng streamInline() cho phiên bản hiển thị nội tuyến tương đương.

Điều phối một PDF để sinh bất đồng bộ: gửi GeneratePdfMessage đến một Messenger transport để việc kết xuất chạy trên worker:

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

Tác dụng: DTO mang một builder class-string và đường dẫn đầu ra đã được xác thực. Handler phân giải builder, dựng tài liệu rồi lưu tài liệu đó trên worker. Lớp builder triển khai PdfBuilderInterface và được đăng ký trong service locator (xem quickstart Symfony để biết cách kết nối locator và worker).

Factory

Dùng bảng này để nắm chính xác constructor và contract create() của service có thể inject để tạo tài liệu mới.

Symbol	Tham số	Hành vi mặc định	Giá trị trả về	Ném ngoại lệ hoặc thất bại với	Ghi chú
new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)	factory: factory lõi; defaults: creator, author, ngôn ngữ, lề; pdfa: profile PDF/A tùy chọn; artisanConfig: cấu hình bộ kết xuất Chrome tùy chọn.	Các giá trị mặc định chỉ được áp dụng khi đã cấu hình.	PdfFactory	Lỗi kết nối container.	Service có thể là singleton vì create() trả về một tài liệu mới.
PdfFactory::create()	không có.	Áp dụng creator và ngôn ngữ; chỉ áp dụng author khi không rỗng; chỉ áp dụng PDF/A và cấu hình Artisan khi có.	NextPDF\Core\Document	Lỗi cấu hình lõi.	Dùng một lần cho mỗi request, command hoặc message.
PdfFactory::setArtisanAvailable(bool $available)	available: cờ xác định tính khả dụng tại thời điểm biên dịch.	Bị tắt cho đến khi compiler pass bật cờ này.	void	không có ngoại lệ dự kiến.	Hook nội bộ do compiler pass của extension tùy chọn gọi.
PdfFactory::setProAvailable(bool $available)	available: cờ xác định tính khả dụng tại thời điểm biên dịch.	Bị tắt cho đến khi compiler pass bật cờ này.	void	không có ngoại lệ dự kiến.	Hook nội bộ cho tính khả dụng của Premium.

Bundle, extension và cấu hình

Dùng bảng đầu tiên cho lớp kết nối: đăng ký bundle, cây cấu hình nextpdf và phát hiện extension tùy chọn. Bảng thứ hai liệt kê các khóa cấu hình.

Symbol	Tham số	Hành vi mặc định	Giá trị trả về	Ném ngoại lệ hoặc thất bại với	Ghi chú
NextPdfBundle::build(ContainerBuilder $container)	Container builder của Symfony.	Gọi phương thức build của lớp cha và đăng ký OptionalExtensionPass.	void	Lỗi đăng ký compiler pass.	Bật phát hiện tính năng Artisan và Premium tùy chọn.
NextPdfBundle::getPath()	không có.	Trả về đường dẫn gốc của gói.	string	không có ngoại lệ dự kiến.	Được dùng bởi cơ chế khám phá bundle và tải tài nguyên của Symfony.
NextPdfExtension::load(array $configs, ContainerBuilder $container)	Các mảng cấu hình của người dùng và container builder.	Xử lý cấu hình nextpdf, lưu các tham số đã phân giải, tải định nghĩa service và kiểm tra các extension bắt buộc.	void	Lỗi xác thực cấu hình, tải service hoặc thiếu extension.	Các extension bắt buộc là mbstring và zlib.
NextPdfExtension::getAlias()	không có.	Dùng nextpdf làm khóa cấu hình gốc.	string	không có ngoại lệ dự kiến.	Cấu hình bundle dưới nextpdf:.
Configuration::getConfigTreeBuilder()	không có.	Định nghĩa cây cấu hình nextpdf đã được xác thực.	TreeBuilder	Lỗi định nghĩa cấu hình của Symfony.	Phản ánh cấu trúc cấu hình của Laravel ở những nơi khả thi.
OptionalExtensionPass::process(ContainerBuilder $container)	Container builder của Symfony.	Phát hiện các service Artisan và Premium tùy chọn rồi bật/tắt các cờ khả dụng của factory.	void	Lỗi kết nối compiler pass.	Chạy trong quá trình biên dịch container.

Khóa cấu hình	Kiểu	Hành vi mặc định	Ghi chú
page_format	enum	A4; các giá trị được phép gồm A3, A5, Letter, Legal và Tabloid.	Áp dụng cho tạo tài liệu mặc định.
orientation	enum	P; các giá trị được phép là P và L.	Dùng các lời gọi tài liệu tường minh khi một trang cần hướng khác.
unit	enum	mm; các giá trị được phép là pt, mm, cm và in.	Giữ cho các giá trị mặc định của framework đồng nhất với các đơn vị của lõi.
pdfa	`string	null`	null; các giá trị được phép là 4, 4e và 4f.
fonts_path / cache_path	string	Đường dẫn phông chữ của dự án và đường dẫn cache của kernel.	Giữ cho mỗi đường dẫn có thể đọc hoặc ghi theo vai trò lúc chạy của nó.
signature.*	array	Tắt theo mặc định với mức chữ ký B-B.	Cung cấp certificate, khóa, mật khẩu, các certificate bổ sung và mức.
tsa.*	array	Tắt khi Uniform Resource Locator (URL) là null; timeout mặc định là 30 giây.	Hỗ trợ thông tin đăng nhập, tệp mutual Transport Layer Security (mTLS), public-key pin và chính sách HTTP.
ocsp_cache.*	array	Bật với thời gian sống (TTL) là 86400 giây.	Được dùng bởi các luồng xác thực và chữ ký dài hạn khi có sẵn.
messenger.*	array	Transport async, timeout 120, retries 3.	Được dùng bởi các quy trình sinh tài liệu bất đồng bộ.
artisan.*	array	Bộ kết xuất Chrome bị tắt trừ khi được cấu hình và cài đặt.	Ánh xạ tới ChromeRendererConfig khi bộ kết xuất tùy chọn có sẵn.
defaults.*	array	Creator NextPDF, author rỗng, ngôn ngữ en, lề và phông chữ mặc định.	Được áp dụng bởi PdfFactory::create().

Phản hồi HTTP

Dùng bảng này để chọn response helper theo chế độ hiển thị và cách đệm: hiển thị nội tuyến hoặc tải xuống, đệm hoặc phát luồng. Bảng cũng mô tả hành vi của tên tệp và header.

Symbol	Tham số	Hành vi mặc định	Giá trị trả về	Ném ngoại lệ hoặc thất bại với	Ghi chú
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: tài liệu đã dựng; filename: tên tệp của phản hồi.	Thêm .pdf khi thiếu.	Symfony\Component\HttpFoundation\Response	Lỗi tuần tự hóa của lõi.	Đặt content type PDF và các header phòng vệ.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Giống inline; disposition là đính kèm.	Phản hồi tải xuống trên trình duyệt.	Response	Giống inline.	Dùng cho các bản tải xuống tường minh.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Giống inline.	Phát các byte PDF đã được dựng theo từng đoạn.	StreamedResponse	Giống inline.	Không tránh được việc dựng tài liệu.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Giống streamInline; disposition là đính kèm.	Phản hồi luồng tải xuống.	StreamedResponse	Giống streamInline.	Áp dụng chính sách kích thước đầu ra trước khi kết xuất.

Messenger

Dùng bảng này cho luồng bất đồng bộ: message DTO bạn điều phối, builder interface bạn triển khai và handler chạy trên worker.

Symbol	Tham số	Hành vi mặc định	Giá trị trả về	Ném ngoại lệ hoặc thất bại với	Ghi chú
new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])	builderClass: class-string triển khai PdfBuilderInterface; outputPath: .pdf đích; builderContext: dữ liệu có thể tuần tự hóa.	Mảng context rỗng.	Message DTO.	InvalidArgumentException khi fully qualified class name (FQCN), stream wrapper, null byte, traversal, đường dẫn rỗng không hợp lệ, hoặc đích không phải .pdf.	Các Messenger transport mang dữ liệu, không mang closure.
PdfBuilderInterface::build(Document $document, array $context): Document	document: tài liệu mới đã được cấu hình; context: dữ liệu message có thể tuần tự hóa.	Không có context mặc định nào ngoài giá trị của message.	Đối tượng Document đã được cấu hình.	Các ngoại lệ riêng của builder.	Hãy làm cho các builder mang tính tất định và idempotent.
new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)	PDF factory và service locator của builder đã được gắn thẻ.	Không có tài liệu nào được tạo trong quá trình khởi tạo.	GeneratePdfHandler	Lỗi kết nối container.	Locator chỉ nên cung cấp các bản triển khai PdfBuilderInterface.
GeneratePdfHandler::__invoke(GeneratePdfMessage $message)	message: message DTO đã được xác thực.	Phân giải builder từ container, dựng tài liệu rồi lưu nó.	void	Thiếu service builder, kết quả builder không hợp lệ, lỗi ghi của lõi.	Ưu tiên dùng các builder dạng service hơn là các callback tĩnh.

Ghi chú phát triển

• Không lưu một Document dưới dạng service. Hãy lưu PdfFactory và gọi create() cho từng đơn vị công việc.
• Chỉ đưa context có thể tuần tự hóa vào hàng đợi. Không đưa các luồng đang mở, closure hay đối tượng request vào builderContext.
• Dùng một chính sách đường dẫn đầu ra nghiêm ngặt hơn DTO khi việc triển khai có các thư mục lưu trữ gốc riêng theo tenant.