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/ — 組態如何在開機期間解析。