NextPDF における Laravel のブートと自動検出

概要

Laravel は、パッケージの composer.json から NextPdfServiceProvider を自動検出します。プロバイダーは遅延コンテナバインディングを登録し、コンソールコンテキストでは設定ファイルの公開を登録します。このページでは、検出の仕組みとすべてのバインディングのライフタイムについて順を追って説明します。

インストール

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Laravel の自動検出の仕組み

パッケージは、自身の composer.json 内の extra.laravel ブロックで、プロバイダーとファサードのエイリアスを宣言します。

{
  "extra": {
    "laravel": {
      "providers": [
        "NextPDF\\Laravel\\NextPdfServiceProvider"
      ],
      "aliases": {
        "Pdf": "NextPDF\\Laravel\\Facades\\Pdf"
      }
    }
  }
}

composer require を実行すると、Laravel はこのブロックを読み取り、プロバイダーとエイリアスを登録します。config/app.php や bootstrap/providers.php を手動で編集する必要はありません。extra.laravel.providers 配列はサービスプロバイダーを自動登録し、extra.laravel.aliases はファサードのエイリアスを自動登録します（Laravel 12 パッケージ開発ガイド、 https://laravel.com/docs/12.x/packages、2026-05-18 に取得）。

ブートシーケンス

NextPdfServiceProvider は、DeferrableProvider と標準の register() / boot() ライフサイクルをどちらも実装します。

register() は、パッケージの設定を nextpdf キー配下にマージします。続いて、コンテナエントリをバインドします。フォントレジストリ、イメージレジストリ、ドキュメントファクトリ、PSR-18 HTTP クライアント、タイムスタンプクライアント、署名、ドキュメント、および e-invoice の各コントラクトです。いずれのバインディングもクロージャであるため、ここでは重いオブジェクトは何も構築されません。
boot() は、mbstring および zlib の PHP 拡張機能が読み込まれていることを確認します。公開可能な設定を nextpdf-config タグ配下に登録するのは、runningInConsole() が true の場合のみです。

プロバイダーは遅延されるため、register() は provides() が返すエントリのいずれかを解決（resolve）したときにのみ実行されます。無関係なコンテナキーを解決しても NextPDF はブートされません。

コンテナバインディングとライフタイム

PSR-11 では、同じ識別子に対する連続する 2 回の get() 呼び出しが、バインディング戦略に応じて異なる値を返すことが許容されています（PSR-11 §1.1.2）。プロバイダーはこれを意図的に利用しています。

バインディングキー	ライフタイム	備考
`FontRegistryInterface`（+ `FontRegistry` エイリアス）	シングルトン、ウォームアップ後にロック	ウォームアップ元は `preload_fonts`。ロック済みのため、どのリクエストからも変更不可
`ImageRegistry`	シングルトン	サイズは `image_cache_mb` で決まる上限付き LRU キャッシュ。ロックされません
`DocumentFactoryInterface`（+ `DocumentFactory` エイリアス）	シングルトン	ステートレス。2 つのレジストリを共有
`Psr\Http\Client\ClientInterface`	シングルトン	リクエストフォージェリを考慮し、curl クライアントをラップするクライアント。構築元は `tsa.*`
`TsaClient`	スコープ付き	`null`（`tsa.url` が空の場合）
`SignerInterface`	ファクトリ	`null`（署名が無効、または証明書が空の場合）
`PdfDocumentInterface`（+ `nextpdf` エイリアス）	ファクトリ	解決のたびに生成される新しい `NextPDF\Core\Document`。デフォルトのメタデータを適用
`EmbedderInterface`, `ValidatorInterface`, `ProfileInterface`, `SchematronRunnerInterface`	ファクトリ	Premium の具象クラスへ解決。最初の解決でエラーになる原因は、`nextpdf/premium` の欠落

ドキュメントバインディングは、新しいドキュメントごとに defaults.creator、defaults.language、および（空でない場合は）defaults.author を適用します。pdfa が非 null の場合、PDF/A（Premium）を有効にします。artisan セクションが存在し、Chrome ブラウザーファクトリのクラスが存在する場合は、Chrome レンダラーの設定を適用します。

コンテナでは、has() は単一の文字列識別子を受け取ります（PSR-11 §1.1.2）。e-invoice のコントラクトはバインドされているため、Premium がなくても has() はこれらに対して true を返します。不足している具象クラスは、構築時にのみエラーになります。

自動検出の無効化

パッケージをアプリケーションの dont-discover 配列に追加してから、プロバイダーを手動で登録します。

{
  "extra": {
    "laravel": {
      "dont-discover": ["nextpdf/laravel"]
    }
  }
}

<?php

declare(strict_types=1);

return [
    App\Providers\AppServiceProvider::class,
    NextPDF\Laravel\NextPdfServiceProvider::class,
];

設定の解決順序

各キーは次の順序で解決されます。環境変数 → 公開された config/nextpdf.php の値 → register() でマージされたパッケージのデフォルト。ほとんどのキーは、NEXTPDF_* という名前、またはレガシーの TCPDF_* 環境変数名のいずれかを受け付けます。NEXTPDF_* の使用を推奨します。

診断

php artisan package:discover --ansi

出力に nextpdf/laravel を含む行があれば、検出を確認できます。プロバイダーは遅延されるため、バインディング自体は最初の解決まで表示されません。この検出行が正しい成功シグナルです。

エッジケースと注意点

設定の公開はコンソールコンテキストでのみ登録されるため、Web のみのリクエストでは決してトリガーされません。vendor:publish は CLI から実行してください。
レジストリ、ファクトリ、HTTP クライアント、署名、タイムスタンプ、ドキュメントの各キーに加えて、provides() には 4 つの e-invoice コントラクトキーが含まれます。
新規インストール直後は、関連する最初の解決まで何も動いていないように見えることがあります。これは遅延プロバイダーの設計によるものであり、不具合ではありません。

パフォーマンス

register() は O(1) です。登録するのはクロージャのみです。フォントレジストリのウォームアップは、プリロードされるフォント数に対して O(f) であり、ワーカープロセスごとに 1 回実行されます。プロバイダーを遅延させることで、バインディングが実際に使用されるまで、NextPDF の構築コストをフレームワークのブートパスから切り離しておけます。

セキュリティに関する注意

遅延設計により、ブート時の攻撃対象領域が狭まります。ロックされたフォントレジストリは、長時間稼働するワーカーでリクエストをまたいだフォント状態の変更を防止します。脅威の全体像については、/integrations/laravel/security-and-operations/. を参照してください。

準拠

主張	出典	条項	リファレンス ID
連続する解決はバインディング戦略によって異なる場合がある	PSR-11 の Container	§1.1.2
`has()` は 1 つの文字列識別子を受け取る	PSR-11 の Container	§1.1.2

Laravel の検出キー名は、公式の Laravel 12 パッケージドキュメント（https://laravel.com/docs/12.x/packages、2026-05-18 に取得）と照合済みです。

商用コンテキスト

Premium の具象クラスは、同じ遅延バインディングキーを通じて解決されます。これはオプションの Enterprise 機能であり、ここで説明している Core パッケージでは、これを採用するためにコードを変更する必要はありません。https://nextpdf.dev/get-license/?intent=laravel-signing を参照してください。