NextPDF Laravel 統合概要

概要

nextpdf/laravel パッケージは、NextPDF PDF エンジンを Laravel 12 アプリケーションに接続し、コンテナーバインディングを自動登録します。このパッケージには、Pdf ファサード、PdfResponse HTTP ヘルパー、キュー対応の GeneratePdfJob が含まれています。Laravel はこのパッケージを自動検出するため、手動登録は不要です。

インストール

composer require nextpdf/laravel

Composer の制約は nextpdf/core: ^3.0 || ^5.2 です。また、このパッケージには laravel/framework: ^12.0 および php: >=8.4 <9.0 も必要です。設定の公開やオプション拡張を含む完全な手順については、/integrations/laravel/install/. を参照してください。

概念的な概要

このパッケージは、Laravel サービスコンテナーと、フレームワークに依存しない NextPDF コアとの間にある薄い接続層です。PDF 生成を再実装するものではありません。代わりに、コアの NextPDF\Core\Document モデルを Laravel のライフサイクル、設定、キュー処理、HTTP レイヤーに適合させます。

次の図は、リクエストがアプリケーションコードからパッケージを経由し、共有のコアレジストリへどのように流れるかを示しています。

NextPDF Laravel request and render flow

オートロードのマッピングは、単一の PSR-4 エントリで構成されます。PSR-4 はオートロードに関する PHP Standard Recommendation であり、そのプレフィックス NextPDF\Laravel\ は src/Laravel/ にマッピングされます。PSR-4 では、ネームスペースのプレフィックスがベースディレクトリに対応し、残りのクラス名はそのディレクトリ配下のファイルパスにマッピングされます（PSR-4 §3）。このプレフィックス配下には、4 つのプロダクションクラスがあります。

NextPDF\Laravel\NextPdfServiceProvider — バインディングを登録し、設定を公開します。
NextPDF\Laravel\Facades\Pdf — コンテナーから新しいドキュメントを resolve（解決）するための静的プロキシです。
NextPDF\Laravel\Http\PdfResponse — インライン、ダウンロード、ストリーミングの各 PDF レスポンスを、固定のセキュリティヘッダーセットを付与して生成するファクトリです。
NextPDF\Laravel\Jobs\GeneratePdfJob — ワーカー上で PDF を構築して保存するキュー対応のジョブです。

このサービスプロバイダーは DeferrableProvider を実装しているため、公開されているエントリのいずれかを解決したときにのみバインディングを登録します。この遅延読み込みにより、フレームワークの起動経路を軽量に保ちます。プロバイダーの provides() メソッドは遅延エントリの一覧を返し、コンテナーはこの一覧を読み取って各キーをプロバイダーにマッピングします。

解決はコンテナーのコントラクトに従います。バインディングが存在する場合、識別子を解決すると登録済みのエントリが返されます。PSR-11 はコンテナーの相互運用性に関する PHP Standard Recommendation であり、同じ識別子に対する連続した 2 回の get() 呼び出しが、バインディング戦略に応じて異なる値を返す場合があると述べています（PSR-11 §1.1.2）。NextPDF はこの動作を意図的に利用しています。レジストリはシングルトンであるため、解決のたびに同じインスタンスが返されます。一方、ドキュメントはファクトリにバインドされているため、解決のたびに新しいインスタンスが返されます。バインディングのライフタイムの完全な一覧については、/integrations/laravel/boot-and-discovery/. を参照してください。

このアーキテクチャは、Octane、RoadRunner、Swoole などの長寿命ワーカーを対象としています。フォントレジストリは、プロセスライフタイムのシングルトンです。パッケージはこれを一度だけウォームアップしてからロックするため、どのリクエストも共有フォント状態を変更できません。イメージレジストリは、上限付きの最長未使用（LRU）キャッシュを備えたプロセスライフタイムのシングルトンです。パッケージは常に DocumentFactory からドキュメントを新規作成するため、リクエストごとの可変状態がリクエストをまたいで漏れることはありません。

API サーフェス

クラス	パブリックエントリポイント	戻り値	用途
`NextPdfServiceProvider`	`register()`, `boot()`, `provides()`	`void` / `array`	コンテナーバインディング、設定公開、遅延エントリ一覧
`Facades\Pdf`	静的プロキシ（`addPage()`, `cell()`, `save()` など）	`static` / mixed	呼び出しごとに `PdfDocumentInterface` を解決
`Http\PdfResponse`	`inline()`, `download()`, `streamInline()`, `streamDownload()`	`Response` / `StreamedResponse`	OWASP ヘッダーを付与した HTTP レスポンス
`Jobs\GeneratePdfJob`	`dispatch()`, `handle()`, `then()`, `catch()`, `failed()`	`PendingDispatch` / `void` / `self`	キュー対応の PDF 生成

