NextPDF Laravel クイックスタート

概要

このチュートリアルでは、コントローラーでダウンロード可能な PDF を作成します。その後、同じ処理をキュー投入ジョブへ移します。どのスニペットも、パッケージのテストスイートで検証されている動作と一致しています。

インストール

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

概念的な概要

3 つのエントリーポイントで、ほぼすべての Laravel ユースケースをカバーできます。ファサードを使うと、最も手早く始められます。PdfResponse は、ドキュメントを HTTP レスポンスに変換します。キュー投入ジョブは、負荷の大きい生成処理をリクエストスレッドから切り離すため、ユーザーが完了を待つ必要はありません。このチュートリアルでは、それぞれを順に見ていきます。エラー処理を追加した本番レベルのバージョンについては、/integrations/laravel/production-usage/ を参照してください。

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

1. ファサード

ファサードは、呼び出しのたびにコンテナーから新しいドキュメントを解決します。コンテナーは Laravel のサービスレジストリです。このスニペットは、tests/Unit/Laravel/Facades/PdfTest.php で検証されている動作と一致しています。

<?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'));

2. コントローラーからのダウンロードレスポンス

PdfResponse::download() は Illuminate\Http\Response を返します。このレスポンスには、Content-Type: application/pdf、attachment ディスポジション、OWASP セキュリティヘッダーが含まれます。tests/Unit/Laravel/Http/PdfResponseTest.php では、ステータスコード、コンテンツタイプ、ディスポジションのプレフィックス、ヘッダーを確認しています。

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

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

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

ブラウザーでインライン表示する場合は、download() を inline() に置き換えます。大きなドキュメントでは、streamInline() または streamDownload() を使用します。これらは、決定論的な 64 KB のチャンク単位で PDF を送信します。

3. キュー投入による生成

GeneratePdfJob は、キューワーカー上で PDF を作成して保存します。ビルダークロージャは、コンテナーで解決されたドキュメントを受け取り、設定済みのドキュメントを返します。tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php では、ジョブが指定された出力パスにファイルを作成することを確認しています。

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

出力パスは .pdf で終わる必要があります。ジョブは、書き込み前にワーカー上でパスを検証します。

コードサンプル — 本番

本番向けバージョンでは、明示的なエラー処理、ジョブの成功コールバックと失敗コールバック、型付き例外戦略を追加しています。これらの詳細は、/integrations/laravel/production-usage/ で説明しています。

エッジケースと注意点

ファサードは、解決のたびに異なるドキュメントインスタンスを返します。論理的に異なるドキュメントをまたいで Pdf::getFacadeRoot() をキャッシュしないでください。
PdfResponse ファクトリーのいずれかに空のファイル名を渡すと、既定で document.pdf になります。レスポンスのテストスイートで、この既定値を検証しています。
ASCII 以外のファイル名には、RFC 5987 の filename*= パラメーターが自動的に付与されます。ASCII のファイル名には付与されません。
GeneratePdfJob は、パストラバーサル、ストリームラッパー、ヌルバイト、.pdf 以外の拡張子をすべて拒否します。この場合、ワーカー上で InvalidArgumentException をスローします。

パフォーマンス

1 ページのドキュメントは、フロントマターで定義されたページあたりの実時間バジェットを十分に下回って生成されます。生成処理を GeneratePdfJob に移すと、PDF のビルド時間が HTTP リクエストから完全に切り離されます。リクエストは、ジョブがディスパッチされた時点で返ります。

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

PdfResponse ファクトリーは、固定の OWASP ヘッダーセットを適用します。また、ダウンロードファイル名をサニタイズします。キュー投入ジョブは、出力パスを検証します。詳細な脅威への対応については、/integrations/laravel/security-and-operations/ で説明しています。

準拠

このチュートリアルを規定する規範的な標準はありません。どのスニペットも、パッケージのソースに照らして検証されています。さらに、tests/ 配下の対応するテストに照らしても検証されています。

商用に関する背景

署名付き出力および PDF/A 出力は、nextpdf/premium で利用できます。これはオプションの Enterprise 機能です。ここで説明している Core パッケージでは、この機能を採用するためのコード変更は不要です。https://nextpdf.dev/get-license/?intent=laravel-signing を参照してください。