Pro 版本

Projection

速览

Projection 将一个 PDF 内容流解析为一个扁平的 token 列表，并从这些 token 发出一个新的内容流。发出操作需要一个显式声明的意图。本模块不是一个通用 PDF 编辑器。

注意。 此处的“Projection”指的是内容流 token 投影。它不是坐标或地理空间投影。关于地理空间功能，请参阅 Geo 模块。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）一同发行，并通过一个 Pro 层级的授权信封激活。一个不具备该权利的部署不会加载此能力的类。比较各版本并获取授权。

不存在单独的逐功能授权标记。一个必需的 ProjectionIntent 参数在 API 层面限制发出操作，而非一个授权开关。

安装

composer require nextpdf/pro:^3

代码位于 NextPDF\Pro\Projection 命名空间下。

概念概述

ContentProjectionWriter 提供三个静态操作：

tokenize() 将一个内容流解析为一个扁平、有序的 token 列表。这是只读的，无需意图。
emit() 从一个（可能已修改的）token 列表写出一个新的内容流。它需要一个 ProjectionIntent。
roundTrip() 先 tokenize 再无改动地重新 emit，用于校验。

输出在概念上是一个新的内容流，而非原始内容的一份已编辑副本。发出器会归一化空白与注释，但保持运算符序列与操作数值精确不变。意图枚举恰好有两种情形 —— 净化（遮蔽）与隐写嵌入 —— 并有意不设通用情形，以便静态分析能检测出非预期的用法。

为何如此设计

Projection 拒绝成为一个通用 PDF 编辑器。发出操作会从一个扁平的 token 列表重建出一个全新的内容流，因此原始内容绝不会被就地改动。正是这种单向模型让遮蔽值得信赖：被移除的 token 是从输出中缺失，而非被涂盖。因此 emit() 要求一个显式的 ProjectionIntent，而该枚举只提供净化与隐写嵌入 —— 没有通用情形。这样，静态分析便能标记出任何缺少已声明、已知目的的发出操作。此设计以牺牲编辑便利为代价，换来一项保证：破坏性意图在调用点始终可见。

设计背景：遮蔽不是一个黑色矩形。

行为契约

tokenize($contentStream) 返回一个 token 列表，涵盖字符串、名称、数字、数组、字典、布尔值、null 与运算符。
emit($tokens, $intent) 需要一个显式意图；类型系统在调用点强制这一点。
roundTrip() 的输出与输入并非字节相同，但运算符序列与操作数值相符。
发出器对数字进行格式化以保持整数与浮点的区分，并对字面字符串重新转义。
两个声明的意图是净化（一项破坏性的、不可逆的遮蔽操作）与隐写嵌入。

代码示例 —— 快速上手

以下反映已记录的公共 API。该仓库未为本模块发行可运行示例。

use NextPDF\Pro\Projection\ContentProjectionWriter;

$tokens = ContentProjectionWriter::tokenize($contentStream);

代码示例 —— 生产环境

use NextPDF\Pro\Projection\ContentProjectionWriter;
use NextPDF\Pro\Projection\ProjectionIntent;

$tokens = ContentProjectionWriter::tokenize($contentStream);

// Validate first: a clean round-trip must hold before any modification.
$check = ContentProjectionWriter::roundTrip($contentStream);

// Apply your modification to $tokens, then emit with a declared intent.
$output = ContentProjectionWriter::emit($tokens, ProjectionIntent::Sanitization);

边界情况与注意事项

在你信任一个修改并发出的序列之前，先运行 roundTrip() 并确认它成立。请将一次失败的 round-trip 视为一个停止条件。
净化意图是不可逆的。被移除的内容无法从输出中恢复。
发出器会归一化空白并丢弃注释，因此即便是一次未修改的 round-trip，与原始内容做字节级比较也会有差异。

性能

tokenize 与 emit 与内容流长度呈线性关系。tokenizer 会限定八进制转义读取与十六进制字符串处理。没有公布的吞吐量数字。请用有代表性的内容流来度量。

安全说明

必需的意图参数防止它被滥用为一个通用编辑器。净化意图是破坏性且不可逆的；请先校验 round-trip，并在分发前确认已遮蔽的输出。本模块不记录任何内容。

一致性

Tokenization 遵循 ISO 32000-2 中的词法与内容流约定；来源标注了相关条款。撰写时 RAG 语料库不可用，因此本页面不断言任何外部条款标识符，并将一致性陈述限定在由该模块测试验证的行为之内。

Enterprise 边界说明

Enterprise 不改变 Projection 的行为。Enterprise 增加的是另行记录的更高层级隐私与合规功能；它们对使用投影 API 并非必需。

Core 回退/替代方案

没有 Core 层级的对等物。没有 Pro 时，调用方必须自行构建内容流 tokenizer；受意图限制的投影模型是一项 Pro 独有的新增能力。

发布边界

本页面仅描述可从外部观察到的行为以及受支持的公共 API 接口面。内部命名空间路径、辅助类、机制表、runbook 文件名与工单前缀均不在范围之内。