Filter — 深度参考

速览

本页是 NextPDF Pro Filter 模块（命名空间 NextPDF\Pro\Filter）的契约级参考。其接口面由两个类组成。DecodeParms 将 PDF /DecodeParms 字典片段解析为一个不可变、经边界校验的值对象。PngPredictor 在经 FlateDecode 解码的流字节上逆向 PNG 预测器族（标记 10-15）。本模块服务于 Pro Diff 与 Classifier 提取器，而非通用的流过滤框架。本页阐明公共 API、可观测的行为契约，以及带类型的失败模式。用法指南与代码示例见 Filter 能力页。

可用性与授权

本能力随 NextPDF Pro（nextpdf/pro）一同发布，并在 Pro 级授权凭据下激活。不具备该权限的部署不会加载本能力的类。比较版本并获取授权。

没有任何运行时能力标记对本模块进行门控。只要安装了 nextpdf/pro，Filter 类即可用。

公共 API 接口面

符号	参数	默认行为	返回	抛出或失败于	说明
DecodeParms	构造函数：int $predictor = 1、int $columns = 1、int $colors = 1、int $bitsPerComponent = 8	默认值表示“无预测器”	—	—	final readonly；四个属性均为 public 且不可变
DecodeParms::fromDictionary()	string $raw——原始字典文本，容许周围的对象体	缺失的键保留其默认值；匹配容许空白	self	InvalidArgumentException	解析期的关卡；边界见行为契约
DecodeParms::isPngPredictor()	无	纯谓词；无 I/O	bool——预测器 10-15 时为 true	—	在调用逆向过滤器前据此分支
PngPredictor	—	无状态	—	—	final；唯一入口是静态方法 inverse()
PngPredictor::inverse()	string $raw、int $columns、int $colors、int $bitsPerComponent、int $predictor	依逐行标记逐行逆向过滤；空输入返回空字符串	string——已剥除过滤标记的重建有效载荷	InvalidArgumentException	仅接受预测器 10-15；TIFF 预测器不在范围内

入口点签名

public function __construct(
    public int $predictor = 1,
    public int $columns = 1,
    public int $colors = 1,
    public int $bitsPerComponent = 8,
) {}

public static function fromDictionary(string $raw): self

public function isPngPredictor(): bool

public static function inverse(
    string $raw,
    int $columns,
    int $colors,
    int $bitsPerComponent,
    int $predictor,
): string

行为契约

/DecodeParms 解析

DecodeParms::fromDictionary() 在原始字典文本中将四个可识别的键作为整数匹配：/Predictor、/Columns、/Colors 与 /BitsPerComponent。这些是 ISO 32000-2:2020 §7.4.4.4 为 LZWDecode 与 FlateDecode 过滤器定义的预测器参数。匹配容许空白，并能在周围的 PDF 记号中存续。缺失的键保留其默认值：predictor 为 1、columns 为 1、colors 为 1、bits-per-component 为 8。存在的值会在解析期以失败即关闭的方式校验，早于任何几何参数抵达逆向过滤器的行分配：

• 任何可识别键上存在的负值都会被拒绝。
• 大于 1,000,000 的 /Columns 会被拒绝。
• 大于 32 的 /Colors 会被拒绝。
• 不在 {1, 2, 4, 8, 16} 内的 /BitsPerComponent 会被拒绝。
• 推导出的行跨距大于 64,000,000 字节会被拒绝。

当解析出的预测器为 10 至 15 时，isPngPredictor() 返回 true。预测器 1（无预测）与预测器 2（TIFF 组）返回 false。

行几何

PngPredictor::inverse() 消费一个经 FlateDecode 解码的字节流，其中每一行前面都有一个一字节的过滤标记。它发出已剥除标记的重建有效载荷。行有效载荷宽度为 ceil(columns * colors * bitsPerComponent / 8) 字节；行跨距再加一个标记字节。左邻偏移（每像素字节数）为 max(1, floor(colors * bitsPerComponent / 8))，因此亚字节打包会向下取整为一个字节。无论位深如何，过滤都在整字节上进行，与 PNG 过滤语义一致。

逐行重建

标记	过滤器	重建
0	None	直通
1	Sub	recon[x] = filt[x] + recon[x-bpp]
2	Up	recon[x] = filt[x] + prior[x]
3	Average	recon[x] = filt[x] + floor((recon[x-bpp] + prior[x]) / 2)
4	Paeth	recon[x] = filt[x] + Paeth(left, up, up-left)

所有求和均对 256 取模。对于第一行，以及第一个像素左侧的字节，缺失的邻居按零读取，依照 W3C PNG §9.2。逆向操作完全由逐行标记驱动。依照 ISO 32000-2:2020 §7.4.4.4，这对固定预测器（10-14）与 Optimum（15）都是符合规范的行为，因此容许写入器的标记差异。

