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）。该模块还提供一条写出器路径，可把一个 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 s）与节点上限（默认 100,000）限制最坏情况下的工作。请用有代表性的文件测量。

安全说明

请把输入视为不可信。构建器拒绝加密的 PDF，而非对其做部分处理。资源上限（节点、深度、内存、时间）防范病态或有敌意的文件。本模块不记录任何文件内容。

符合性

结构树路径读取由 ISO 32000-2 定义的带标签 PDF 结构；该模块的源代码标注了相关的内容流与结构条款。由于著作时 RAG 语料库不可用，本页不断言任何外部条款标识符，并将符合性陈述限定在由该模块测试验证过的行为上。

Enterprise 边界说明

Enterprise 不改变 AST 行为。Enterprise 增加了单独记录的更高层级合规与归档能力；构建或消费一个 AST 不需要它们。

Core 回退 / 替代

在没有 Pro 的情况下，没有等价的文档树；调用方使用 NextPDF Core 原语直接解析内容流。参见 /modules/ast/。

发布边界

本页仅记录外部可观察行为与受支持的公开 API 表面。内部命名空间路径、辅助类、机制表、runbook 文件名与工单前缀不在范围内。