Cấu hình bundle Symfony của NextPDF

Tổng quan nhanh

Định cấu hình toàn bộ hành vi của bundle dưới khóa gốc nextpdf trong config/packages/nextpdf.yaml. Mỗi khóa đều có giá trị mặc định, vì vậy bạn chỉ cần đặt những giá trị muốn thay đổi. Trang này phản ánh chính xác Configuration.php.

Cây cấu hình

NextPDF\Symfony\DependencyInjection\Configuration định nghĩa schema cấu hình. Các giá trị không hợp lệ sẽ làm quá trình build container thất bại với một InvalidConfigurationException của Symfony.

Các khóa cấp cao nhất

Khóa	Kiểu	Mặc định	Kiểm tra
`page_format`	enum	`A4`	một trong số `A4`, `A3`, `A5`, `Letter`, `Legal`, `Tabloid`
`orientation`	enum	`P`	một trong số `P`, `L`
`unit`	enum	`mm`	một trong số `pt`, `mm`, `cm`, `in`
`pdfa`	scalar	`null`	một trong số `null`, `4`, `4e`, `4f`
`fonts_path`	scalar	`%kernel.project_dir%/resources/fonts`	—
`cache_path`	scalar	`%kernel.cache_dir%/nextpdf`	—
`image_cache_mb`	số nguyên	`50`	tối thiểu `0`
`font_cache_locking`	boolean	`true`	—
`preload_fonts`	danh sách chuỗi	`[]`	—

`icc_profile`

Khóa	Kiểu	Mặc định
`icc_profile.rgb`	scalar	`null`
`icc_profile.cmyk`	scalar	`null`

`defaults`

Áp dụng cho mọi tài liệu do PdfFactory tạo ra.

Khóa	Kiểu	Mặc định
`defaults.creator`	scalar	`NextPDF`
`defaults.author`	scalar	(trống)
`defaults.language`	scalar	`en`
`defaults.margin_top`	float	`10.0`
`defaults.margin_right`	float	`10.0`
`defaults.margin_bottom`	float	`10.0`
`defaults.margin_left`	float	`10.0`
`defaults.font_family`	scalar	`dejavusans`
`defaults.font_size`	float	`12.0`
`defaults.trim_box`	variable	`null`
`defaults.bleed_box`	variable	`null`

PdfFactory đọc creator, author, và language từ phần này rồi áp dụng chúng cho mỗi tài liệu mới. Bundle lưu các khóa còn lại dưới dạng tham số container để engine sử dụng.

`artisan`

Chỉ áp dụng khi nextpdf/artisan được cài đặt và phát hiện.

Khóa	Kiểu	Mặc định
`artisan.chrome_binary`	scalar	`null`
`artisan.render_timeout`	số nguyên	`30`
`artisan.default_css`	scalar	(trống)
`artisan.no_sandbox`	boolean	`false`
`artisan.max_html_size`	số nguyên	`5000000`

`signature`

Chỉ áp dụng khi nextpdf/premium được cài đặt. Khi bundle và bậc Pro cùng hiện diện, cấu hình ký được hỗ trợ là hồ sơ baseline B-B. Khóa level chấp nhận các giá trị chuỗi bên dưới để schema tương thích với nhóm cấu hình NextPDF rộng hơn. Bundle này cung cấp khả năng ký B-B. Các hồ sơ vượt ngoài B-B được tài liệu hóa riêng trong NextPDF Premium và không được xác nhận ở đây.

Khóa	Kiểu	Mặc định	Kiểm tra
`signature.enabled`	boolean	`false`	—
`signature.certificate`	scalar	`null`	—
`signature.private_key`	scalar	`null`	—
`signature.password`	scalar	(trống)	—
`signature.extra_certs`	danh sách chuỗi	`[]`	—
`signature.level`	enum	`B-B`	tập giá trị được chấp nhận: `B-B`, `B-T`, `B-LT`, `B-LTA` (B-B được cung cấp; `B-T`/`B-LT`/`B-LTA` là các giá trị tương thích schema, không phải khả năng Pro được cung cấp)