校验分层

参数校验按设计分两层运行。DecodeParms 是解析期的关卡，率先拒绝恶意的量级。PngPredictor::inverse() 保留自身的检查作为第二层：对全部四个参数的范围检查、在构成跨距乘积前将各个因子与 PHP_INT_MAX 比较的溢出防护、同样的 64,000,000 字节逐行上限，以及一个与输入成比例的边界——在分配任何行缓冲区之前，拒绝声明的跨距大于整个输入的情形。

确定性

两个入口点都是其输入的纯静态函数。没有 I/O、没有日志、也没有全局状态。运行时间随输入长度线性增长，每字节常数很小。/DecodeParms 解析是若干个有界的正则表达式匹配。预算在 frontmatter 的 performance_budget 中给出。

边界情形与失败模式

本模块中的每一次失败都会抛出 InvalidArgumentException，并在消息中指明发生问题的值。

• fromDictionary() 拒绝任何可识别键上存在的负值。
• fromDictionary() 拒绝大于 1,000,000 的 /Columns 与大于 32 的 /Colors。
• fromDictionary() 拒绝不在 {1, 2, 4, 8, 16} 内的 /BitsPerComponent，以及推导出的大于 64,000,000 字节的行跨距。
• inverse() 拒绝 10-15 以外的预测器。TIFF 预测器（2）在此从不被逆向过滤；请先据 isPngPredictor() 分支。
• inverse() 拒绝小于 1 的 columns 或 colors，以及不在合法集合内的 bitsPerComponent。
• inverse() 在任何分配之前，拒绝跨距乘积会溢出平台整数的几何参数。
• inverse() 拒绝超过 64,000,000 字节逐行上限的行跨距，与实际输入长度无关。
• inverse() 对空输入返回空字符串；这不是错误。
• inverse() 会将声明的大于整个输入的行跨距，作为偏移 0 处的截断行而失败。
• inverse() 会将末尾的部分行作为截断行而失败，并指明偏移与字节数。
• inverse() 会对未知的逐行过滤标记（非 0-4）失败，并附上标记值与行偏移。
• 声明的 /DecodeParms 几何参数与实际流布局之间的不匹配，会表现为参数错误或截断错误，绝不会表现为静默损坏的输出。
• Average 过滤器使用整数除法，与 PNG 规范的 floor 语义一致。
• 本模块不发生任何密码学操作。在受 FIPS 约束的部署中行为相同。

一致性

声明	标准	条款
/Predictor 过滤器参数选定预测器算法；允许的取值来自预测器取值表。	ISO 32000-2:2020	§7.4.4.4
PDF 定义两个预测器组：TIFF 组是单一的 Predictor 2 函数；PNG 组是标记 10-15。	ISO 32000-2:2020	§7.4.4.4
/BitsPerComponent 的合法取值为 1、2、4、8 与 16，默认值为 8；/Colors 为 1 或更大，默认值为 1；/Columns 默认值为 1。	ISO 32000-2:2020	§7.4.4.4
过滤类型 0-4 的重建函数按整字节对 256 取模运算；缺失的左侧与上一行字节按零读取。	W3C PNG (Third Edition)	§9.2
Paeth 过滤类型计算左、上与左上邻居的 PaethPredictor 并选择最接近者。	W3C PNG (Third Edition)	§9.4

所有条款均为转述；NextPDF 不复制规范性文本。这些是能力声明，而非认证；NextPDF 不持有任何认证，也不授予任何认证。重建数学运算与参数默认值的一致性由单元测试套件加以验证。完整的 PDF 流过滤框架以及 TIFF 预测器的逆向，都不在本模块范围内。

开发说明

• 两个类自 nextpdf/pro 3.0.0 起发布，并在 3.1.0 中保持现行。
• 当 Pro Diff 与 Classifier 提取器的输入携带预测器时，本模块被它们消费。
• 在调用 inverse() 前据 isPngPredictor() 分支；预测器 1 与 TIFF 预测器无需 PNG 逆向。
• 本模块会限定自身的逐行分配。在不受信任的流上逆向预测器的调用方，仍应在上游限定解压后的输入大小，一如 Pro 提取器所为。
• 固定预测器（10-14）与 Optimum（15）共享一条代码路径；两种情形下均由逐行标记驱动重建。
• 内部机制细节留存于源代码仓库的内部文档中，不在本手册范围内。

发布边界

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

另请参阅

• Filter（能力） —— 安装、快速上手与生产用法示例。
• Diff — 深度参考 —— 逆向过滤器的一个消费者。
• Classifier — 深度参考 —— 逆向过滤器的一个消费者。