Pro エディション

AST

概要

AST モジュールは、PDF をイミュータブルでナビゲート可能なドキュメントツリーに変換します。タグ付き構造ツリーが存在する場合はそれを使用し、タグなしドキュメントに対してはヒューリスティックなビルダーにフォールバックして、各ノードにバウンディングボックスとテキストを付与します。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）に同梱され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得。

機能ごとのライセンスフラグは存在しません。コードは Pro エディションに同梱されており、ビルドの挙動はライセンススイッチではなく、AstBuildOptions（リソース制限とページ範囲）によって完全に管理されます。

インストール

composer require nextpdf/pro:^3

コードは NextPDF\Pro\Ast 名前空間の下に存在します。

概念の概要

AstBuilder は、PDF からツリーへのパイプラインをオーケストレーションします。キャッシュをチェックし、暗号化された入力を早期に拒否し、タグ付き PDF の構造ツリーを読み取り、それ以外の場合はタグなしパスにフォールバックし、コンテンツストリーム解析からバウンディングボックスを付与し、結果をキャッシュします。出力は AstDocument であり、そのノードはイミュータブルです。更新は、その場で変更するのではなく、影響を受けるサブツリーをボトムアップで再構築します。

タグなし PDF に対しては、2 つのフォールバックストラテジーが存在します。ベアフォールバックと、オプションのヒューリスティックビルダー（AstBuildOptions::$useHeuristic）です。このモジュールは、AST を PDF に書き戻して結果を検証できるエミッターパスと、ツリーに適用された変更を追跡するためのミューテーションログも提供します。

なぜこの仕組みなのか

ツリーは構造上イミュータブルです。各編集は、影響を受けるルートからノードまでのパスのみを再構築し、変更されないサブツリーを同一性で共有します。そのため、構築済みの AstDocument は、防御的コピーなしで保持、キャッシュ、そして並行リーダーへの受け渡しを安全に行えます。これは、PDF そのものがディスク上で変化する方法を反映しています。書き戻しパスは、ファイルを書き換えるのではなく、AstWriter を通じて増分更新を追記し、元のバイト列（および既存の署名）をそのまま残します。追記のみのリビジョンは構造的に検証するコストも低く、これが AstWriter が返す前に自身の出力をチェックできる理由です。その場で変更するのではなくサブツリーを再構築することが、このモジュールをナビゲート可能かつ安全に編集可能なものにする唯一の決定です。

設計背景：増分更新とそれが重要な理由。

挙動コントラクト

AstBuilder::build($sourceHash) は、ソース PDF の完全な SHA-256 16 進数を受け取り、AstDocument を返します。
暗号化された PDF は、専用の非サポート暗号化エラーで拒否されます。構築する前に復号してください。
構造ツリーが存在しない場合、ビルダーは自動的にタグなしパスを使用します。有効な場合はヒューリスティック、そうでない場合はベアフォールバックです。
AstBuildOptions のリソース制限（最大ノード数、最大深度、最大メモリ、ウォールクロックタイムアウト）は、無制限の処理ではなく、ビルド制限エラーまたはビルドタイムアウトエラーを引き起こします。
キャッシュキーは、ソースハッシュとオプションハッシュを組み込みます。そのため、入力とオプションが同一の 2 回のビルドは、同じツリーを返します。
AstNode はイミュータブルです。ツリーが変化すると、コンシューマーは新しいノードインスタンスを受け取ります。

コードサンプル — クイックスタート

以下は、文書化されたパブリック API を反映しています。リポジトリは、このモジュールに対して実行可能な例を同梱していません。

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$builder = new AstBuilder($pdfReader, new AstBuildOptions());
$document = $builder->build($sha256OfPdf);

コードサンプル — 本番

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$options = new AstBuildOptions(
    maxNodes: 100_000,
    maxDepth: 200,
    maxMemoryBytes: 256 * 1024 * 1024,
    timeoutSeconds: 30.0,
    useHeuristic: true,
);

$builder = new AstBuilder($pdfReader, $options, $astCache);

try {
    $document = $builder->build($sha256OfPdf);
} catch (\NextPDF\Pro\Ast\Exception\AstUnsupportedEncryptionException $e) {
    // Decrypt the source first, then retry.
}

エッジケースと注意点

コンテンツストリームを解析できないページは、バウンディングボックスの付与中にスキップされます。ツリーは依然として返されますが、それらのページにはボックスがありません。
ヒューリスティックビルダーはオプトインです。無効にした場合、タグなし PDF はベアフォールバックからより粗いツリーを生み出します。
AstBuildOptions のページ範囲は、0 ベースの包含的インデックスを使用します。両方の境界を null のままにすると、すべてのページを処理します。

パフォーマンス

ビルドのコストは、ノード数とページ数に応じて増減します。AstBuildOptions は両方の上限を定めます。キャッシュは、同じオプションでの同じ入力の繰り返しビルドを短絡します。NextPDF はここでドキュメントごとの固定タイミングを公開しません。ウォールクロックタイムアウト（デフォルト 30 秒）とノード上限（デフォルト 100,000）が、最悪ケースの処理の上限を定めます。代表的なドキュメントで測定してください。

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

入力を信頼できないものとして扱ってください。ビルダーは、暗号化された PDF を部分的に処理するのではなく、拒否します。リソース上限（ノード、深度、メモリ、時間）は、病的または敵対的なドキュメントから保護します。このモジュールはドキュメントコンテンツをログに記録しません。

適合性

構造ツリーパスは、ISO 32000-2 で定義されたタグ付き PDF 構造を読み取ります。モジュールのソースは、関連するコンテンツストリームおよび構造の条項に注釈を付けています。執筆時点で RAG コーパスが利用できなかったため、このページは外部の条項識別子を一切主張せず、適合性の記述をモジュールのテストによって検証された挙動に限定します。

Enterprise の境界に関する注記

Enterprise は AST の挙動を変更しません。Enterprise は、別途文書化されている、より上位ティアのコンプライアンスとアーカイブのケイパビリティを追加します。それらは AST を構築または消費するために必要ではありません。

Core のフォールバック/代替手段

Pro がない場合、同等のドキュメントツリーはありません。呼び出し元は、NextPDF Core プリミティブを使用してコンテンツストリームを直接解析します。/modules/ast/ を参照してください。

公開の境界

このページは、外部から観測可能な挙動と、サポートされているパブリック API サーフェスのみを記述しています。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケットのプレフィックスは対象外です。