コンテンツにスキップ
NextPDF

Artisan 開発者ガイド

概要

「概要」という見出しのセクション

Artisan パッケージには、相互に関連する 2 つの役割があります。Chrome で HTML をレンダリングすることと、生成された PDF ページを NextPDF ドキュメントにインポートすることです。デバッグ時は、Chrome、パーサー、インポーターの各境界を個別に扱ってください。

レンダラーの統合、長時間稼働するワーカー、パーサーの診断、または nextpdf/artisan 周辺のテスト作成に取り組む際は、このガイドを参照してください。

アーキテクチャの境界

「アーキテクチャの境界」という見出しのセクション
レイヤー所有者責務ここに置かないもの
アプリケーションアプリケーションHTML 生成の承認、レンダラー構成の選択。ブラウザープロセスの管理。
HTML ポリシーアプリケーションとパッケージレンダリング前の、安全でない HTML やサイズ超過 HTML の拒否。テナント承認やビジネス上の判断。
Chrome レンダラーnextpdf/artisanHTML から、Chrome が生成する単独 PDF へのレンダリング。一般的な PDF 修復や任意の PDF 編集。
パーサー/インポーターnextpdf/artisanレンダリング済み PDF の解析、および 1 ページのフォーム XObject としてのインポート。完全な PDF 適合性検証。
コアエンジンnextpdf/nextpdfインポート済みフォームオブジェクトの配置、最終ドキュメントの書き出し。Chrome CDP のライフサイクル。

ランタイムのライフサイクル

「ランタイムのライフサイクル」という見出しのセクション
ステージ動作開発者のアクション
構成の作成ChromeRendererConfig による、バイナリ、タイムアウト、CSS、入力サイズ、サンドボックス動作の定義。ハードコードされたランタイム推測ではなく、環境固有の構成の使用。
レンダラーの作成ChromeHtmlRenderer による BrowserPool の所有。ワーカー内でのレンダラー再利用、シャットダウン時のクローズ。
HTML の検証セキュリティポリシーによるサイズチェックと、デフォルト CSS でのドキュメントのラップ。このステージ前の、呼び出し元の承認検証。
Chrome での印刷CDP による単独 PDF のレンダリング。レビュー済みのポリシーで許可されない限り、外部リソースのブロック維持。
PDF の解析PdfReader::parse() による、xref データ、ページ、オブジェクト、リソース、リビジョンの読み取り。診断目的でない限り、パーサー失敗のレンダリング失敗としての扱い。
ページのインポートPageImporter::import() による、ページのコンテンツ、メディアボックス、リソース、埋め込みオブジェクトの抽出。ワークフローが意図的に別のページを選択する場合を除く、ページ 0 のインポート。

推奨されるアプリケーション構造