Compiler pass chỉ đăng ký service ký khi signature.enabled là true và signature.certificate được đặt; nếu không, phần này không có tác dụng.

`tsa`

Cấu hình client của Time Stamp Authority (TSA), được tính năng ký Pro sử dụng khi đã cấu hình.

Khóa	Kiểu	Mặc định
`tsa.url`	scalar	`null`
`tsa.username`	scalar	(trống)
`tsa.password`	scalar	(trống)
`tsa.cert`	scalar	`null`
`tsa.key`	scalar	`null`
`tsa.timeout`	số nguyên	`30`
`tsa.allow_insecure_http`	boolean	`false`
`tsa.pinned_public_keys`	danh sách chuỗi	`[]`
`tsa.warn_on_key_rotation`	boolean	`true`

Bundle chỉ đăng ký service client TSA khi tsa.url đã được đặt.

`ocsp_cache`

Khóa	Kiểu	Mặc định
`ocsp_cache.enabled`	boolean	`true`
`ocsp_cache.ttl`	số nguyên	`86400`
`ocsp_cache.directory`	scalar	`null`

`messenger`

Các thiết lập cho quá trình tạo bất đồng bộ, được dùng khi symfony/messenger được cài đặt.

Khóa	Kiểu	Mặc định
`messenger.transport`	scalar	`async`
`messenger.timeout`	số nguyên	`120`
`messenger.retries`	số nguyên	`3`

Cấu hình tham chiếu

Một tệp cấu hình hiển thị mọi phần cùng giá trị mặc định tương ứng:

nextpdf:
    page_format: A4
    orientation: P
    unit: mm
    pdfa: ~
    fonts_path: '%kernel.project_dir%/resources/fonts'
    cache_path: '%kernel.cache_dir%/nextpdf'
    image_cache_mb: 50
    font_cache_locking: true
    preload_fonts: []
    icc_profile:
        rgb: ~
        cmyk: ~
    defaults:
        creator: NextPDF
        author: ''
        language: en
        margin_top: 10.0
        margin_right: 10.0
        margin_bottom: 10.0
        margin_left: 10.0
        font_family: dejavusans
        font_size: 12.0
        trim_box: ~
        bleed_box: ~
    artisan:
        chrome_binary: ~
        render_timeout: 30
        default_css: ''
        no_sandbox: false
        max_html_size: 5000000
    signature:
        enabled: false
        certificate: ~
        private_key: ~
        password: ''
        extra_certs: []
        level: B-B
    tsa:
        url: ~
        username: ''
        password: ''
        cert: ~
        key: ~
        timeout: 30
        allow_insecure_http: false
        pinned_public_keys: []
        warn_on_key_rotation: true
    ocsp_cache:
        enabled: true
        ttl: 86400
        directory: ~
    messenger:
        transport: async
        timeout: 120
        retries: 3

Service và alias của container

Bundle nạp các định nghĩa service từ config/services.php. Bảng bên dưới phản ánh chính xác tệp đó.

Service id	Shared	Public	Ghi chú
`NextPDF\Typography\FontRegistry`	có	—	được tạo từ `nextpdf.fonts_path`; logger PHP Standard Recommendation 3 (PSR-3) tùy chọn
`NextPDF\Contracts\FontRegistryInterface`	(alias)	có	alias của `FontRegistry`
`NextPDF\Graphics\ImageRegistry`	có	—	least-recently-used (LRU) có giới hạn; được gắn tag `kernel.reset` (`reset`)
`NextPDF\Core\DocumentFactory`	có	—	chia sẻ hai registry
`NextPDF\Contracts\DocumentFactoryInterface`	(alias)	có	alias của `DocumentFactory`
`NextPDF\Symfony\Service\PdfFactory`	có	có	đọc `defaults`, `pdfa`, và `artisan` dưới dạng tham số
`NextPDF\Contracts\PdfDocumentInterface`	không	có	factory `[PdfFactory, create]`
`NextPDF\Core\Document`	(alias)	—	alias của `PdfDocumentInterface`
`nextpdf.document`	(alias)	có	alias của `PdfDocumentInterface`
`NextPDF\Symfony\Http\PdfResponse`	—	có	helper không trạng thái

