統合の意思決定ガイド

Spec: ISO/IEC/IEEE 26514:2022, §3.x162 Spec: ISO 24495-1:2023, §5 Evidence: Editorial

概要

NextPDF エコシステムは、軽量なコアエンジンと、目的を絞った一連のパッケージ（フレームワークブリッジ、2 つの HTML レンダラー、エッジレンダラー、実行サーバー）で構成されています。このページでは、各パッケージが実際に何を含んでいるかに基づき、現実のユースケースを適したパッケージへ対応づけます。選択はこのドキュメントが代行するものではなく、根拠に基づいてあなた自身が下す判断であり続けます。

なぜこれが重要か

誤った統合を選ぶと、すぐには表面化しない形でコストがかかります。インプロセスエンジンでドキュメントを問題なくレンダリングできたはずなのにリモートブラウザレンダラーを選ぶと、すべての PDF にネットワークホップと可用性への依存が加わります。本来は完全なブラウザレイアウトエンジンを必要とするドキュメントにインプロセスエンジンを選ぶと、見た目が微妙に誤ったファイルが生成されます。採用するパッケージは、レイテンシー、障害モード、運用上の責任範囲を左右するため、この判断は明示的に行う価値があります。

手短に言うと

コアエンジンから始めてください。 それ以外はすべて追加要素です。インプロセスエンジンがドキュメントを正しくレンダリングできるなら、レンダラーパッケージはまったく必要ありません。
フレームワークブリッジは、ドキュメントではなくフレームワークに従います。 Laravel、Symfony、CodeIgniter の各統合は、ファサードやファクトリ、PDF レスポンス、キューでの生成、自動検出を提供するために存在します。エンジンがレンダリングできる内容を変えるものではありません。
レンダラーは、CSS の忠実度がブラウザを必要とする場合にのみ使用してください。 Artisan（ローカル Chrome）と Cloudflare（エッジブラウザ）は、そのためのものです。Gotenberg は、Office ドキュメントを取り込むために存在します。
呼び出し元が PHP 呼び出しではなく、サービスや AI エージェントである場合は Connect を使用してください。 Connect はエンジンを MCP、REST、gRPC 経由で公開し、危険な操作には人による承認ゲートを設けます。

NextPDF のアプローチ

このエコシステムは、各パッケージが 1 つの役割を担うよう意図的に階層化されています。コアエンジンは PDF をインプロセスでレンダリングします。フレームワークブリッジは、そのエンジンをフレームワークの流儀に適応させます。レンダラーパッケージは、インプロセスエンジンが適切なツールでない場合に、HTML または Office のレイアウトを外部エンジンに委譲します。Connect は、エンジンをネットワークサービスに変えます。これらのパッケージはいずれも互いの責務を重ねておらず、それが判断を扱いやすくしています。競合するツールの中から選ぶのではありません。補完し合うツールを組み合わせているのです。

この判断は、ユースケースに照らして行うのが最善です。この表では、各シナリオを適したパッケージに対応づけ、受け入れることになるトレードオフを示します。

