Khởi động và khám phá NextPDF trong Symfony

Tổng quan nhanh

Kernel đăng ký NextPdfBundle. Extension Dependency Injection (DI) của bundle nạp services.php và phân giải cây cấu hình thành các tham số trong container. Sau đó, một compiler pass kết nối các tiện ích mở rộng tùy chọn và bước làm nóng phông chữ.

Cách Symfony Flex nhận diện bundle

Tệp composer.json của bundle khai báo một gợi ý tự động đăng ký:

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

Trong ứng dụng Symfony Flex, gợi ý này thêm NextPDF\Symfony\NextPdfBundle vào config/bundles.php cho mọi môi trường (all). Nếu không dùng Flex, hãy thêm bundle thủ công trong config/bundles.php. Symfony mô tả mô hình đăng ký bundle tại (https://symfony.com/doc/current/bundles.html). Các lớp của bundle được autoload theo tiền tố PHP Standard Recommendation (PSR)-4 là NextPDF\Symfony\, ánh xạ tới src/Symfony/. Autoloader PSR-4 ánh xạ tiền tố namespace tới thư mục gốc đó (PSR-4 §2).

Trình tự khởi động

Trình tự khởi động, đối chiếu với mã nguồn của bundle:

Kernel đăng ký các bundle. Kernel::registerBundles() đọc config/bundles.php và khởi tạo NextPDF\Symfony\NextPdfBundle, lớp này kế thừa Symfony\Component\HttpKernel\Bundle\Bundle.
Bundle build. NextPdfBundle::build() gọi phương thức của lớp cha rồi đăng ký compiler pass: OptionalExtensionPass. NextPdfBundle::getPath() trả về thư mục gốc của gói.
Nạp extension. Extension DI NextPDF\Symfony\DependencyInjection\NextPdfExtension (bí danh nextpdf) chạy processConfiguration() dựa trên Configuration. Extension này lưu các giá trị đã phân giải dưới dạng tham số container nextpdf.*, rồi nạp config/services.php qua PhpFileLoader.
Kiểm tra extension bắt buộc. NextPdfExtension::load() kết thúc bằng việc xác nhận rằng ext-mbstring và ext-zlib đã có mặt, và dừng ngay nếu thiếu một trong hai.
Compiler pass chạy. Trong quá trình biên dịch container, OptionalExtensionPass::process() cấu hình các cờ thể hiện tính khả dụng của tiện ích mở rộng trên PdfFactory, đăng ký có điều kiện trình ký và client của cơ quan đóng dấu thời gian (TSA), đồng thời lên lịch làm nóng và khóa font registry.
Container được biên dịch và lưu vào bộ nhớ đệm. Symfony ghi container đã biên dịch. cache:warmup thực hiện bước này trước khi lưu lượng truy cập đến ứng dụng.

Các compiler pass

Bundle đăng ký đúng một pass, NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass, trong NextPdfBundle::build(). Pass này chạy trong nhóm pass mặc định (trước khi tối ưu hóa) và thực hiện bốn bước. Mỗi bước đều có lớp kiểm tra, nên sẽ không làm gì khi thiếu đầu vào:

Cờ tiện ích mở rộng — thêm các lệnh gọi phương thức setArtisanAvailable(...) và setProAvailable(...) vào định nghĩa PdfFactory. Các giá trị này đến từ các lần kiểm tra class_exists ở thời điểm biên dịch đối với factory trình duyệt Artisan và lớp PDF/A của Pro.
Đăng ký trình ký — đăng ký factory thông tin chứng chỉ và dịch vụ trình ký cho profile baseline B-B khi nextpdf.signature có mặt, enabled là true, và chứng chỉ đã được thiết lập.
Client TSA — đăng ký dịch vụ client TSA khi nextpdf.tsa có một Uniform Resource Locator (URL).
Làm nóng phông chữ — thêm các lệnh gọi phương thức warmup() và lock() vào định nghĩa font registry khi nextpdf.preload_fonts không rỗng.

Liên kết container

config/services.php định nghĩa các dịch vụ. Dịch vụ document nextpdf.document (có bí danh là NextPDF\Contracts\PdfDocumentInterface và NextPDF\Core\Document) là không dùng chung: mỗi lần phân giải đều trả về một tài liệu mới. PSR-11 cho phép rõ ràng hành vi này; các lệnh gọi get() liên tiếp cho cùng một id có thể trả về những giá trị khác nhau (PSR-11 §1.1.2). Font registry được dùng chung và bị khóa sau khi làm nóng. Image registry được dùng chung và được gắn thẻ kernel.reset. Bảng đầy đủ nằm ở /integrations/symfony/configuration/.

Thứ tự phân giải cấu hình

Giá trị mặc định tích hợp sẵn từ Configuration (getConfigTreeBuilder()).
Các ghi đè ở cấp ứng dụng trong config/packages/nextpdf.yaml, cùng với các ghi đè theo môi trường bên dưới config/packages/<env>/.
Symfony phân giải các placeholder tham số %kernel.*%. Ví dụ, fonts_path mặc định là %kernel.project_dir%/resources/fonts.
NextPdfExtension::load() ghi kết quả đã hợp nhất vào các tham số container nextpdf.* mà services.php và compiler pass sử dụng.

Các giá trị không hợp lệ sẽ thất bại ở bước 1–2 với một InvalidConfigurationException của Symfony.

Chẩn đoán

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

Lệnh đầu tiên liệt kê các dịch vụ đã đăng ký. Lệnh thứ hai in cấu hình đã hợp nhất. Lệnh thứ ba xây dựng lại container và chạy lại các lần kiểm tra extension ở thời điểm biên dịch.

Tuân thủ

Mỗi hàng là một tuyên bố quy chuẩn trên trang này, được ghim vào một reference_id 64 ký tự hex đầy đủ từ kho ngữ liệu có kiểm soát của tổ chức phát triển tiêu chuẩn (SDO). Nguồn gốc (manifest kho ngữ liệu, phương thức truyền tải truy xuất) được ghi 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`		Việc phân giải container có thể khác nhau theo từng lần gọi
PSR-4	`psr_4_autoload#x1.x2.p5`		Ánh xạ tiền tố namespace tới thư mục gốc

Xem thêm

/integrations/symfony/integration/ — tài liệu tham khảo về cách kết nối từ đầu đến cuối.
/integrations/symfony/install/ — cài đặt và đăng ký.
/integrations/symfony/configuration/ — cây cấu hình đầy đủ và bảng dịch vụ.
/integrations/symfony/overview/ — tóm tắt các tính năng.