Tích hợp NextPDF với Symfony

Tổng quan nhanh

Cài đặt nextpdf/symfony, cho Flex đăng ký bundle hoặc tự đăng ký thủ công, thêm config/packages/nextpdf.yaml, rồi tiêm PdfFactory. Trang này là chỉ mục liên kết; mỗi bước đều dẫn đến một hướng dẫn chi tiết hơn.

Cài đặt

composer require nextpdf/symfony

Bundle này yêu cầu nextpdf/core^3.0 || ^5.2, symfony/*^7.2, và psr/log^3.0. Các lớp được tự động nạp theo tiền tố PHP Standards Recommendation (PSR)-4 là NextPDF\Symfony\, ánh xạ tới src/Symfony/. Trình tự động nạp PSR-4 ánh xạ tiền tố namespace đó đến thư mục gốc (PSR-4 §2). Để xem đầy đủ yêu cầu và các gói tùy chọn, hãy xem /integrations/symfony/install/.

Khởi động và tự động phát hiện

Với Symfony Flex, mục extra.symfony.bundles trong tệp composer.json của bundle sẽ đăng ký NextPDF\Symfony\NextPdfBundle cho mọi môi trường. Nếu không dùng Flex, hãy thêm thủ công bundle này vào config/bundles.php:

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

Để biết toàn bộ trình tự khởi động và hành vi của compiler pass, hãy xem /integrations/symfony/boot-and-discovery/.

Ràng buộc trong container

Tệp config/services.php của bundle đăng ký các service sau:

Service / alias	Vòng đời
`NextPDF\Symfony\Service\PdfFactory`	dùng chung, công khai; hãy tiêm service này
`nextpdf.document` → `PdfDocumentInterface` → `Document`	không dùng chung, công khai; tạo mới ở mỗi lần phân giải
`NextPDF\Contracts\FontRegistryInterface`	dùng chung, bị khóa sau giai đoạn warmup khi khởi động
`NextPDF\Graphics\ImageRegistry`	dùng chung, `kernel.reset`
`NextPDF\Contracts\DocumentFactoryInterface`	dùng chung
`NextPDF\Symfony\Http\PdfResponse`	trình trợ giúp công khai, không lưu trạng thái

Ràng buộc document được cố ý đặt ở chế độ không dùng chung. PSR-11 cho phép một container trả về các giá trị khác nhau giữa những lần gọi get() liên tiếp cho cùng một định danh. Một document mới giúp tránh trộn lẫn trạng thái giữa các request trong các worker chạy lâu (PSR-11 §1.1.2). Để xem bảng đầy đủ về service và alias, bao gồm các ràng buộc EInvoice có điều kiện, hãy xem /integrations/symfony/configuration/.

Xuất cấu hình

Alias cấu hình là nextpdf. Tạo config/packages/nextpdf.yaml. Khi Flex áp dụng một recipe, Flex sẽ tự thêm cho bạn một bản sao mặc định. Mọi khóa đều có giá trị mặc định, nên một tệp tối giản sẽ như sau:

nextpdf: ~

Cây cấu hình đầy đủ được mô tả trong /integrations/symfony/configuration/.

Lần dùng đầu tiên

Tiêm PdfFactory, sau đó trả về tài liệu bằng 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');
    }
}

Để xem controller hoàn chỉnh từ đầu đến cuối cùng với luồng bất đồng bộ qua Messenger, hãy xem /integrations/symfony/quickstart/.

Kiểm tra nhanh bundle

Xác minh phần tích hợp mà không cần viết mã ứng dụng:

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

debug:container nextpdf sẽ liệt kê PdfFactory, alias nextpdf.document và các registry. lint:container kiểm tra rằng mọi đối số của service đều có thể phân giải. Để thử tạo tệp, hãy thêm controller ở trên, rồi gửi yêu cầu đến /hello.pdf.

Các điểm vào API công khai

Application programming interface (API) công khai hỗ trợ các ký hiệu sau cho mã ứng dụng:

Ký hiệu	Mục đích
`NextPDF\Symfony\Service\PdfFactory::create()`	đối tượng mới, đã được cấu hình sẵn, thuộc kiểu `Document`
`NextPDF\Symfony\Http\PdfResponse::inline()` / `download()`	phản hồi được đệm kèm header bảo mật
`NextPDF\Symfony\Http\PdfResponse::streamInline()` / `streamDownload()`	phản hồi truyền theo luồng dạng từng khối
`NextPDF\Symfony\Message\GeneratePdfMessage`	data transfer object (DTO) cho quy trình tạo bất đồng bộ (đã được kiểm tra hợp lệ)
`NextPDF\Symfony\Message\PdfBuilderInterface`	contract của builder được handler phân giải

Tuân thủ

Mỗi hàng liệt kê một tuyên bố mang tính chuẩn mực được nêu trên trang này. Mỗi tuyên bố được gắn với một reference_id đầy đủ gồm 64 ký tự hex từ kho tài liệu standards development organization (SDO) có kiểm soát truy cập. Thông tin nguồn gốc (manifest của kho tài liệu và phương thức truyền tải khi truy xuất) nằm trong _sidecars/rag-citations.yaml.

Đặc tả	Điều khoản	reference_id	Tuyên bố
PSR-11	`psr_11_container#1.1.2.p4`		Contract về định danh của has()/get() trên container
PSR-4	`psr_4_autoload#x1.x2.p5`		Ánh xạ namespace của trình tự động nạp

Xem thêm

/integrations/symfony/install/ — yêu cầu và đăng ký.
/integrations/symfony/boot-and-discovery/ — phát hiện, khởi động và compiler pass.
/integrations/symfony/configuration/ — schema đầy đủ và bảng service.
/integrations/symfony/quickstart/ — controller chạy được và ví dụ bất đồng bộ.
/integrations/symfony/production-usage/ — an toàn cho worker và truyền theo luồng.