ユースケース	適合するパッケージ	実際に提供するもの	受け入れるトレードオフ
Laravel アプリでの PDF	`nextpdf/laravel`	自動検出されるサービスプロバイダー、`Pdf`ファサード、`PdfResponse`（インライン/ダウンロード/ストリーミング、OWASP ヘッダー）、tries/timeout/バックオフを備えたキュー実行の`GeneratePdfJob`、Octane セーフなロック済みレジストリ	Laravel 12 への依存。エンジンの機能は不変
Symfony アプリでの PDF	`nextpdf/symfony`	自動登録されるバンドル、注入可能な`PdfFactory`、`PdfResponse`、非同期生成のためのオプションの Messenger ハンドラー	Symfony 7.2 バンドルへの依存。機能は不変
CodeIgniter 4 アプリでの PDF	`nextpdf/codeigniter`	`service('pdf')` / `pdf()`ヘルパー、使い捨ての`Document`をラップする`Pdf`ライブラリ、`PdfResponse`、オプションのキュー実行ジョブ	CodeIgniter 4.6 への依存。機能は不変
ドキュメントがインプロセスに近い形で完全なブラウザ CSS（flex/grid/Web フォント）を必要とする	`nextpdf/artisan`	CDP 経由のヘッドレス Chrome。レンダリング後、テキストを選択可能なまま保つために Form XObject として再取り込み。ブラウザプールあり	ホスト上の Chrome ランタイムと、その memory/process コスト
Office ドキュメント（`.docx`、`.xlsx`）から PDF へ	`nextpdf/gotenberg`	SSRF 対策を施し、IP を固定したトランスポートを備える、Gotenberg マイクロサービスへの PSR-18 ブリッジ	外部の Gotenberg サービスとネットワークへの依存
エッジでの HTML→PDF/ローカル Chrome 不要	`nextpdf/cloudflare`	固定したトランスポート経由の Cloudflare Browser Rendering。オプションでローカル Chrome へのフォールバックあり	Cloudflare アカウントとネットワークへの依存。フォールバックには Artisan が必要
サービスまたは AI エージェントから利用されるエンジン	`nextpdf/server`（Connect）	MCP（stdio）、REST（OpenAPI 3.1）、gRPC で公開される単一のエンジン。ソフト依存によるツール検出。高リスクのツールには人による確認ゲートあり	サービス面の運用、決定論的実行の規律

これらは 2 つの独立した判断ですが、混同されがちです。 フレームワークブリッジは、すでに使っているフレームワークによって決まります。これはエンジンがレンダリングする内容を広げたり制限したりしません。レンダラーは、ドキュメントによって決まります。決め手となる問いは、インプロセスの CSS エンジンで十分なのか、それともドキュメントが本当にブラウザレイアウトエンジンを必要とするのか、です。フレームワークブリッジは必要でレンダラーは不要、レンダラーは必要でブリッジは不要、両方とも必要、あるいはどちらも不要、というように状況はさまざまです。これらを 1 つの問いとして決めてしまうことは、最もよくある統合上の誤りであり、だからこそこのページでは分けて扱います。

根拠が示すこと

このページは編集的な内容、つまりルーティング判断です。ただしそのルーティングは、各パッケージのマニフェストとメインクラスが実際に含んでいる内容に基づいています。

これらのブリッジは実在し、互いに対応する役割を持っています。いずれも、フレームワークへの依存と自動登録を自身のcomposer.jsonで宣言しています（extra.laravel.providers、extra.symfony.bundles、CodeIgniter のRegistrar）。いずれも、PdfResponse、使い捨てドキュメントのバインディング、オプションのキュー実行ジョブも同梱しています。いずれもレンダリング機能を追加するものではなく、同じエンジンを適応させているだけです。これらのレンダラーは実在し、それぞれ異なります。Artisan はchrome-php/chromeに依存し、テキストを選択可能なまま保つために、Chrome の PDF を Form XObject として取り込み直します。Gotenberg と Cloudflare は、SSRF 対策を明示的に施し、IP を固定したトランスポートを備えた PSR-18 の HTTP ブリッジです。Cloudflare は、Worker に到達できないときに Artisan へフォールバックできます。Connect のcomposer.jsonは、3 つのトランスポートと、対応するパッケージがインストールされるとツールが利用可能になるソフト依存モデルを宣言します。これは、人による確認ゲートを伴う 4 段階のリスクモデルによって管理されます。

このページがあなたを導く方法は、形式の面で標準に裏付けられています。 Spec: ISO 24495-1:2023, §5 は、読者が、コンテンツが自分の目的にかなっているかをすばやく判断できるべきだと述べています。また、 Spec: ISO/IEC/IEEE 26514:2022, §3.x222 は、リンクと参照がその遷移先を明示することを求めています。だからこそ、この表では「ある統合」と曖昧に言うのではなく、具体的なパッケージとトレードオフを名指しで示しています。

実践的な例

この判断は、機能の比較ではなく、率直な問いの連なりです。以下は、よくあるケースを整理したものです。

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

