配置 NextPDF Symfony 包

快速概览

该包的所有行为都通过 config/packages/nextpdf.yaml 中的 nextpdf 根键配置。每个键都有默认值，因此配置是可选的。本页内容与 Configuration.php 完全一致。

配置树

结构说明由 NextPDF\Symfony\DependencyInjection\Configuration 定义。无效值会在容器构建期间触发 Symfony 的 InvalidConfigurationException，导致构建失败。

顶层键

键	类型	默认值	验证
page_format	enum	A4	以下值之一：A4、A3、A5、Letter、Legal、Tabloid
orientation	enum	P	以下值之一：P、L
unit	enum	mm	以下值之一：pt、mm、cm、in
pdfa	标量	null	以下值之一：null、4、4e、4f
fonts_path	标量	%kernel.project_dir%/resources/fonts	—
cache_path	标量	%kernel.cache_dir%/nextpdf	—
image_cache_mb	整数	50	最小值 0
font_cache_locking	boolean	true	—
preload_fonts	字符串列表	[]	—

icc_profile

键	类型	默认值
icc_profile.rgb	标量	null
icc_profile.cmyk	标量	null

defaults

应用于 PdfFactory 生成的每一份文档。

键	类型	默认值
defaults.creator	标量	NextPDF
defaults.author	标量	（空）
defaults.language	标量	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	标量	dejavusans
defaults.font_size	float	12.0
defaults.trim_box	变量	null
defaults.bleed_box	变量	null

PdfFactory 会读取此区段中的 creator、author 与 language，并应用于每一份新建文档。其余键会保存为容器参数，供引擎使用。

artisan

仅在检测到已安装 nextpdf/artisan 时生效。

键	类型	默认值
artisan.chrome_binary	标量	null
artisan.render_timeout	整数	30
artisan.default_css	标量	（空）
artisan.no_sandbox	boolean	false
artisan.max_html_size	整数	5000000

signature

仅在已安装 nextpdf/premium 时生效。同时安装此包和 Pro 版本时，支持的签章配置为 baseline B-B 配置文件。level 节点接受下列字符串值，以便与更广泛的 NextPDF 配置家族保持结构说明兼容。此包实际提供的签章能力是 B-B。B-B 以外的配置文件在 NextPDF Premium 文档中另行说明，本页不声明提供。

键	类型	默认值	验证
signature.enabled	boolean	false	—
signature.certificate	标量	null	—
signature.private_key	标量	null	—
signature.password	标量	（空）	—
signature.extra_certs	字符串列表	[]	—
signature.level	enum	B-B	接受值：B-B、B-T、B-LT、B-LTA（实际提供 B-B；B-T/B-LT/B-LTA 是为结构说明兼容保留的值，并非实际提供的 Pro 能力）

只有当 signature.enabled 为 true 且 signature.certificate 已配置时，编译器阶段才会注册签署器服务；否则此区段不会产生作用。

tsa

Time Stamp Authority（时间戳机构）客户端配置；已配置时供 Pro 签章使用。

键	类型	默认值
tsa.url	标量	null
tsa.username	标量	（空）
tsa.password	标量	（空）
tsa.cert	标量	null
tsa.key	标量	null
tsa.timeout	整数	30
tsa.allow_insecure_http	boolean	false
tsa.pinned_public_keys	字符串列表	[]
tsa.warn_on_key_rotation	boolean	true

只有在已配置 tsa.url 时，才会注册 TSA 客户端服务。

ocsp_cache

键	类型	默认值
ocsp_cache.enabled	boolean	true
ocsp_cache.ttl	整数	86400
ocsp_cache.directory	标量	null

messenger

异步生成的调节选项，在已安装 symfony/messenger 时生效。

键	类型	默认值
messenger.transport	标量	async
messenger.timeout	整数	120
messenger.retries	整数	3

参考配置

以下配置文件展示每个区段及其默认值：

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

容器服务与别名

此包从 config/services.php 加载其服务定义。下表完全反映该文件的内容。

