NextPDF Symfony のブートと検出

概要

カーネルは NextPdfBundle を登録します。バンドルの DI 拡張は services.php を読み込み、構成ツリーをコンテナーパラメーターへ解決します。続いて 1 つのコンパイラーパスが、オプション拡張とフォントのウォームアップを配線します。

Symfony Flex によるバンドルの検出方法

バンドルの composer.json は、自動登録のヒントを宣言します。

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

Symfony Flex アプリケーションでは、これにより NextPDF\Symfony\NextPdfBundle が、すべての環境（all）向けに config/bundles.php へ追加されます。Flex を使用しない場合は、config/bundles.php でバンドルを手動で追加します。Symfony は、バンドル登録モデルを公式にドキュメント化しています（https://symfony.com/doc/current/bundles.html）。バンドルのクラスは、PSR-4 プレフィックス NextPDF\Symfony\ の下でオートロードされ、src/Symfony/ にマッピングされます。PSR-4 オートローダーは、名前空間プレフィックスを対応するベースディレクトリにマッピングします（PSR-4 §2）。

ブートシーケンス

バンドルのソースに照らして検証したブートシーケンスは次のとおりです。

カーネルがバンドルを登録します。 Kernel::registerBundles() は config/bundles.php を読み込み、NextPDF\Symfony\NextPdfBundle をインスタンス化します。これは Symfony\Component\HttpKernel\Bundle\Bundle を継承します。
バンドルのビルド。 NextPdfBundle::build() は親を呼び出し、続いて 1 つのコンパイラーパス OptionalExtensionPass を登録します。NextPdfBundle::getPath() はパッケージルートを返します。
拡張の読み込み。 DI 拡張 NextPDF\Symfony\DependencyInjection\NextPdfExtension（エイリアス nextpdf）は、Configuration に対して processConfiguration() を実行します。解決された値を nextpdf.* コンテナーパラメーターとして設定し、続いて PhpFileLoader を介して config/services.php を読み込みます。
必須拡張のガード。 NextPdfExtension::load() は最後に ext-mbstring と ext-zlib が存在することをアサートし、存在しない場合は即座に失敗します。
コンパイラーパスの実行。 コンテナーのコンパイル中に、OptionalExtensionPass::process() は PdfFactory の拡張可用性フラグを構成し、署名担当と TSA クライアントを条件付きで登録し、フォントレジストリのウォームアップとロックをスケジュールします。
コンテナーのコンパイルとキャッシュ。 Symfony はコンパイル済みコンテナーを書き出します。cache:warmup は、トラフィックを受ける前にこのステップを実行します。

コンパイラーパス

バンドルは、ちょうど 1 つのパス NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass を登録します。これは NextPdfBundle::build() で追加されます。このパスはデフォルト（最適化前）のパスグループで実行されます。このパスは 4 つのステップを実行します。各ステップはガードされており、入力が存在しない場合は何も実行しません。

拡張フラグ — setArtisanAvailable(...) と setProAvailable(...) のメソッド呼び出しを、PdfFactory 定義に追加します。これらの値は、Artisan ブラウザーファクトリーと Pro PDF/A クラスに対するコンパイル時の class_exists プローブに由来します。
署名担当の登録 — nextpdf.signature が存在し、enabled が true で、証明書が設定されている場合に、ベースラインの B-B プロファイル向けの証明書情報ファクトリーと署名担当サービスを登録します。
TSA クライアント — nextpdf.tsa に URL が設定されている場合、TSA クライアントサービスを登録します。
フォントのウォームアップ — nextpdf.preload_fonts が空でない場合、フォントレジストリ定義に warmup() と lock() のメソッド呼び出しを追加します。

コンテナーのバインディング

config/services.php はサービスを定義します。ドキュメントサービス nextpdf.document（NextPDF\Contracts\PdfDocumentInterface および NextPDF\Core\Document のエイリアス）は 非共有 です。解決のたびに新しいドキュメントが返されますが、これは PSR-11 が明示的に許可しています。つまり、1 つの ID に対する連続した get() 呼び出しが、異なる値を返す場合があります（PSR-11 §1.1.2）。フォントレジストリは共有され、ウォームアップ後にロックされます。イメージレジストリは共有され、kernel.reset のタグが付与されます。完全な表は /integrations/symfony/configuration/. にあります。

構成の解決順序

組み込みデフォルト値。これは Configuration（getConfigTreeBuilder()）に由来します。
アプリケーションのオーバーライドは config/packages/nextpdf.yaml に配置し、環境別オーバーライドは config/packages/<env>/ 配下に配置します。
Symfony は %kernel.*% パラメータープレースホルダーを解決します。たとえば、fonts_path はデフォルトで %kernel.project_dir%/resources/fonts になります。
NextPdfExtension::load() は、マージ結果を nextpdf.* コンテナーパラメーターに書き込みます。この値は services.php とコンパイラーパスで使用されます。

無効な値は、ステップ 1〜2 で Symfony の InvalidConfigurationException によって失敗します。

診断

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

1 つ目は、登録済みのサービスを一覧表示します。2 つ目は、マージ済みの構成を出力します。3 つ目は、コンテナーを再構築し、コンパイル時の拡張プローブを再実行します。

準拠性

各行は、このページで示される規範的な主張であり、ゲート付き SDO コーパス由来の完全な 64 桁の 16 進数 reference_id に紐付けられています。Provenance（来歴情報、コーパスマニフェスト、取得トランスポート）は _sidecars/rag-citations.yaml にあります。

仕様	条項	リファレンス ID	主張
PSR-11	`psr_11_container#1.1.2.p3.b`		コンテナーの解決は呼び出しごとに異なる場合がある
PSR-4	`psr_4_autoload#x1.x2.p5`		名前空間プレフィックスからベースディレクトリへのマッピング