NextPDF の Laravel 統合

概要

このハウツーでは、NextPDF を Laravel 12 アプリケーションに組み込みます。次の 6 つの段階を順に進めます。パッケージのインストール、Laravel による自動検出、設定の公開、コンテナーバインディングの resolve（解決）、HTTP レスポンスの返却、そしてキュー投入ジョブの実行です。各段階から、該当領域の詳細リファレンスを参照できます。

インストール

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

ブート / 自動検出

Laravel は、パッケージの composer.jsonextra.laravel ブロックから、サービスプロバイダーとファサードのエイリアスを自動検出します。config/app.php を編集する必要はありません。オートロードマップは、単一の PSR-4 エントリです。PSR-4 のプレフィックスからベースディレクトリへのルール（PSR-4 §3）に従い、NextPDF\Laravel\ プレフィックスは src/Laravel/ に解決されます。このプロバイダーは遅延型で、provides() のいずれかのエントリが最初に解決されたときにブートします。検出の内部動作について詳しくは、/integrations/laravel/boot-and-discovery/ を参照してください。

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

ドキュメントのコントラクトは、コンテナーから解決します。バインドされた識別子は、登録済みのエントリに解決されます（PSR-11 §1.1.2）。ドキュメントのバインディングはファクトリであるため、解決するたびに新しいドキュメントが得られます。フォントレジストリとイメージレジストリはシングルトンであるため、解決するたびに同じ共有インスタンスが返されます。バインディングのライフタイムの完全な一覧は、/integrations/laravel/overview/ と /integrations/laravel/boot-and-discovery/ にあります。

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

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

設定の公開

php artisan vendor:publish --tag=nextpdf-config

このコマンドは config/nextpdf.php を書き込みます。各キー、その環境変数、および既定値は、/integrations/laravel/configuration/ に記載されています。

サービスプロバイダー / バンドルのスモークテスト

このパッケージには、プロバイダーをエンドツーエンドで検証する Testbench ベースのテストスイートが付属しています。利用側のアプリケーションに追加できる最小限のスモークテストを次に示します。

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

これら 2 つのアサーションは、パッケージ自体の EInvoiceServiceProviderIntegrationTest にある一度限りの適合性チェックを反映したものです。ドキュメントがファクトリとしてバインドされていること、およびフォントレジストリがロックされたシングルトンであることを確認します。

公開 API のエントリポイント

エントリポイント	目的	リファレンス
`NextPDF\Laravel\Facades\Pdf`	新しいドキュメントに対する静的プロキシ	クイックスタート: /integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	コンテナーから解決されたドキュメント	本番運用ガイド: /integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	インライン / ダウンロード / ストリーム配信の HTTP レスポンス	セキュリティと運用: /integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	キュー投入による生成	本番運用ガイド: /integrations/laravel/production-usage/

コードサンプル — 本番

依存性注入で組み込み、エラー処理を施したコントローラーの全体は、/integrations/laravel/production-usage/ に記載されています。成功時と失敗時のコールバックを含むキュー投入ジョブも同じページに記載されています。

エッジケースと注意点

解決するのは PdfDocumentInterface であり、具象クラスの Document ではありません。これにより、バインディングはテスト可能で差し替え可能な状態に保たれます。
SignerInterface と TsaClient は、設定するまで null に解決されます。必ず null チェックを行ってください。
e-invoice のコントラクトには nextpdf/premium が必要です。コントラクト自体はバインドされていますが、これがないと最初の解決時にエラーになります。

パフォーマンス

プロバイダーは遅延型であるため、エンドツーエンドで組み込んでもブートコストは増加しません。最初の解決時の構築コストとフォントのウォームアップコストについては、/integrations/laravel/boot-and-discovery/ で説明しています。

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

PdfResponse は、固定の OWASP ヘッダーセットを適用します。GeneratePdfJob は、ワーカー上で出力パスを検証します。脅威モデルは、/integrations/laravel/security-and-operations/ にあります。

適合性

主張	出典	条項	リファレンス ID
バインドされた識別子が登録済みのエントリに解決される	PSR-11 コンテナー	§1.1.2
PSR-4 のプレフィックスがベースディレクトリにマッピングされる	PSR-4 オートローダー	§3

商用コンテキスト

nextpdf/premium がインストールされている場合、署名、PDF/A、e-invoice のコントラクトは同じプロバイダーを通じて統合されます。これは任意の Enterprise 機能です。ここで説明している Core パッケージでは、これを採用するためにコードを変更する必要はありません。https://nextpdf.dev/get-license/?intent=laravel-signing を参照してください。