服务 ID	共享	公开	备注
NextPDF\Typography\FontRegistry	是	—	由 nextpdf.fonts_path 构建；可选 PSR-3 记录器
NextPDF\Contracts\FontRegistryInterface	（别名）	是	别名为 FontRegistry
NextPDF\Graphics\ImageRegistry	是	—	有界 LRU；标记为 kernel.reset（reset）
NextPDF\Core\DocumentFactory	是	—	共享两个注册表
NextPDF\Contracts\DocumentFactoryInterface	（别名）	是	别名为 DocumentFactory
NextPDF\Symfony\Service\PdfFactory	是	是	读取 defaults、pdfa、artisan 参数
NextPDF\Contracts\PdfDocumentInterface	否	是	工厂 [PdfFactory, create]
NextPDF\Core\Document	（别名）	—	别名为 PdfDocumentInterface
nextpdf.document	（别名）	是	别名为 PdfDocumentInterface
NextPDF\Symfony\Http\PdfResponse	—	是	无状态辅助组件

此包还会注册 EInvoice 合约绑定（EmbedderInterface、ValidatorInterface、ProfileInterface、SchematronRunnerInterface），但只有在对应的 Premium 实现类存在时才会注册。每个绑定都注册为非共享，因此调用方每次都会取得全新的实例。每次调用的解析器状态绝不会泄漏到其他请求。

共享与非共享

nextpdf.document（及其别名）为非共享：每次容器 resolve（解析）都会返回不同的文档。在 PSR-11 下，容器允许使用相同标识符在连续的 get() 调用中返回不同的值——PSR-11 §1.1.2。字体注册表为共享服务，并会在预热后锁定。因此，结构性字体数据在每个进程中只解析一次，且无法在请求进行中被更改。

其中的 FontRegistry 与 ImageRegistry 服务接受一个可选的 Psr\Log\LoggerInterface，并通过 nullOnInvalid() 绑定。记录器是可替换、可选的协作组件，符合 PSR-3 记录器合约（PSR-3）。

自动绑定

PdfFactory、PdfResponse、文档工厂接口与字体注册表接口均为公开服务。它们可从容器取得，也可在自动绑定的控制器与服务中以类型提示注入。建议将 NextPDF\Symfony\Service\PdfFactory 作为构造函数注入的入口点。

边界情况与陷阱

• 未安装 Pro 却配置了 pdfa——该值会被保存但会被忽略。PdfFactory 只有在编译时检测到 Pro 扩展功能时，才会应用 PDF/A。
• image_cache_mb: 0——有效；会禁用图像 LRU 缓存。负值会在构建时被拒绝。
• 配置了 signature.enabled: true 却没有 signature.certificate——不会注册签署器服务；此配置按设计会静默地不产生作用。
• %kernel.*% placeholder（占位符）——fonts_path 与 cache_path 的默认值使用 Symfony 容器参数；只有需要字面路径时，才应以绝对路径覆盖。

符合性

每一行都是本页提出的一项规范性主张，并固定到受管 SDO 语料库中的完整 64 字节十六进制 reference_id。provenance（来源信息）（语料库信息清单、检索传输）位于 _sidecars/rag-citations.yaml。

规范	条款	参考 ID	主张
PSR-11	psr_11_container#1.1.2.p3.b		get() 每次解析可能返回不同的值
PSR-3	psr_3_logger#x3.p17		可选的 LoggerInterface 协作组件

商业情境

signature 与 tsa 区段仅在已安装 nextpdf/premium（Pro）时生效。这是一项可选的 Pro 能力；本页说明的 Core 包无需更改代码即可采用它。请参阅 </get-license/?intent=symfony-pro>。

另请参阅

• /integrations/symfony/install/ — 安装并注册此套件。
• /integrations/symfony/overview/ — 能力摘要。
• /integrations/symfony/production-usage/ — worker 安全性与异步模式。
• /integrations/symfony/boot-and-discovery/ — 配置如何在启动期间解析。