Tổng quan tích hợp NextPDF Symfony

Tổng quan nhanh

nextpdf/symfony là bundle Symfony 7 chính thức cho engine NextPDF. Bundle này kết nối engine với container Symfony và cung cấp một document factory để bạn inject vào các service của mình. Nó cũng bao gồm các helper response Hypertext Transfer Protocol (HTTP) và một luồng tạo tệp Portable Document Format (PDF) không đồng bộ, để công việc có thể chạy trong nền.

Những gì bundle cung cấp

NextPDF Symfony gắn engine nextpdf/core vào ứng dụng Symfony dưới dạng một bundle chuẩn. Nó bổ sung các thành phần nền tảng sau; mỗi thành phần đều đã được kiểm chứng đối chiếu với mã nguồn bundle trong src/Symfony/:

• Một entry point của bundle — NextPDF\Symfony\NextPdfBundle mở rộng lớp cơ sở Bundle của Symfony và đăng ký một compiler pass.
• Một extension dependency-injection — NextPDF\Symfony\DependencyInjection\NextPdfExtension nạp các định nghĩa service, chuyển cây cấu hình thành các tham số container, và cung cấp alias cấu hình nextpdf.
• Một cây cấu hình có kiểu — NextPDF\Symfony\DependencyInjection\Configuration định nghĩa schema cấu hình nextpdf. Nó xác thực các giá trị enum, đặt giá trị mặc định, và dùng các placeholder tham số %kernel.*%.
• Một document factory có thể inject — NextPDF\Symfony\Service\PdfFactory tạo các instance NextPDF\Core\Document mới đã được cấu hình sẵn. Đây là phần tương đương trong Symfony với một static facade.
• Các helper response HTTP — NextPDF\Symfony\Http\PdfResponse tạo các response inline, tải xuống và truyền luồng với một bộ header bảo mật cố định tuân theo Open Worldwide Application Security Project (OWASP).
• Một luồng tạo không đồng bộ — NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler, và NextPDF\Symfony\Message\PdfBuilderInterface tích hợp với Symfony Messenger để việc kết xuất PDF có thể chạy trên một worker.
• Một bộ phát hiện extension tại thời điểm biên dịch — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass phát hiện các extension NextPDF tùy chọn và chỉ đăng ký service của chúng khi các extension đó hiện diện.

Hợp đồng container

Bundle đăng ký một tập nhỏ, ổn định gồm các service container công khai. Service document nextpdf.document (được đặt alias thành NextPDF\Contracts\PdfDocumentInterface và NextPDF\Core\Document) không được chia sẻ: mỗi lần phân giải đều trả về một document riêng, dùng một lần. Điều này khớp với hợp đồng container PHP Standard Recommendation 11 (PSR-11): hai lần gọi get() liên tiếp với cùng một định danh có thể trả về các giá trị khác nhau, tùy thuộc vào cấu hình của container — xem PSR-11 §1.1.2. Binding không chia sẻ này là có chủ đích. Một document tích lũy trạng thái theo từng lần kết xuất, vì vậy việc dùng một instance mới cho mỗi request giúp ngăn trạng thái rò rỉ giữa các request trong các worker chạy dài.

Registry phông chữ (NextPDF\Contracts\FontRegistryInterface) hoạt động theo cách ngược lại: nó là một singleton được chia sẻ. Registry hình ảnh mang tag kernel.reset, vì vậy cache có giới hạn của nó được xóa giữa các request dưới FrankenPHP và các worker Messenger. Trang cấu hình ghi đầy đủ bảng service và alias.

Ghi log tùy chọn

Các registry phông chữ và hình ảnh chấp nhận một logger PHP Standard Recommendation 3 (PSR-3) tùy chọn. Bundle chỉ binding Psr\Log\LoggerInterface khi ứng dụng cung cấp một logger (nullOnInvalid()). Vì vậy, ghi log là một thành phần cộng tác tùy chọn, không phải dependency bắt buộc. Điều này nhất quán với hợp đồng logger PSR-3, trong đó logger là thành phần cộng tác được inject và có thể hoán đổi (PSR-3).

Khả năng core so với tùy chọn

Bản thân bundle là phần mềm core Apache-2.0. Một số khả năng chỉ xuất hiện khi bạn cài đặt thêm gói tùy chọn bên cạnh bundle:

Khả năng	Yêu cầu	Phát hiện
Tạo PDF, PdfFactory, PdfResponse	chỉ core	luôn khả dụng
Tạo không đồng bộ	symfony/messenger	handler kích hoạt khi Messenger được cài đặt
Kết xuất HTML Chrome DevTools Protocol (CDP)	nextpdf/artisan	thăm dò class_exists tại thời điểm biên dịch
Lưu trữ PDF/A, chữ ký số	nextpdf/premium (cài đặt Pro)	thăm dò class_exists tại thời điểm biên dịch

Khi nextpdf/premium được cài đặt, bundle có thể áp dụng một cấu hình chữ ký PDF Advanced Electronic Signatures (PAdES) B-B cơ sở. Các profile chữ ký cao hơn nằm ngoài phạm vi của tài liệu bundle này. Để xem ma trận phiên bản, hãy tham khảo tài liệu NextPDF Premium.

Khi nào nên dùng bundle này

Hãy dùng nextpdf/symfony khi bạn tạo PDF bên trong ứng dụng HTTP Symfony 7 hoặc worker. Bundle cung cấp các service do container quản lý, các registry an toàn cho worker, và các response tải xuống an toàn, để bạn không phải tự đấu nối engine. Nếu bạn chỉ cần tạo PDF một lần trong script, chỉ riêng gói core nextpdf/core là đủ.

Tuân thủ

Mỗi hàng là một tuyên bố quy chuẩn được nêu trên trang này và được ghim vào một reference_id 64-hex đầy đủ từ kho ngữ liệu standards development organization (SDO) có kiểm soát. Nguồn gốc (manifest kho ngữ liệu, phương thức 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.p3.b		Hợp đồng giá trị trả về của get() container
PSR-3	psr_3_logger#x3.p17		Dependency tùy chọn LoggerInterface

Bối cảnh thương mại

Chữ ký số và lưu trữ PDF/A trở nên khả dụng khi nextpdf/premium (Pro) được cài đặt bên cạnh bundle. Khả năng Pro tùy chọn này không yêu cầu thay đổi mã trong bundle Core được mô tả ở đây. Xem </get-license/?intent=symfony-pro>.

Xem thêm

• /integrations/symfony/install/ — cài đặt và đăng ký bundle.
• /integrations/symfony/configuration/ — cây cấu hình nextpdf đầy đủ và bảng service.
• /integrations/symfony/quickstart/ — một controller chạy được và ví dụ async.
• /integrations/symfony/boot-and-discovery/ — cách Symfony phát hiện và khởi động bundle.
• /integrations/symfony/production-usage/ — an toàn worker, truyền luồng, và các mẫu async.