NextPDF Symfony バンドルの構成

概要

バンドルの動作はすべて、nextpdf ルートキー（config/packages/nextpdf.yaml 内）配下で構成します。すべてのキーに既定値があるため、必要な項目だけを明示的に設定します。このページの内容は Configuration.php を正確に反映しています。

構成ツリー

スキーマは NextPDF\Symfony\DependencyInjection\Configuration で定義されています。無効な値を指定すると、コンテナーのビルド時に Symfony の InvalidConfigurationException で失敗します。

トップレベルのキー

キー	型	既定値	検証
`page_format`	列挙型	`A4`	次のいずれか：`A4`、`A3`、`A5`、`Letter`、`Legal`、`Tabloid`
`orientation`	列挙型	`P`	次のいずれか：`P`、`L`
`unit`	列挙型	`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`	ブール値	`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`	浮動小数点数	`10.0`
`defaults.margin_right`	浮動小数点数	`10.0`
`defaults.margin_bottom`	浮動小数点数	`10.0`
`defaults.margin_left`	浮動小数点数	`10.0`
`defaults.font_family`	スカラー	`dejavusans`
`defaults.font_size`	浮動小数点数	`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`	ブール値	`false`
`artisan.max_html_size`	整数	`5000000`

`signature`

有効になるのは、nextpdf/premium がインストールされている場合のみです。バンドルと Pro ティアの両方が存在する場合、サポートされる署名構成は ベースライン B-B プロファイルです。level ノードは、より広い NextPDF 構成ファミリーとのスキーマ互換性を保つため、以下の文字列値を受け付けます。このバンドルが提供する署名機能は B-B です。B-B を超えるプロファイルについては NextPDF Premium のドキュメントで別途説明されており、このページでは提供を主張しません。

キー	型	既定値	検証
`signature.enabled`	ブール値	`false`	—
`signature.certificate`	スカラー	`null`	—
`signature.private_key`	スカラー	`null`	—
`signature.password`	スカラー	(空)	—
`signature.extra_certs`	文字列のリスト	`[]`	—
`signature.level`	列挙型	`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`

タイムスタンプ局（TSA）のクライアント構成です。設定されている場合は、Pro の署名で使用されます。

キー	型	既定値
`tsa.url`	スカラー	`null`
`tsa.username`	スカラー	(空)
`tsa.password`	スカラー	(空)
`tsa.cert`	スカラー	`null`
`tsa.key`	スカラー	`null`
`tsa.timeout`	整数	`30`
`tsa.allow_insecure_http`	ブール値	`false`
`tsa.pinned_public_keys`	文字列のリスト	`[]`
`tsa.warn_on_key_rotation`	ブール値	`true`

TSA クライアントサービスは、tsa.url が設定されている場合にのみ登録されます。

`ocsp_cache`

キー	型	既定値
`ocsp_cache.enabled`	ブール値	`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`	はい	—	2 つのレジストリを共有
`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）。フォントレジストリは共有され、ウォームアップ後にロックされます。そのため、構造的なフォントデータはプロセスごとに 1 回だけ解析され、リクエスト中に変更することはできません。

サービス 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.certificate なしで signature.enabled: true を設定した場合 — 署名者サービスは登録されません。構成は設計上、警告なしで無効になります。
%kernel.*% プレースホルダー — fonts_path と cache_path の既定値は Symfony のコンテナーパラメーターを使用します。リテラルパスが必要な場合にのみ絶対パスで上書きしてください。

準拠

各行は、このページに含まれる規範的な主張であり、ゲート付き SDO コーパス内の完全な 64 桁 16 進数の reference_id に固定されています。来歴（コーパスマニフェスト、取得トランスポート）は _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> を参照してください。

NextPDF Symfony バンドルの構成

概要

構成ツリー

トップレベルのキー

icc_profile

defaults

artisan

signature

tsa

ocsp_cache

messenger