跳轉到

Bundle 設定

NextPdfBundle 透過標準的 Symfony DependencyInjection Extension 處理設定，支援 YAML、XML 與 PHP 三種格式。設定解析在容器 compile 階段完成，無執行時成本。

PHP Compatibility

This example uses PHP 8.5 syntax. If your environment runs PHP 8.1 or 7.4, use NextPDF Backport for a backward-compatible build.

最小設定

只需在 config/packages/nextpdf.yaml 中建立空設定即可啟用 Bundle 預設值：

# config/packages/nextpdf.yaml
nextpdf: ~

完整 YAML 設定

# config/packages/nextpdf.yaml
nextpdf:
    document:
        page_size:   'A4'
        orientation: 'portrait'
        margin_mm:   15.0
        author:      '%env(APP_NAME)%'
        creator:     'NextPDF'

    spectrum:
        enabled: '%env(bool:NEXTPDF_SPECTRUM_ENABLED)%'
        binary:  '%env(NEXTPDF_SPECTRUM_BINARY)%'

    messenger:
        enabled:   true
        transport: 'async'   # 使用名為 'async' 的 Messenger 傳輸

    response:
        cache_max_age:            0
        x_content_type_nosniff:   true
        content_security_policy:  "default-src 'none'"

XML 設定

<!-- config/packages/nextpdf.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services">
    <nextpdf>
        <document
            page-size="A4"
            orientation="portrait"
            margin-mm="15.0"
            author="%env(APP_NAME)%"
        />
        <spectrum enabled="false" />
        <messenger enabled="true" transport="async" />
    </nextpdf>
</container>

PHP 設定（Symfony 5.3+）

<?php

declare(strict_types=1);

use Symfony\Config\NextpdfConfig;

return static function (NextpdfConfig $config): void {
    $config->document()
        ->pageSize('A4')
        ->orientiation('portrait')
        ->marginMm(15.0)
        ->author('%env(APP_NAME)%');

    $config->spectrum()
        ->enabled(false);

    $config->messenger()
        ->enabled(true)
        ->transport('async');
};

設定項目說明

document 區段

鍵 型別 預設值 說明
page_size string 'A4' ISO 216 頁面尺寸或 'Letter'、'Legal'
orientation 'portrait'\|'landscape' 'portrait' 頁面方向
margin_mm float 15.0 四邊統一邊距（mm）
author string\|null null PDF 作者中繼資料
creator string 'NextPDF' PDF Creator 中繼資料

spectrum 區段

鍵 型別 預設值 說明
enabled bool false 啟用 Rust FFI Spectrum 加速器
binary string\|null null Spectrum 二進位檔路徑；null 則自動偵測

messenger 區段

鍵 型別 預設值 說明
enabled bool true 是否注冊 Messenger Handler
transport string 'async' 使用的 Messenger 傳輸名稱

環境特定設定

利用 Symfony 的 config/packages/{env}/nextpdf.yaml 覆寫：

# config/packages/test/nextpdf.yaml
nextpdf:
    spectrum:
        enabled: false   # 測試環境不使用加速器
    messenger:
        enabled: false   # 測試環境使用同步 Bus

設定驗證

Bundle 使用 Symfony Configuration TreeBuilder 驗證所有設定值，無效設定會在容器編譯時拋出 InvalidConfigurationException：

# 驗證容器設定（dev 環境）
php bin/console debug:config nextpdf

# 傾印已解析的設定樹
php bin/console config:dump-reference nextpdf

參見