この構造が要点です。レンダリングと呼び出しは別々の軸です。これらをまとめて答えてしまうと、チームは必要のなかったリモートレンダラーや、忠実度の問題を解決しないブリッジを抱え込むことになります。

よくある誤解

最も多い誤解は、*「PDF を生成するにはレンダラーパッケージが必要だ」*というものです。必要ありません。コアエンジンは PDF をインプロセスで生成します。レンダラーパッケージは、ブラウザ級のレイアウトエンジンが必要な場合、またはソースが Office ドキュメントである場合という特定のケースのためにのみ存在します。インプロセスエンジンがすでに正しいファイルを生成しているなら、反射的にレンダラーを採用しても、利点がないままランタイム依存と障害モードが増えるだけです。

その裏返しの誤解が、「フレームワークブリッジが機能を解放する」というものです。そうではありません。ブリッジが変えるのは、エンジンを呼び出す方法（ファサード、ファクトリ、レスポンス、キュー実行ジョブ）であって、エンジンが生成できるものではありません。署名、PDF/A、構造化インボイスは、ティアとエンジンに関わる事柄であり、ブリッジ経由で呼び出しても直接呼び出しても同じです。

制限と境界

このページはルーティングを示すものであり、ベンチマークや順位付けは行いません。 各パッケージが提供するものとトレードオフを述べるだけです。その中から選ぶことは、あなた自身の制約に基づく判断です。
パッケージの機能は、ある時点におけるマニフェストとメインクラスから読み取られたものです。 現在の API については、各パッケージ自身のドキュメントを正典として扱ってください。このガイドは地図であって、仕様書ではありません。
競合製品との比較は提示も示唆もしていません。 唯一の対象は NextPDF エコシステムと、その各部分がどのように組み合わさるかです。
フレームワークブリッジとレンダラーは独立した選択です。 ブリッジはエンジンの機能を拡張せず、レンダラーはフレームワークに依存しません。
外部レンダラーは可用性への依存を追加します。 Gotenberg と Cloudflare は、ネットワーク呼び出しと運用すべきサービスを導入します。それは受け入れたトレードオフであって、隠れたコストではありません。
ティアで制御される機能は、統合とは直交します。 商用機能を解放するのはティアであって、ブリッジやレンダラーではありません。以下の境界を参照してください。

Ecosystem packages and tiering — edition availability
Edition	Availability
Core	すべての統合パッケージ（ブリッジ、Artisan、Gotenberg、Cloudflare、 Connect）は Core に対して動作し、Apache-2.0 です。これらはエンジンを適応させる、または公開するだけであり、機能を制御するものではありません。
Pro	商用機能（PAdES ベースライン署名、PDF/A、高度なバーコード）はティアによって解放され、その後はあらゆる統合を通じて利用できるようになります。統合を切り替えることで利用可能になるわけではありません。
Enterprise	構造化インボイス、検証ポリシー、および高リスクのツールに対する Connect の人による確認ゲートはティア機能であり、同様に統合には依存しません。

用語集

コアエンジン — nextpdf/core。他のすべてのパッケージの基盤となる、インプロセスの PDF 2.0 エンジン。
フレームワークブリッジ — エンジンの機能を変えることなく、エンジンをフレームワークの流儀に適応させる統合パッケージ（Laravel/Symfony/CodeIgniter）。
レンダラーパッケージ — インプロセスエンジンが適切なツールでない場合に、HTML または Office のレイアウトを外部エンジン（Artisan/Cloudflare/Gotenberg）に委譲するパッケージ。
Form XObject — 再利用可能な PDF コンテンツの断片。Artisan は、テキストを選択可能なまま保つために、ブラウザでレンダリングしたページをこれとして取り込みます。
NextPDF Connect — nextpdf/server。決定論的な実行面を備え、エンジンを MCP、REST、gRPC 経由で公開するパッケージ。
ソフト依存 — オプションの NextPDF パッケージがインストールされるにつれ、コードを変更することなくツールが自動的に現れる Connect のモデル。