NextPDF Symfony 統合の概要

概要

nextpdf/symfony は、NextPDF エンジン向けの公式 Symfony 7 バンドルです。このバンドルはエンジンを Symfony コンテナーに接続し、独自サービスへ注入できるドキュメントファクトリーを提供します。さらに HTTP レスポンスヘルパーと、PDF を非同期に生成する経路も同梱しているため、処理をバックグラウンドで実行できます。

バンドルが提供するもの

NextPDF Symfony は、nextpdf/core エンジンを標準的なバンドルとして Symfony アプリケーションに結び付けます。以下の構成要素を追加します。いずれも src/Symfony/ 内のバンドルソースに照らして検証済みです。

バンドルのエントリーポイント — NextPDF\Symfony\NextPdfBundle は Symfony の Bundle 基底クラスを拡張し、1 つのコンパイラーパスを登録します。
依存性注入の拡張 — NextPDF\Symfony\DependencyInjection\NextPdfExtension はサービス定義を読み込み、設定ツリーをコンテナーパラメーターに変換し、設定エイリアス nextpdf を公開します。
型付き設定ツリー — NextPDF\Symfony\DependencyInjection\Configuration は nextpdf 設定スキーマを定義します。このスキーマは列挙値を検証し、デフォルトを設定し、%kernel.*% パラメータープレースホルダーを使用します。
注入可能なドキュメントファクトリー — NextPDF\Symfony\Service\PdfFactory は、構成済みの新しい NextPDF\Core\Document インスタンスを生成します。これは静的ファサードに相当する Symfony 版です。
HTTP レスポンスヘルパー — NextPDF\Symfony\Http\PdfResponse は、OWASP に準拠した固定のセキュリティヘッダーセットを付与して、インライン、ダウンロード、ストリーミングのレスポンスを構築します。
非同期生成の経路 — NextPDF\Symfony\Message\GeneratePdfMessage、NextPDF\Symfony\Message\GeneratePdfHandler、および NextPDF\Symfony\Message\PdfBuilderInterface は Symfony Messenger と連携し、PDF レンダリングをワーカー上で実行できるようにします。
コンパイル時の拡張機能検出 — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass はオプションの NextPDF 拡張機能を検出し、その拡張機能が存在する場合にのみサービスを登録します。

コンテナーのコントラクト

このバンドルは、少数で安定したパブリックコンテナーサービスのセットを登録します。ドキュメントサービス nextpdf.document（NextPDF\Contracts\PdfDocumentInterface および NextPDF\Core\Document にエイリアス設定）は 共有されません。resolve（解決）するたびに、個別に使い捨てできるドキュメントが返されます。これは PSR-11 コンテナーコントラクトと一致します。同コントラクトでは、同じ識別子に対する連続した 2 回の get() 呼び出しが、コンテナーの構成によっては異なる値を返すことがあります。PSR-11 §1.1.2 を参照してください。非共有のバインディングは意図的なものです。ドキュメントはレンダリングごとの状態を蓄積するため、リクエストごとに新規インスタンスを用いることで、長時間稼働するワーカーで状態がリクエスト間に漏えいするのを防ぎます。

フォントレジストリ（NextPDF\Contracts\FontRegistryInterface）は逆の動作をします。これは共有シングルトンです。画像レジストリには kernel.reset タグが付与されているため、FrankenPHP および Messenger ワーカーでは、その上限付きキャッシュがリクエスト間でクリアされます。設定ページには、サービスとエイリアスの完全な一覧が記載されています。

オプションのロギング

フォントレジストリと画像レジストリは、オプションの PSR-3 ロガーを受け入れます。このバンドルは、アプリケーションがロガーを提供する場合にのみ Psr\Log\LoggerInterface をバインドします（nullOnInvalid()）。したがってロギングは必須の依存関係ではなく、オプションのコラボレーターです。これは PSR-3 ロガーコントラクトと一致します。同コントラクトでは、ロガーは注入される交換可能なコラボレーターです（PSR-3）。

コア機能とオプション機能

バンドル自体は Apache-2.0 のコアソフトウェアです。一部の機能は、オプションのパッケージを併せてインストールした場合にのみ利用できます。

機能	必要なもの	検出方法
PDF 生成、`PdfFactory`、`PdfResponse`	コアのみ	常時利用可能
非同期生成	`symfony/messenger`	Messenger がインストールされている場合にハンドラーが有効になる
Chrome CDP による HTML レンダリング	`nextpdf/artisan`	コンパイル時の `class_exists` による検査
PDF/A アーカイブ、電子署名	`nextpdf/premium`（Pro をインストール）	コンパイル時の `class_exists` による検査

パッケージ nextpdf/premium がインストールされている場合、このバンドルはベースラインの PAdES B-B 署名構成を適用できます。より上位の署名プロファイルは、このバンドルのドキュメントの対象外です。エディションのマトリクスについては、NextPDF Premium のドキュメントを参照してください。

このバンドルを使用する場面

Symfony 7 の HTTP アプリケーションまたはワーカー内で PDF を構築する場合は、nextpdf/symfony を使用してください。このバンドルは、コンテナーで管理されるサービス、ワーカーセーフなレジストリ、安全なダウンロードレスポンスを提供するため、エンジンを手作業で結線する必要がありません。スクリプト内で単発の生成だけが必要な場合は、コアの nextpdf/core パッケージだけで十分です。

準拠

各行は、このページで示される規範的な主張であり、ゲート付き 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 のオプション依存関係

商用に関する背景情報

電子署名と PDF/A アーカイブは、nextpdf/premium（Pro）をバンドルと併せてインストールすると利用できるようになります。これはオプションの Pro 機能です。ここで説明している Core バンドルでは、これを採用するためにコードを変更する必要はありません。</get-license/?intent=symfony-pro> を参照してください。