NextPDF Artisan の概要

概要

NextPDF Artisan は、NextPDF 向けの Chrome ブリッジです。HTML フラグメントを Chrome DevTools Protocol 経由でヘッドレス Chrome プロセスに送信し、printToPDF の出力を取得して、その結果を Form XObject として対象ドキュメントに埋め込みます。埋め込まれたテキストは、選択可能かつ検索可能な状態で保持されます。

概念の概要

Artisan パッケージ（nextpdf/artisan）は、レイアウトを Chrome に委譲するレンダラーによって、オープンソースの NextPDF エンジンを拡張します。NextPDF のネイティブ HTML パイプラインは、すでに広範な CSS サブセットをカバーしています。Artisan ブリッジは、Chrome 相当のレイアウト（CSS の flexbox やグリッド、data URI から読み込まれるカスタム Web フォント、複雑なセレクター）を必要とするドキュメント向けに用意されており、ラスタライズされたスクリーンショットではなくベクターテキストを生成します。

このブリッジは、単一の目的を持つ小さなコンポーネントで構成されたパイプラインです。ChromeHtmlRenderer はレンダリングを統括します。ChromeSecurityPolicy は入力を検証し、それを厳格に制限された HTML ドキュメントでラップします。BrowserPool は Chrome プロセスのライフサイクルを管理します。ViewportCalculator は PDF のポイントを CSS ピクセルにマッピングします。NextPDF\Parser リーダーが Chrome の出力を解析し、PageImporter がそれを Form XObject に変換します。各コンポーネントは final で宣言され、コンストラクター注入され、PHPStan レベル 10 で型付けされています。

このブリッジは 外部依存に制約されます。chrome-php/chrome ライブラリ（^1.15）と、PHP プロセスから到達可能な Chrome または Chromium バイナリが必要です。どちらも同梱されていません。ライブラリが存在しない場合、ブリッジは黙って機能を低下させるのではなく、ChromeNotAvailableException をスローします。/integrations/artisan/troubleshooting/ ページの /integrations/artisan/failure-modes/ を参照してください。

入力が ChromeSecurityPolicy::validate() を通過するまで、レンダリングが Chrome に到達することはありません。また、Chrome が受け取るドキュメントは、常に厳格な Content-Security-Policy と多層防御の CDP ネットワークブロックでラップされています。このブリッジは信頼できない可能性のある HTML を処理するため、その転送と分離に関する方針は、ここで要約せず、/integrations/artisan/security-and-operations/ ページで明示的に文書化しています。

これは、出荷されたパッケージで観測された動作であり、src/Artisan/ および tests/Unit/Artisan/ スイートに対して検証されています。インタラクティブな Chrome ブラウザーとのピクセル単位の一致を主張するものではありません。アニメーションは最終フレームでキャプチャされ、レイアウトは JavaScript に依存せず、Chrome の最初のページのみがインポートされます。

アーキテクチャ

Diagram

コンポーネントの責務

コンポーネント	責務	ソース
`ChromeHtmlRenderer`	単一レンダリングの統括と `ChromeRenderResult` の返却	`src/Artisan/ChromeHtmlRenderer.php`
`ChromeRendererConfig`	イミュータブルな構成値オブジェクト	`src/Artisan/ChromeRendererConfig.php`
`ChromeSecurityPolicy`	入力検証 + 安全な HTML エンベロープ	`src/Artisan/ChromeSecurityPolicy.php`
`BrowserPool`	Chrome プロセスのライフサイクルと再起動ポリシー	`src/Artisan/BrowserPool.php`
`ViewportCalculator`	72 pt/inch ↔ 96 px/inch の変換	`src/Artisan/ViewportCalculator.php`
`ChromeRenderResult`	型付けされたレンダリング出力（`ChromeRenderResultInterface`）	`src/Artisan/ChromeRenderResult.php`
`PageImporter`	解析された Chrome ページ → `ImportedFormXObject`	`src/Artisan/PageImporter.php`
`EInvoiceServiceFactory`	Premium の電子請求書コントラクト向けコンテナーレスファクトリー	`src/Artisan/EInvoiceServiceFactory.php`

エッジケースと注意点

バージョンの系譜。 公開されている Composer アーティファクトには v0.1.0 のタグが付けられています。ソースの docblock には @since 1.7.0（Chrome ブリッジ）と @since 1.1.0（電子請求書ファクトリー）が記載されており、いずれもリネーム前の nextpdf/core のバージョン系列から継承されています。このパッケージは nextpdf/artisan にリネームされ、その変更は 2.0.0 の CHANGELOG エントリで行われました。Composer のタグを正規のインストールバージョンとして扱い、@since マーカーはエンジンバージョンの由来として扱ってください。
最初のページのみ。 PageImporter::import() は、デフォルトでページインデックス 0 を使用します。Chrome の 2 ページ目にはみ出したコンテンツは、明示的な高さが指定されていない限りクリップされます。詳細は /integrations/artisan/production-usage/ ページで説明しています。
DI コンテナーなし。 Artisan はコンテナーレスです。EInvoiceServiceFactory は、サービスコンテナーを持たない環境でも一貫してインスタンス化できる手段を提供します。詳細は /integrations/artisan/boot-and-discovery/. を参照してください。

パフォーマンス

各レンダリングでは、呼び出しごとに 1 回、Chrome のページ読み込みと printToPDF のコストが発生します。BrowserPool はレンダリング間も Chrome プロセスを存続させ、メモリ増加を抑えるために 100 回のレンダリングごとに再起動します。Big-O を支配するのは、ブリッジ自体ではなく、Chrome による入力のレイアウトです。このページのリファレンスフローで計測された予算については、フロントマターの performance_budget と /integrations/artisan/production-usage/ ページを参照してください。

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

このブリッジは、信頼できない可能性のある HTML を Chrome 内でレンダリングします。入力は、Chrome が受け取る前にサイズとコンテンツを検証されます。ラップされたドキュメントには default-src 'none' が付与されます。CDP レベルのブロックにより、すべてのサブリソースリクエストが停止されます。Chrome のサンドボックスフラグに対する明示的な制限を含め、転送と分離の完全なモデルは /integrations/artisan/security-and-operations/ ページにあります。このセクションを完全なセキュリティ体制として扱わないでください。

商用面の背景

オープンソースのブリッジは、HTML を PDF にレンダリングします。Premium ティアは、レンダリング済みドキュメントの上に、準拠した電子請求書の埋め込み（Pro）と検証（Enterprise）を重ねて提供します。これらのティアがインストールされていない場合、EInvoiceServiceFactory は null を返すため、オープンソース側の処理経路はそれらがなくても完全に機能し続けます。