Bundle cũng đăng ký các binding contract EInvoice (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) chỉ khi các lớp triển khai Premium tương ứng tồn tại. Mỗi service đều non-shared, nên bên gọi nhận được một thực thể mới. Trạng thái parser của từng lần gọi không bao giờ rò rỉ giữa các request.

Shared so với non-shared

nextpdf.document (và các alias của nó) là non-shared: mỗi lần container resolve sẽ trả về một tài liệu riêng biệt. Theo PHP Standard Recommendation 11 (PSR-11), một container có thể trả về giá trị khác nhau qua các lần gọi get() liên tiếp với cùng một định danh; xem PSR-11 §1.1.2. Font registry được chia sẻ và bị khóa sau khi warmup. Dữ liệu cấu trúc của phông chữ được parse một lần cho mỗi tiến trình và không thể bị thay đổi giữa chừng request.

Các service FontRegistry và ImageRegistry chấp nhận một Psr\Log\LoggerInterface tùy chọn; Symfony bind nó bằng nullOnInvalid(). Logger vẫn là một cộng tác viên tùy chọn, có thể thay thế, nhất quán với contract logger PSR-3.

Autowiring

PdfFactory, PdfResponse, document factory interface và font registry interface đều là public. Bạn có thể lấy chúng từ container hoặc type-hint trong các controller và service autowired. Constructor injection của NextPDF\Symfony\Service\PdfFactory là điểm vào được khuyến nghị.

Trường hợp đặc biệt và những điều cần lưu ý

pdfa được đặt mà không có Pro — giá trị được lưu nhưng bị bỏ qua. PdfFactory chỉ áp dụng Portable Document Format/Archival (PDF/A) khi extension Pro được phát hiện tại thời điểm compile.
image_cache_mb: 0 — hợp lệ; tắt cache LRU ảnh. Các giá trị âm bị từ chối tại thời điểm build.
signature.enabled: true mà không có signature.certificate — service ký không được đăng ký; theo thiết kế, cấu hình không có tác dụng trong im lặng.
Placeholder %kernel.*% — các giá trị mặc định của fonts_path và cache_path dùng tham số container của Symfony; chỉ ghi đè bằng đường dẫn tuyệt đối khi cần đường dẫn nguyên văn.

Tuân thủ

Mỗi hàng là một khẳng định mang tính chuẩn mực trên trang này, được ghim vào một reference_id đầy đủ 64 ký tự hex từ kho ngữ liệu của tổ chức phát triển tiêu chuẩn (SDO) có kiểm soát truy cập. Nguồn gốc, bao gồm manifest kho ngữ liệu và transport truy xuất, nằm trong _sidecars/rag-citations.yaml.

Spec	Điều khoản	reference_id	Khẳng định
PSR-11	`psr_11_container#1.1.2.p3.b`		get() có thể trả về giá trị khác nhau qua mỗi lần resolve
PSR-3	`psr_3_logger#x3.p17`		Cộng tác viên LoggerInterface tùy chọn

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

Các phần signature và tsa chỉ áp dụng khi nextpdf/premium (Pro) được cài đặt. Khả năng Pro tùy chọn này không yêu cầu thay đổi mã nào trong bundle Core được ghi lại ở đây. Xem </get-license/?intent=symfony-pro>.

Xem thêm

/integrations/symfony/install/ — cài đặt và đăng ký bundle.
/integrations/symfony/overview/ — xem lại bản tóm tắt khả năng.
/integrations/symfony/production-usage/ — an toàn worker và các mẫu bất đồng bộ.
/integrations/symfony/boot-and-discovery/ — xem cách cấu hình được resolve trong quá trình boot.