Laravel API リファレンス

概要

nextpdf/laravel パッケージは、フレームワーク非依存の NextPDF コアを Laravel アプリケーションに組み込みます。直接呼び出せる入口は 4 つあります。素早く作成するための Pdf ファサード、依存性注入で使えるドキュメント生成用の PdfDocumentInterface コンテナバインディング、完成したドキュメントを HTTP レスポンスに変換する PdfResponse ヘルパー、リクエストの外で生成を担う GeneratePdfJob キュージョブです。NextPdfServiceProvider はすべてのバインディングを登録し、自動検出されるため、手動セットアップは不要です。config/nextpdf.php の設定で、デフォルト、フォント、キューイング、およびオプションの署名と TSA 機能を制御します。

まずはここから始めてください。コントローラーから直接 PDF を送信するには、ドキュメントを構築して PdfResponse::download($document, 'file.pdf') を返します。以下の最初の例を参照してください。

よくあるタスク

以下のスニペットでは、最初に使う 3 つのフローを扱います。各スニペットはパッケージのソースに照らして検証済みです。その後に、シンボル別の網羅的な表を示します。

コントローラーからダウンロード可能な PDF を返します（最もよくあるタスク）。

<?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(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

動作内容：新しいドキュメントを注入し、1 行を書き込み、attachment レスポンス（Content-Type: application/pdf と OWASP セキュリティヘッダー付き）を返します。ブラウザーでプレビューするには、download() を inline() に置き換えてください。

Pdf ファサードで作成して保存します（スクリプトや短いフローには最短の手段）。

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

動作内容：ファサードはコンテナから新しいドキュメントを resolve（解決）し、1 つのセルを書き込み、完成した PDF をディスクに保存します。

GeneratePdfJob を使ってリクエストスレッド外で PDF を生成します。

<?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 の出力パスを検証します。キュー名、タイムアウト、接続は config('nextpdf.queue.*') から取得されます。

ファサード

Pdf ファサードは、新規のコア Document を静的にプロキシします。静的な記法のほうが読みやすい、短いコントローラーフローで使用してください。各行は、プロキシされたドキュメントメソッド 1 つに対応します。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗する条件	備考
`NextPDF\Laravel\Facades\Pdf`	なし。静的ファサードアクセサーが解決する `NextPDF\Contracts\PdfDocumentInterface`	Laravel がドキュメントインターフェイスの現在のコンテナバインディングを解決します。	基盤となるコアドキュメントの fluent API。	プロバイダーが登録されていない場合は Laravel コンテナバインディングが失敗します。	短いコントローラーフローで使用してください。サービスやジョブにはコンストラクター注入を推奨します。
`Pdf::setTitle(string $title)`	`title`：ドキュメントのタイトル。	以前のタイトルを置き換えます。	`static`	コアの検証エラーまたは書き込み時のエラー。	コアの `Document` にプロキシされます。
`Pdf::setAuthor(string $author)`	`author`：ドキュメントの作成者メタデータ。	以前の作成者を置き換えます。	`static`	コアのメタデータ検証エラー。	アプリケーション全体のメタデータには、設定済みのデフォルトを推奨します。
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`：任意のページサイズ。`orientation`：デフォルトは `Portrait`。	`size` を省略した場合は configured/default のページサイズを使用します。	`static`	コアのページ検証エラー。	出力サイズが重要な場合は、明示的な `PageSize` を使用してください。
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	フォントファミリー、スタイル、ポイントサイズ。	空のスタイルと 12 pt のサイズ。	`static`	フォントレジストリまたはエンコーディングのエラー。	レイテンシーが重要な場合は、`nextpdf.preload_fonts` を通じて本番フォントをプリロードしてください。
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	セルのボックス、テキスト、罫線フラグ、改行フラグ、配置。	テキストなし、罫線なし、改行なし、左揃え。	`static`	レイアウトまたはテキストエンコーディングのエラー。	単純な固定レイアウトの出力に使用してください。
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	セルの幅、行の高さ、テキスト、罫線フラグ、配置。	罫線なし、左揃え。	`static`	レイアウトまたはテキストエンコーディングのエラー。	テキストを固定幅内で折り返す場合に使用してください。
`Pdf::writeHtml(string $html)`	`html`：HTML フラグメント。	現在のページにレンダリングし、必要な場合は新しいページを作成します。	`static`	コアの HTML レンダリングエラー。	信頼できない HTML を受け入れる前に、入力サイズとリソースのポリシーを適用してください。
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	ファイルパスと任意の配置矩形。	座標を省略した場合、コアドキュメントが現在位置と本来のサイズを選択します。	`static`	画像のデコード、パス、またはレイアウトのエラー。	ユーザー指定のパスを受け入れる前に、画像ソースのポリシーを検証してください。
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`：任意の名前。`dest`：出力先。	出力先を省略した場合はインライン出力。	`string`	コアのシリアライズエラー。	Laravel の HTTP レスポンスには `PdfResponse` を推奨します。
`Pdf::save(string $path)`	`path`：ファイルシステムのターゲット。	完成した PDF をディスクに書き込みます。	`void`	ファイルシステムまたはコアの書き込みエラー。	出力ディレクトリはアプリケーションコードで検証してください。
`Pdf::getPdfData()`	なし。	PDF をメモリ上に具現化します。	`string`	コアのシリアライズエラー。	別のフレームワークオブジェクトにレスポンスボディを持たせる必要がある場合に使用してください。

サービスプロバイダーとバインディング

コンテナエントリを直接解決したり、オーバーライドしたりする必要がある場合は、この表を参照してください。たとえば、DocumentFactoryInterface をサービスに注入する場合や、provides() が遅延対象として返す内容を確認する場合です。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗する条件	備考
`NextPdfServiceProvider::register()`	なし。	設定ファイル `config/nextpdf.php` をマージし、レジストリ、ドキュメントファクトリー、ドキュメントバインディング、HTTP クライアント、TSA クライアント、署名者、およびオプションの電子請求書コントラクトを登録します。	`void`	機能使用時のコンテナまたはオプションクラスの解決エラー。	`FontRegistryInterface` と `ImageRegistry` は共有されます。ドキュメントは常に新規です。
`NextPdfServiceProvider::boot()`	なし。	必須の PHP 拡張機能を検証し、コンソールモードで `nextpdf-config` をパブリッシュします。	`void`	`RuntimeException`（必須の拡張機能が利用できない場合）。	必須の拡張機能は `mbstring` と `zlib` です。
`NextPdfServiceProvider::provides()`	なし。	遅延サービス ID を報告します。	`array<string>`	想定されません。	対象は、`PdfDocumentInterface`、`DocumentFactoryInterface`、`FontRegistryInterface`、`SignerInterface`、`TsaClient`、`ClientInterface`、および `nextpdf` です。
`PdfDocumentInterface` / `nextpdf`	Laravel コンテナから解決されます。	使い捨ての `Document` を `DocumentFactoryInterface` から作成し、設定済みのデフォルトとオプションの PDF/A または Artisan 設定を適用します。	`NextPDF\Core\Document`	設定されているが利用できないオプション拡張機能のエラー。	リクエストまたはジョブごとに新しいドキュメントを解決してください。
`DocumentFactoryInterface`	Laravel コンテナから解決されます。	プロセス存続期間中のフォントレジストリと画像レジストリを共有するシングルトンファクトリー。	`DocumentFactoryInterface`	レジストリのセットアップエラー。	明示的な依存性注入に使用してください。
`SignerInterface`	Laravel コンテナから解決されます。	既定では `null` を返します。ただし `nextpdf.signature.enabled` と証明書パスが設定されている場合を除きます。	`SignerInterface	null`	証明書の読み込みまたは署名レベルの検証エラー。

構成

バインディングが読み取るランタイム向けの nextpdf.* キーを確認するには、この表を使用してください。環境変数とデフォルトを含むキーごとの完全なリファレンスは /integrations/laravel/configuration/. にあります。

キー	型	デフォルトの動作	備考
`nextpdf.fonts_path`	`string`	省略した場合は Laravel のリソースフォントを使用します。	カスタムフォントとウォームアップ用のディレクトリ。
`nextpdf.cache_path`	`string`	アプリケーションのキャッシュパス。	PHP ワーカーから書き込める状態に保ってください。
`nextpdf.preload_fonts`	`list<string>`	空のリスト。	レジストリ作成時にウォームアップされ、その後レジストリはロックされます。
`nextpdf.image_cache_mb`	`int`	上限付きの画像キャッシュサイズ。	プロセス存続期間の画像キャッシュメモリを制限します。
`nextpdf.defaults.*`	`array`	作成者は `NextPDF`、言語は `en`、任意の作成者およびレイアウトのデフォルト。	各新規ドキュメントに適用されます。
`nextpdf.artisan.*`	`array`	インストールされ、設定されている場合を除き、Chrome レンダラーは無効です。	設定は `ChromeRendererConfig::fromArray()` にマッピングされます。
`nextpdf.signature.*`	`array`	デフォルトでは署名は無効です。	証明書、秘密鍵、パスワード、追加の証明書、および署名レベル。
`nextpdf.tsa.*`	`array`	URL が空の場合、TSA は無効です。	資格情報、mTLS ファイル、タイムアウト、公開鍵ピン、および HTTP ポリシーをサポートします。
`nextpdf.ocsp_cache.*`	`array`	OCSP キャッシュは設定済みの TTL で有効です。	利用可能な場合、署名検証フローで使用されます。

HTTP レスポンス

完成したドキュメントを HTTP 経由で返し、インライン表示、添付ファイルのダウンロード、ストリーミング出力のいずれかを選ぶ必要がある場合は、この表を使用してください。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗する条件	備考
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`：構築済みのドキュメント。`filename`：Content-Disposition のファイル名。	空のファイル名は `document.pdf` に正規化されます。	`Illuminate\Http\Response`	コアのシリアライズエラーまたはレスポンス構築エラー。	PDF のコンテンツタイプと防御的なヘッダーを設定します。
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	戻り値は `inline` と同じで、disposition は attachment です。	ブラウザーのダウンロードレスポンス。	`Illuminate\Http\Response`	上記の `inline` と同じ。	明示的なファイルダウンロードに使用してください。
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	上記の `inline` と同じ。	PDF のバイト列を具現化してから、64 KB のチャンクを送出します。	`Symfony\Component\HttpFoundation\StreamedResponse`	上記の `inline` と同じ。	これはストリーミング HTTP 出力であり、ゼロコピーレンダリングではありません。
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	戻り値は `streamInline` と同じで、disposition は attachment です。	ダウンロードストリームのレスポンス。	`StreamedResponse`	上記の `streamInline` と同じ。	レンダリングする前に入力サイズと出力サイズの上限を適用してください。

キュージョブ

リクエストスレッドの外へ生成を移す場合は、この表を使用してください。GeneratePdfJob の構築、ディスパッチ、成功または失敗コールバックの設定を扱います。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗する条件	備考
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`：ターゲットの `.pdf`。`builder`：`PdfDocumentInterface` を受け取ります。コールバックは任意です。	キュー名、タイムアウト、接続は `config('nextpdf.queue.*')` から読み取られます。	ジョブのインスタンス。	ビルダーまたはコールバックをシリアライズできない場合のシリアライズエラー。	ビルダーは設定済みのドキュメントを返す必要があります。
`GeneratePdfJob::handle()`	なし。	まず `PdfDocumentInterface` を解決し、ビルダーを適用し、出力パスを検証してから保存します。	`void`	`InvalidArgumentException`（安全でない出力パスに対して）。コアの書き込みエラー。	ストリームラッパー、null バイト、`..` セグメント、および `.pdf` 以外のパスを拒否します。
`GeneratePdfJob::failed(Throwable $exception)`	`exception`：失敗の原因。	設定済みの失敗コールバックがある場合は、それを呼び出します。	`void`	コールバックの失敗。	コールバックはべき等に保ってください。
`GeneratePdfJob::then(callable $callback)`	`callback`：出力パスを受け取ります。	成功コールバックを置き換えます。	`self`	シリアライズ可能なクロージャのエラー。	ディスパッチ設定用の fluent ヘルパー。
`GeneratePdfJob::catch(callable $callback)`	`callback`：スローされた `Throwable` を受け取ります。	失敗コールバックを置き換えます。	`self`	シリアライズ可能なクロージャのエラー。	アラートや補償的なクリーンアップに使用してください。

開発上の注意

PdfResponse は、レスポンスを構築する前に必ず getPdfData() を呼び出します。これは遅延ドキュメントビルダーではありません。
共有トランスポートではキューのペイロードが改ざんされる可能性があります。出力パスはアプリケーションが所有するディレクトリ内に限定してください。
リクエストまたはジョブごとに新しいドキュメントを使用してください。ドキュメントを複数のリクエストにまたがって再利用しないでください。