NextPDF Symfony バンドルのトラブルシューティング

概要

ほとんどの問題は、検出、構成の検証、コンテナーの結線、Messenger のルーティングという 4 つの領域のいずれかに分類されます。以下の各セクションでは、症状とバンドルソース内の該当する検証動作を対応させて示し、修正を確認するためのコンソールコマンドも示します。

バンドルが登録されていない

症状: PdfFactory をオートワイヤーできない、または debug:container nextpdf で何も見つからない。

原因: バンドルが config/bundles.php に追加されていません。Flex が実行されなかったか、アプリケーションが Flex を使用していないかのどちらかです。

resolve（解決）方法:

php bin/console debug:container nextpdf

空の場合は、バンドルを手動で追加します。

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

自動登録のヒントは、バンドルの composer.json の extra.symfony.bundles 配下にあります。これは Flex が有効なアプリケーションにのみ適用されます。

PHP 拡張機能の不足でブートが失敗する

症状: ブート時にカーネルが RuntimeException をスローし、その内容で ext-mbstring または ext-zlib に言及します。

原因: これはバンドルが意図的に設けているフェイルファストガード NextPdfExtension::guardRequiredExtensions() です。不具合ではありません。

解決方法: 指定された拡張機能を php.ini で有効にし、ランタイムを再起動します。次のコマンドで確認します。

php -m | grep -E 'mbstring|zlib'

ビルド時に構成が拒否される

症状: cache:clear または cache:warmup の実行中に、Symfony\Component\Config\Definition\Exception\InvalidConfigurationException が発生する。

原因: 値がスキーマの範囲外です。これらの制約は Configuration.php に由来します。

page_format は A4、A3、A5、Letter、Legal、Tabloid のいずれかである必要があります。
orientation は P または L である必要があります。
unit は pt、mm、cm、in のいずれかである必要があります。
pdfa は null、4、4e、または 4f である必要があります。
image_cache_mb は >= 0 である必要があります。

解決方法: マージ済みの構成を表示し、問題のあるキーを修正します。

php bin/console debug:config nextpdf

PDF/A または署名が反映されない

症状: pdfa または signature セクションが設定されているのに、出力が通常の PDF になる。

原因: これらの機能には nextpdf/premium が必要です。PdfFactory は、コンパイル時に Pro 拡張機能が検出された場合にのみ PDF/A を適用します。コンパイラーパスが署名者を登録するのは、signature.enabled が true で、かつ signature.certificate が設定されている場合のみです。

解決方法: Premium がインストールされており、署名者サービスが存在することを確認します。

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

Premium が存在しない場合、バンドルは構成を保存しますが、設計上、それを有効にはしません。Pro を使用した場合に文書化されているバンドルの署名機能は、ベースラインの B-B プロファイルです。NextPDF Premium のドキュメントでは、B-B を超えるプロファイルについて説明しています。

Chrome レンダリングが何も行わない

症状: artisan の構成が無視される。

原因: Chrome CDP レンダリングには nextpdf/artisan が必要です。コンパイラーパスは、コンパイル時に class_exists でこれを検出します。拡張機能が存在しない場合、レンダラーは結線されません。

解決方法:

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

この検出はコンテナーのコンパイル中に実行されます。そのため、拡張機能をインストールした後は、改めて cache:clear を実行してください。

Messenger ハンドラーが呼び出されない

症状: GeneratePdfMessage がディスパッチされても、PDF が書き込まれない。

原因と解決方法:

メッセージがルーティングされていない — NextPDF\Symfony\Message\GeneratePdfMessage を config/packages/messenger.yaml 内のトランスポートにマッピングするルーティングエントリを追加し、ワーカーを実行します（php bin/console messenger:consume <transport>）。
ビルダーがロケーターに存在しない — ハンドラーは、クラス文字列の ID を使って PSR-11 ロケーターからビルダーを取得します。コンテナー識別子とは、エントリを一意に識別する文字列です（PSR-11 §1.1.2）。ロケーターにビルダークラスが登録されていない場合、ハンドラーは RuntimeException を発生させ、構成されたビルダーが PdfBuilderInterface を実装している必要があることを示します。ビルダーを登録してから、ロケーターで参照します。

ルーティングとロケーターを確認します。

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

ディスパッチ時に InvalidArgumentException でメッセージが拒否される

症状: GeneratePdfMessage の構築時に InvalidArgumentException がスローされる。

原因: メッセージのデータ転送オブジェクト（DTO）が入力を検証します。検証済みの拒否ルールは次のとおりです。

空の出力パス、または NULL バイトを含むパス。
ストリームラッパーのスキーム（例：php://...）。
パス内の .. によるパストラバーサルのセグメント（POSIX または Windows の区切り文字）。
出力パスのうち、.pdf で終わっていないもの（大文字小文字を区別しない）。
構文的に有効なクラス名ではない builderClass。

解決方法: .pdf で終わる絶対ファイルシステムパスと、実在する完全修飾ビルダークラス名を渡します。

ドキュメントに古いデータが残る

症状: 生成された PDF に、以前のリクエストのコンテンツが含まれる。

原因: 長時間稼働するワーカーで、Document インスタンスが複数のリクエストにまたがって保持されていました。ドキュメントサービスは、まさにこれを防ぐために非共有になっています。

解決方法: リクエストスコープのメソッド内で PdfFactory::create() を呼び出します。返されたドキュメントを共有サービスに保存しないでください。

診断コマンドリファレンス

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

準拠

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

仕様	箇条	リファレンス ID	主張
PSR-11	`psr_11_container#1.1.2.p4`		コンテナーの has()/get() 識別子コントラクト