インテグレーションを選ぶ
インテグレーションを選ぶ
「インテグレーションを選ぶ」という見出しのセクションこのページでは、ユースケースとそれに対応するインテグレーションを整理します。 すべての推奨は、パッケージの composer.json の説明と明示された目的のみに基づいており、いずれもソースリポジトリから直接読み取ったものです。 2 つのインテグレーションが重なって見える場合、このページではそれらを区別する要素を示し、判断は読者に委ねます。
自分の状況に合う行を見つけ、そこから始めてください。
ここから始める: 何を持っていますか？
「ここから始める: 何を持っていますか？」という見出しのセクション| 持っているもの … | 使うもの | 理由（検証済みの目的） |
|---|---|---|
| Laravel 12 アプリケーション | nextpdf/laravel | Laravel フレームワークインテグレーション: サービスプロバイダー、ファサード、PDF レスポンスヘルパー。 |
| Symfony 7 アプリケーション | nextpdf/symfony | Symfony バンドル: DI サービスと PDF レスポンスヘルパー。 |
| CodeIgniter 4 アプリケーション | nextpdf/codeigniter | CodeIgniter 4 のサービス、ライブラリラッパー、PDF レスポンスヘルパー。 |
| フレームワークを使わない PHP アプリ | nextpdf/core を直接使用 | フレームワークインテグレーションは不要。エンジンは通常のライブラリとして使えます。 |
| ブラウザーの CSS エンジンを必要とする HTML で、Chrome を実行できる場合 | nextpdf/artisan | ブラウザー品質の CSS レイアウトが必要な HTML 向けの Chrome CDP レンダラー。 |
| DOCX、XLSX、ODT など、変換対象の Office ドキュメント | nextpdf/gotenberg | Gotenberg マイクロサービスを介した Office から PDF への変換。 |
| 運用するブラウザープロセスなしでレンダリングする必要がある場合 | nextpdf/cloudflare | エッジで Cloudflare Browser Rendering API を介して行うサーバーレスレンダリング。 |
| レガシー PDF ライブラリ向けに書かれたコード | nextpdf/compat-legacy | レガシー PDF ライブラリの互換レイヤー。呼び出し箇所を書き換えずに NextPDF を呼び出せます。 |
| PHP 8.1 / 7.4 に固定されたランタイム | nextpdf/backport-builder | エンジンの 8.1 / 7.4 ターゲットをビルドする Rector ダウングレードパイプライン。 |
| リモートの呼び出し元、別の言語、または AI システム | nextpdf/server | NextPDF Connect: リモート実行のための REST、gRPC、Model Context Protocol のインターフェイス。 |
2 つのインテグレーションが当てはまりそうな場合
「2 つのインテグレーションが当てはまりそうな場合」という見出しのセクションHTML を PDF にレンダリングする: Artisan、Gotenberg、Cloudflare、core の比較
「HTML を PDF にレンダリングする: Artisan、Gotenberg、Cloudflare、core の比較」という見出しのセクション3 つのレンダラーブリッジはいずれもマークアップを PDF に変換します。 違いは品質ではなく運用方法にあるため、その運用上の違いが判断材料になります。
nextpdf/artisanは、Chrome DevTools Protocol を介してヘッドレス Chrome を駆動します。 アプリケーションから到達できる Chrome プロセスが必要です。 そのプロセスを運用でき、かつドキュメントがブラウザーの CSS エンジンを必要とする場合に選択してください。nextpdf/gotenbergは、プロセス外の Gotenberg マイクロサービスを HTTP 経由で呼び出します。 レンダリングを独立したサービスとして分離する必要がある場合、または入力が Office ドキュメントの場合に選択してください。 3 つのうち、明示された目的に Office から PDF への変換が含まれるのは Gotenberg だけです。nextpdf/cloudflareは、Cloudflare Browser Rendering API を呼び出します。 実行やパッチ適用が必要なブラウザープロセスを持たずに edge/serverless レンダリングを行いたい場合に選択してください。- プロセス内の NextPDF コア HTML パイプライン は、上記のいずれも必要としません。 レンダラーブリッジは、プロセス内パイプラインではドキュメントに必要なレイアウトの忠実度やプロセスの分離を実現できない場合にのみ使用してください。 ブリッジはそのステップを外部へ委ねるための意図的な選択であり、デフォルトの経路ではありません。
2 つの HTTP ブリッジ（nextpdf/gotenberg、nextpdf/cloudflare）は、ホストが提供する PSR-18 HTTP クライアントを必要とします。 これらのレシピでは、トランスポートの失敗と成功以外の HTTP ステータスを、別々の結果として扱います。
Office ドキュメントを変換する
「Office ドキュメントを変換する」という見出しのセクションnextpdf/gotenberg は、検証済みの composer.json の説明で Office から PDF への変換が挙げられているインテグレーションです。 他のレンダラーブリッジは、Office 入力ではなく HTML レンダリングを対象としています。 ソースが DOCX/XLSX/ODT の場合、これが該当します。
レガシー PDF ライブラリから移行する
「レガシー PDF ライブラリから移行する」という見出しのセクション明示された目的によれば、nextpdf/compat-legacy は、レガシー PDF ライブラリ向けに書かれたコードベースのための互換レイヤーです。 これにより、既存の呼び出し箇所を書き換える前に NextPDF へ接続できます。 これは恒久的なランタイム依存ではなく、削除を前提とした移行補助として扱ってください。 新しいコードは、nextpdf/core（または該当するフレームワークインテグレーション）を直接呼び出します。
PHP 8.1 または 7.4 で実行する
「PHP 8.1 または 7.4 で実行する」という見出しのセクションすべてのエコシステムパッケージは PHP >=8.4 <9.0 を宣言しています。 nextpdf/backport-builder は、まさにこの制約に対応するために存在します。その明示された目的は、PHP 8.1 以上（および 7.4 ターゲット）の成果物をビルドする Rector ダウングレードパイプラインです。 これはビルドツールであり、アプリケーションのランタイム依存ではありません。 ビルダーを実行してバックポートされたエンジンを生成し、そのエンジンをデプロイしてください。
PHP 以外の呼び出し元または AI エージェント
「PHP 以外の呼び出し元または AI エージェント」という見出しのセクションnextpdf/server（NextPDF Connect）は、REST API、gRPC サービス、Model Context Protocol を通じてエンジンを公開します。 呼び出し元がリモートにある場合、別の言語である場合、または PHP ライブラリではなくツールエンドポイントを利用する AI システムである場合に選択してください。 同一プロセス内の PHP アプリケーションでは、ネットワークホップのコストを払う代わりに、nextpdf/core またはフレームワークインテグレーションを使用してください。
複数のインテグレーションを組み合わせて使う
「複数のインテグレーションを組み合わせて使う」という見出しのセクションフレームワークインテグレーションとレンダラーブリッジは異なるレイヤーで動作するため、両方をインストールできます。 フレームワークインテグレーションはコンテナーの配線と HTTP レスポンスを処理し、レンダラーブリッジはレンダリングバックエンドを処理します。 依存関係をまとめて解決する際は、各パッケージが受け入れる nextpdf/core のバージョンを確認してください。 その際は、インテグレーションクックブックのインデックス にあるコア制約のリファレンスが信頼できる情報源です。 組み合わせごとのレシピは該当するリポジトリにあり、そのインデックスからリンクされています。
- インテグレーションクックブック — パッケージとコア制約のリファレンス、およびレシピのリンクインデックス。
- レシピの規約 — 実行可能なすべてのレシピが従う取り決め。