Cài đặt bundle Symfony của NextPDF

Tổng quan nhanh

Cài đặt bundle bằng Composer. Nếu ứng dụng của bạn dùng Symfony Flex, bundle sẽ tự đăng ký. Nếu không dùng Flex, hãy đăng ký bundle một lần trong config/bundles.php.

Yêu cầu

Tệp composer.json của bundle định nghĩa các ràng buộc sau.

Phụ thuộc	Ràng buộc
`php`	`>=8.4 <9.0`
`nextpdf/core`	`^3.0 \|\| ^5.2`
`symfony/framework-bundle`	`^7.2`
`symfony/dependency-injection`	`^7.2`
`symfony/config`	`^7.2`
`symfony/http-foundation`	`^7.2`
`psr/log`	`^3.0`

Bundle cũng kiểm tra hai phần mở rộng PHP tại thời điểm dựng container: ext-mbstring và ext-zlib. Mọi runtime PHP được hỗ trợ đều bật cả hai phần mở rộng này. Nếu thiếu một trong hai, bộ kiểm tra sẽ dừng ngay và hiển thị thông báo rõ ràng.

Các gói tùy chọn

Tệp composer.json của bundle khai báo các gói sau trong suggest. Hãy thêm chúng khi bạn cần hành vi mà chúng cung cấp:

Gói	Bổ sung
`nextpdf/artisan`	Kết xuất HTML qua Chrome CDP, tự động phát hiện tại thời điểm biên dịch
`nextpdf/premium`	Lưu trữ PDF/A và ký số (cài đặt bậc Pro), tự động phát hiện tại thời điểm biên dịch
`symfony/messenger`	Tạo PDF bất đồng bộ thông qua handler Messenger

Cài đặt bằng Composer

composer require nextpdf/symfony

Bundle được tự động nạp dưới tiền tố PHP Standard Recommendation 4 (PSR-4) là NextPDF\Symfony\, ánh xạ tới src/Symfony/. Ánh xạ này được khai báo trong composer.jsonautoload.psr-4. Bộ tự động nạp do Composer sinh ra sẽ ánh xạ tiền tố namespace tới thư mục gốc đó, đúng như PSR-4 §2 định nghĩa.

Đăng ký bundle

Symfony Flex (khuyến nghị)

Bundle đi kèm một gợi ý tự động đăng ký bên trong composer.json:

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

Trong ứng dụng đã bật Flex, mục này thêm bundle vào config/bundles.php cho mọi môi trường (all). Bạn không cần chỉnh sửa tệp này thủ công. Để biết mô hình đăng ký, hãy xem tài liệu chính thức về bundle của Symfony (https://symfony.com/doc/current/bundles.html).

Đăng ký thủ công (không dùng Flex)

Nếu ứng dụng của bạn không dùng Symfony Flex, hãy tự thêm bundle vào config/bundles.php:

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

Lớp bundle là NextPDF\Symfony\NextPdfBundle. Lớp này kế thừa lớp cơ sở Symfony\Component\HttpKernel\Bundle\Bundle của Symfony. Phương thức getPath() của bundle trả về thư mục gốc của gói. Phương thức build() của nó đăng ký compiler pass OptionalExtensionPass.

Cung cấp tệp cấu hình

Bí danh cấu hình của bundle là nextpdf. Tạo config/packages/nextpdf.yaml. Khi được phát hành, một Flex recipe sẽ thêm sẵn một bản mặc định tại đây cho bạn. Một tệp tối giản dựa hoàn toàn vào các giá trị mặc định tích hợp sẵn sẽ trông như sau:

nextpdf: ~

Mọi khóa đều có giá trị mặc định, nên một cấu hình rỗng vẫn hợp lệ. Trang /integrations/symfony/configuration/ ghi lại đầy đủ cây cấu hình.

Xác minh việc cài đặt

Xác nhận rằng container có thể thấy các dịch vụ của bundle:

php bin/console debug:container nextpdf

Bạn sẽ thấy các dịch vụ bao gồm bí danh nextpdf.document và NextPDF\Symfony\Service\PdfFactory. Để kiểm tra cấu hình đã được phân giải, hãy chạy:

php bin/console debug:config nextpdf

Lệnh này in ra cây cấu hình đã hợp nhất: các giá trị ghi đè của bạn cùng với giá trị mặc định.

Trường hợp đặc biệt và các điểm cần lưu ý

Phạm vi ràng buộc của core — bundle chấp nhận nextpdf/core^3.0 || ^5.2. Composer sẽ phân giải phiên bản thỏa mãn phần còn lại trong đồ thị phụ thuộc của bạn. Hãy ghim một phiên bản major duy nhất trong composer.json của ứng dụng nếu bạn cần một phiên bản engine xác định.
Bộ kiểm tra phần mở rộng bị thiếu — nếu php bin/console dừng khi khởi động kèm một thông báo về ext-mbstring hoặc ext-zlib, hãy bật phần mở rộng được nêu tên trong php.ini. Hành vi dừng sớm này là có chủ ý, không phải lỗi của bundle.
Flex không đăng ký bundle — hãy xóa cache của Composer rồi cài đặt lại. Nếu bạn không dùng Flex, hãy thực hiện bước thủ công với config/bundles.php.

Tuân thủ

Mỗi hàng là một tuyên bố chuẩn tắc được nêu trên trang này, được ghim vào một reference_id 64 ký tự thập lục phân đầy đủ từ kho ngữ liệu SDO được kiểm soát. Nguồn gốc nằm trong _sidecars/rag-citations.yaml. Nguồn gốc này bao gồm manifest của kho ngữ liệu và transport truy xuất.

Đặc tả	Điều khoản	reference_id	Tuyên bố
PSR-4	`psr_4_autoload#x1.x2.p5`		Ánh xạ tiền tố namespace của bộ tự động nạp tới thư mục

Xem thêm

/integrations/symfony/overview/ — các chức năng bundle cung cấp.
/integrations/symfony/configuration/ — toàn bộ cây cấu hình và bảng dịch vụ.
/integrations/symfony/quickstart/ — controller chạy được đầu tiên.
/integrations/symfony/boot-and-discovery/ — chi tiết về quá trình phát hiện và trình tự khởi động.