Khắc phục sự cố với bundle Symfony của NextPDF

Tổng quan nhanh

Hầu hết sự cố bắt nguồn từ một trong bốn mảng: phát hiện, kiểm tra cấu hình, nối dây container hoặc định tuyến Messenger. Mỗi phần đối chiếu một triệu chứng với hành vi tương ứng của bundle, rồi cung cấp một lệnh console để xác nhận cách khắc phục.

Bundle chưa được đăng ký

Triệu chứng: bạn không autowire được PdfFactory, hoặc debug:container nextpdf không trả về gì.

Nguyên nhân: bundle chưa được thêm vào config/bundles.php. Có thể Flex chưa chạy, hoặc ứng dụng không dùng Flex.

Cách khắc phục:

php bin/console debug:container nextpdf

Nếu lệnh không trả về service nào, hãy thêm bundle theo cách thủ công:

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

Tệp composer.json của bundle chứa gợi ý đăng ký tự động trong extra.symfony.bundles. Gợi ý này chỉ áp dụng cho các ứng dụng đã bật Flex.

Khởi động thất bại vì thiếu extension PHP

Triệu chứng: kernel ném ra một RuntimeException nhắc đến ext-mbstring hoặc ext-zlib khi khởi động.

Nguyên nhân: nguyên nhân nằm ở NextPdfExtension::guardRequiredExtensions(), cơ chế bảo vệ fail-fast có chủ đích của bundle. Đây không phải là lỗi.

Cách khắc phục: bật extension được nêu trong php.ini, rồi khởi động lại runtime. Xác nhận bằng:

php -m | grep -E 'mbstring|zlib'

Cấu hình bị từ chối trong lúc build

Triệu chứng: Symfony ném ra một Symfony\Component\Config\Definition\Exception\InvalidConfigurationException khi chạy cache:clear hoặc cache:warmup.

Nguyên nhân: một giá trị không khớp với schema. Configuration.php định nghĩa các ràng buộc sau:

• page_format phải là một trong các giá trị A4, A3, A5, Letter, Legal, Tabloid.
• orientation phải là P hoặc L.
• unit phải là một trong các giá trị pt, mm, cm, in.
• pdfa phải là null, 4, 4e, hoặc 4f.
• image_cache_mb phải >= 0.

Cách khắc phục: in ra cấu hình đã hợp nhất, rồi sửa khóa bị lỗi:

php bin/console debug:config nextpdf

PDF/A hoặc chữ ký không có tác dụng

Triệu chứng: bạn đã đặt pdfa hoặc phần signature, nhưng kết quả vẫn là một tệp Portable Document Format (PDF) thông thường.

Nguyên nhân: các tính năng này yêu cầu nextpdf/premium. Lúc biên dịch, PdfFactory chỉ áp dụng PDF/A khi phát hiện extension Pro. Compiler pass chỉ đăng ký signer khi signature.enabled là true và signature.certificate đã được đặt.

Cách khắc phục: xác nhận rằng Premium đã được cài đặt và service signer tồn tại:

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

Nếu không có Premium, bundle vẫn lưu cấu hình nhưng chủ đích không kích hoạt cấu hình đó. Theo tài liệu của bundle khi dùng Pro, khả năng ký là profile cơ sở B-B. Tài liệu NextPDF Premium đề cập đến các profile ngoài B-B.

Kết xuất bằng Chrome không có hiệu lực

Triệu chứng: cấu hình artisan bị bỏ qua.

Nguyên nhân: kết xuất qua Chrome DevTools Protocol (CDP) yêu cầu nextpdf/artisan. Compiler pass dò tìm extension này bằng class_exists lúc biên dịch. Nếu không có extension, bộ kết xuất sẽ không được nối dây.

Cách khắc phục:

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

Quá trình dò tìm chạy trong giai đoạn biên dịch container. Sau khi cài đặt extension, hãy chạy lại cache:clear.

Handler của Messenger không bao giờ được gọi

Triệu chứng: bạn dispatch GeneratePdfMessage, nhưng không có PDF nào được ghi.

Nguyên nhân và cách khắc phục:

• Message chưa được định tuyến — thêm một mục định tuyến để ánh xạ NextPDF\Symfony\Message\GeneratePdfMessage tới một transport trong config/packages/messenger.yaml, rồi chạy một worker (php bin/console messenger:consume <transport>).
• Builder không nằm trong locator — handler lấy builder từ một locator PHP Standards Recommendation 11 (PSR-11) bằng id dạng class-string của builder. Định danh container là chuỗi nhận diện duy nhất một entry (PSR-11 §1.1.2). Nếu locator chưa đăng ký lớp builder, handler sẽ ném ra một RuntimeException cho biết builder được cấu hình phải implement PdfBuilderInterface. Hãy đăng ký builder, rồi tham chiếu nó từ locator.

Kiểm tra định tuyến và locator:

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

Message bị từ chối khi dispatch bằng InvalidArgumentException

Triệu chứng: thao tác khởi tạo GeneratePdfMessage ném ra một InvalidArgumentException.

Nguyên nhân: data transfer object (DTO) của message kiểm tra các đầu vào của chính nó. Các quy tắc từ chối đã được xác minh là:

• đường dẫn đầu ra rỗng, hoặc đường dẫn chứa null byte;
• một scheme stream-wrapper (ví dụ php://...);
• một đoạn path-traversal .. (dấu phân tách POSIX hoặc Windows);
• một đường dẫn đầu ra không kết thúc bằng .pdf (không phân biệt chữ hoa chữ thường);
• một builderClass không phải là tên lớp hợp lệ về mặt cú pháp.

Cách khắc phục: truyền vào một đường dẫn hệ thống tệp tuyệt đối kết thúc bằng .pdf và một tên lớp builder đầy đủ, có thật.

Tài liệu mang dữ liệu cũ

Triệu chứng: một PDF được tạo ra chứa nội dung từ một yêu cầu trước đó.

Nguyên nhân: một worker chạy lâu giữ lại một instance Document qua nhiều yêu cầu. Service document được đặt là non-shared để ngăn đúng tình huống này.

Cách khắc phục: gọi PdfFactory::create() bên trong một phương thức có phạm vi theo từng yêu cầu. Không bao giờ lưu tài liệu được trả về trên một service dùng chung.

Tham khảo lệnh chẩn đoán

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

Tuân thủ

Mỗi hàng là một tuyên bố quy chuẩn được đưa ra trên trang này và được gắn với một reference_id 64-hex đầy đủ từ kho ngữ liệu standards development organization (SDO) được kiểm soát truy cập. Nguồn gốc, bao gồm manifest của kho ngữ liệu và transport 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		Hợp đồng định danh has()/get() của container

Xem thêm

• /integrations/symfony/install/ — cài đặt và đăng ký.
• /integrations/symfony/configuration/ — toàn bộ schema và ràng buộc.
• /integrations/symfony/boot-and-discovery/ — phát hiện và trình tự khởi động.
• /integrations/symfony/security-and-operations/ — header bảo mật và kiểm tra đường dẫn.