Pro 版本

AST

速覽

AST 模組將一份 PDF 轉換為一棵不可變、可導覽的文件樹。它在標記結構樹存在時使用它，並對未標記的文件回退到一個啟發式建構器，為每個節點附上邊界框與文字。

供應與授權

此能力隨附於 NextPDF Pro（nextpdf/pro），並以一份 Pro 層級授權封套啟用。沒有該授權資格的部署不會載入此能力的類別。比較版本並取得授權。

不存在逐功能的授權旗標。程式碼隨 Pro 版本一同交付；建構行為完全由 AstBuildOptions（資源限制與頁面範圍）治理，而非一個授權開關。

安裝

composer require nextpdf/pro:^3

程式碼位於 NextPDF\Pro\Ast 命名空間之下。

概念總覽

AstBuilder 協調 PDF 轉樹的管線：檢查快取、提早拒絕加密輸入、為標記 PDF 讀取結構樹、否則回退到未標記路徑、從內容串流分析附上邊界框，然後快取結果。輸出是一個 AstDocument，其節點不可變；更新會由下而上重建受影響的子樹，而非就地變更。

未標記 PDF 有兩種回退策略：一個簡略回退，以及一個選用的啟發式建構器（AstBuildOptions::$useHeuristic）。本模組也提供一條 emitter 路徑，可將一個 AST 寫回 PDF 並驗證結果，加上一個用以追蹤套用於樹之變更的變更日誌。

為何以此方式運作

這棵樹在建構上即為不可變。每次編輯只重建受影響的根到節點路徑，並以識別共享未觸及的子樹，因此一份建好的 AstDocument 可安全地持有、快取，並交給並行的讀取者而不需防禦性複製。這映照了 PDF 本身在磁碟上如何變更：寫回路徑透過 AstWriter 附加一次增量更新，而非重寫檔案，讓原始位元組——以及任何既有的簽章——維持完好。一次僅附加的修訂在結構上也易於驗證，這正是 AstWriter 能在回傳前檢查自身輸出的原因。重建子樹而非就地變更，是使本模組既可導覽又可安全編輯的那一個決策。

設計背景：增量更新以及它們為何重要。

行為合約

AstBuilder::build($sourceHash) 接受來源 PDF 的完整 SHA-256 十六進位，並回傳一個 AstDocument。
加密的 PDF 會以一個專用的不支援加密錯誤被拒絕；請在建構前先解密。
當沒有結構樹存在時，建構器會自動使用未標記路徑——啟用時為啟發式，否則為簡略回退。
AstBuildOptions 中的資源限制（最大節點數、最大深度、最大記憶體、牆鐘逾時）會導致一個建構限制或建構逾時錯誤，而非無界的工作。
快取鍵納入來源雜湊與選項雜湊，因此兩次以相同輸入與選項的建構會回傳相同的樹。
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 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名與工單前綴皆不在範圍內。