「推奨されるアプリケーション構造」という見出しのセクション
パス目的
app/Pdf/Renderers/*アプリケーション側ラッパーによる ChromeHtmlRenderer のラップ。
app/Pdf/Templates/*HTML テンプレートのレンダリング、DTO からビューへのマッピング。
app/Pdf/Policies/*HTML サイズ、リソース、テナントのレンダリングポリシー。
tests/Pdf/Renderer/*小さな HTML フィクスチャを使ったレンダラーのスモークテスト。
tests/Pdf/Parser/*インポートされた Chrome 出力用のパーサーフィクスチャ。

テンプレートのレンダリングは、ブラウザーのレンダリングとは切り離してください。レンダラーには、最終的な HTML と既知のページ幅を渡す必要があります。

<?php


use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;


$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(
    renderTimeout: 30,
    maxHtmlSize: 1_000_000,
));


$result = $renderer->render($html, widthPt: 595.28);


$reader = new PdfReader($result->getPdfData());
$reader->parse();


$form = (new PageImporter())->import($reader);

レンダラーのパターン

「レンダラーのパターン」という見出しのセクション

ワーカープロセスごと、またはリクエストスコープごとに、レンダラーを 1 つ作成してください。レンダラーを再利用すると、Chrome 起動コストの繰り返しを避けられます。明示的にクローズすれば、ワーカーのシャットダウン時にプロセスがリークするのを防げます。

<?php


final class InvoiceChromeRenderer
{
    public function __construct(
        private readonly ChromeHtmlRenderer $renderer,
    ) {}


    public function renderInvoice(string $html): string
    {
        return $this->renderer
            ->render($html, widthPt: 595.28)
            ->getPdfData();
    }


    public function close(): void
    {
        $this->renderer->close();
    }
}

パーサー診断のパターン

「パーサー診断のパターン」という見出しのセクション

パーサー API は、Chrome 出力のインポートが失敗した場合に役立ちます。診断は読み取り専用にとどめ、インポートが成功した後はパーサーの状態を変更しないでください。

診断の問い使用する API期待されるシグナル
ファイルの解析可否。PdfReader::parse()無効な PDF 構造の場合の例外。
ページ 0 の存在有無。PdfReader::getPage(0)返り値としての PdfObject。
コンテンツの有無。PdfReader::getPageContentStream($page)空でないコンテンツストリーム。
リソースの存在有無。PdfReader::getPageResources($page)リソース辞書の配列。
増分リビジョンの有無。PdfReader::getRevisionCount()1 より大きいカウント。
失敗したオブジェクトの特定。PdfTokenizer::getOffset() とパーサー例外のコンテキスト。フィクスチャ縮小用のバイトオフセット。

拡張ポイント

「拡張ポイント」という見出しのセクション
拡張ポイント用途制約
ChromeRendererConfig::fromArray()フレームワーク構成のマッピング。不明な値や型が誤ったオプション値の、デフォルトへのフォールバック。
HtmlSecurityPolicyInterface解析レイヤーの HTML ポリシー。トランスポート、プロセス、承認の制御の代替ではないこと。
LoggerInterfaceレンダリングとブラウザーの診断。デフォルトでは HTML コンテンツをログに記録しないこと。
BrowserPool長時間稼働する Chrome プロセスの再利用。ワーカーのシャットダウン時のクローズ必須。
PageImporter解析済み外部ページの埋め込み。事前のリーダー解析が必要。
パーサークラス診断、およびインポートされた Chrome 出力。一般的な PDF 修復ツールキットではないこと。

開発ワークフロー

「開発ワークフロー」という見出しのセクション
  1. HTML フラグメントを、最小限のレンダリングテストとして再現します。
  2. 次の項目を検証します。maxHtmlSize、デフォルト CSS、Chrome バイナリのパス。
  3. ポイント単位の固定幅でレンダリングします。
  4. 返された PDF バイトを PdfReader::parse() で解析します。
  5. ワークフローが意図的に別のページを選択する場合を除き、ページ 0 をインポートします。
  6. 各失敗を再現できる最小の HTML に対して、フィクスチャテストを追加します。
  7. ワーカーのシャットダウンフックでレンダラーをクローズします。

失敗の処理

「失敗の処理」という見出しのセクション
失敗処理すべき場所推奨される対応
Chrome バイナリが見つからないデプロイ時チェックと、レンダラーの構築パス。レンダリングトラフィック受け入れ前の readiness 失敗。
サイズ超過の HTMLHTML ポリシー。Chrome 起動前の拒否。
ブラウザーのタイムアウトレンダラーの境界。レンダリングの失敗化、およびテンプレート名、サイズ、幅、タイムアウトの記録。
パーサーの失敗インポートの境界。ポリシーで許可される場合の、デバッグ用の小さなサニタイズ済みフィクスチャの保存。
ブラウザープロセスのリークワーカーのライフサイクル。シャットダウン時のクローズ、および制御されたレンダリング回数後の再起動。

安全なデフォルト

「安全なデフォルト」という見出しのセクション
関心事デフォルトオーバーライドするタイミング
レンダリングのタイムアウト30 秒。計測済みで範囲が限定されたドキュメントの場合のみ増加。
HTML の最大サイズ5,000,000 バイト。パブリックエンドポイントでの低減。
サンドボックス有効。コンテナーの制約上必要であり、かつホストが分離されている場合にのみ無効化。
高さ自動化条件は heightPt <= 0。厳密なレイアウト契約での固定高さの使用。
外部リソースレンダラーポリシーによるブロック。レビュー済みリソースポリシー経由でのみ許可。

テストのチェックリスト

「テストのチェックリスト」という見出しのセクション
  • レンダリングテストでは、代表的な HTML と CSS をカバーします。
  • セキュリティテストでは、サイズ超過の HTML と、ブロックされたリソースへのアクセス試行をカバーします。
  • インポートテストでは、返されたフォームオブジェクトにコンテンツ、メディアボックス、リソースがあることをアサートします。
  • パーサーテストでは、xref テーブル、xref ストリーム、オブジェクトストリーム、不正な形式のフィクスチャのケースをカバーします。
  • ワーカーテストでは close() を呼び出し、ブラウザープロセスが残っていないことを検証します。
  • パフォーマンステストでは、テンプレートおよびコンテンツサイズごとのレンダリング時間を記録します。