プロバイダーによってバインドされるコンテナーキー:

キー	ライフタイム	解決先
`NextPDF\Contracts\FontRegistryInterface`（エイリアス `FontRegistry`）	シングルトン、ロック済み	`NextPDF\Typography\FontRegistry`
`NextPDF\Graphics\ImageRegistry`	シングルトン、LRU 上限付き	`ImageRegistry`
`NextPDF\Contracts\DocumentFactoryInterface`（エイリアス `DocumentFactory`）	シングルトン	`NextPDF\Core\DocumentFactory`
`Psr\Http\Client\ClientInterface`	シングルトン	`SecurityAwareHttpClient` がラップする `CurlHttpClient`
`NextPDF\Security\Timestamp\TsaClient`	スコープ付き	`TsaClient`。TSA URL がない場合は `null`
`NextPDF\Contracts\SignerInterface`	ファクトリ	`DigitalSigner`。署名が無効な場合は `null`
`NextPDF\Contracts\PdfDocumentInterface`（エイリアス `nextpdf`）	ファクトリ	`NextPDF\Core\Document`
`NextPDF\Contracts\EInvoice\{Embedder,Validator,Profile,SchematronRunner}Interface`	ファクトリ	次の場合にのみ解決: `nextpdf/premium` がインストールされているとき

コードサンプル — クイックスタート

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

コントローラースコープで実行できる例については、/integrations/laravel/quickstart/. を参照してください。

コードサンプル — プロダクション

プロダクションパターンでは、ファサードではなくコンテナーからドキュメントコントラクトを解決します。これにより、呼び出し側が明示的になり、テストしやすくなります。依存性注入（DI）とエラー処理を含む完全なコントローラーについては、/integrations/laravel/production-usage/. を参照してください。

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Invoice', newLine: true);

return PdfResponse::download($document, 'invoice.pdf');

エッジケースと注意点

プロバイダーは遅延されているため、関連のないコンテナーキーを解決しても NextPDF は起動しません。バインディングは、provides() のエントリのいずれかを要求したときにのみ利用可能になります。
SignerInterface と TsaClient は、署名またはタイムスタンプ局を設定していない場合、仕様上 null に解決されます。コードは結果を null チェックする必要があります。インスタンスが存在することを前提にしないでください。
e-invoice コントラクトのバインディングは常に登録されますが、解決先となる Premium の具象クラスは nextpdf/premium がインストールされている場合にのみ存在します。Premium がない状態でこれらを解決すると class-not-found エラーが発生し、このエラーは起動時ではなく最初の解決時に発生します。
ファサードは解決のたびに新しいドキュメントを返します。同一リクエスト内で Pdf:: 静的呼び出しを 2 回行い、その間に Pdf::clearResolvedInstances() を挟む場合を考えてみましょう。これら 2 回の呼び出しは、それぞれ異なるドキュメントを操作します。

パフォーマンス

プロバイダーの登録は O(1) の時間で実行されます。プロバイダーはクロージャをバインドするだけで、重いオブジェクトを構築しないため、構築コストは最初の解決時まで遅延されます。フォントレジストリのウォームアップは O(f) の時間で実行されます。ここで f はプリロードされるフォントファイルの数であり、ワーカープロセスごとに 1 回実行されます。このタイミングにより、長寿命ワーカーにおける初回リクエストのレイテンシーが分散されます。この概要ページのメモリバジェットは、フロントマターのフィールド performance_budget に記録されています。

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

PdfResponse は、Open Worldwide Application Security Project（OWASP）に基づく固定のヘッダーセットを適用します。ヘッダーは X-Content-Type-Options: nosniff、X-Frame-Options: DENY、Content-Security-Policy: default-src 'none'、X-Robots-Tag、および Referrer-Policy: no-referrer です。GeneratePdfJob はワーカー側で出力パスを検証し、このチェックによって改ざんされたシリアライズ済みペイロードを軽減します。完全な脅威モデルとデプロイ設定については、/integrations/laravel/security-and-operations/. を参照してください。

適合性

主張	出典	条項	リファレンス ID
コンテナーの解決 / ライフタイムのセマンティクス	PSR-11 コンテナー	§1.1.2
PSR-4 オートロードプレフィックスのマッピング	PSR-4 オートローダー	§3

商用コンテキスト

nextpdf/premium がインストールされている場合、同じプロバイダーがさらに多くの機能を公開します。つまり、電子署名（PAdES B-B）、PDF/A アーカイブ、および e-invoice コントラクトのバインディングです。プロバイダーはこれらを同一のコンテナーキーを通じて公開するため、ここで説明する Core パッケージでは、これらの機能を採用するためのコード変更は不要です。詳細については、次を参照してください。 https://nextpdf.dev/get-license/?intent=laravel-signing。