Pro 版本

Filter

速览

NextPDF\Pro\Filter 提供两个专注的辅助工具：一个用于 PDF /DecodeParms 字典的解析器，以及一个用于逆向应用在 FlateDecode 流上的 PNG 预测器的逆向过滤器。它是 Pro Diff 和 Classifier 提取器所使用的预测器支持；它不是一个通用的过滤器框架。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）一同发布，并在 Pro 层级的授权信封下激活。缺少该授权的部署不会加载此能力的相关类。比较各版本并获取授权。

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

安装

composer require nextpdf/pro:^3

概念概述

PDF 流可能经过 FlateDecode 压缩，并额外用预测器进行预处理以改善压缩效果。ISO 32000-2:2020 §7.4.4.4 定义了预测器参数（/Predictor、/Columns、/Colors、/BitsPerComponent）以及 PNG 预测器族（标签 10–15）。

DecodeParms 将一个 /DecodeParms 字典片段解析为一个带合理默认值（predictor 1、columns 1、colors 1、bits-per-component 8）的不可变值对象。对于标签 10–15，isPngPredictor() 为真。
PngPredictor 应用五种 PNG 过滤类型 —— None、Sub、Up、Average、Paeth —— 的逆运算，外加 Optimum（predictor 15，逐行标签）。它会校验参数，并在取值越界或行被截断时抛出 InvalidArgumentException。

本模块在读取流时逆向一个已存在的预测器。它不实现完整的 PDF 流过滤器集合，也不提供过滤器调优挂钩。

为何采用这种设计

本模块逆向一个已存在的预测器，而不是提供一个通用的过滤器框架。Pro Diff 和 Classifier 提取器只读取生产方已经写入的内容，因此一个狭窄的范围就已足够。这个范围让每个输入都能在处理任何字节之前先被约束。DecodeParms::fromDictionary() 是解析时的收敛点：它拒绝负值或超大的几何参数，并在某个键缺失时应用 DecodeParms::__construct() 的默认值。PngPredictor 在应用时重新校验这些边界，因此一个恶意的 /DecodeParms 会抛出带类型的错误，而不是引发一次大规模分配。调用方基于 DecodeParms::isPngPredictor() 进行分支，从而把 TIFF 预测器挡在一个仅处理标签 10–15 的逆向过滤器之外。

设计背景：流与过滤器。

行为契约

DecodeParms::fromDictionary(string $raw): self —— 容忍空白的整数匹配；缺失的键保持其默认值。
PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string —— predictor 必须为 10–15；columns 和 colors 必须 ≥ 1；bits-per-component 必须为 1、2、4、8 或 16；短于所计算步幅（stride）的行会抛出 InvalidArgumentException。
确定性。 输出是输入的纯函数。

公共 API 接口

类型	种类	关键成员
`NextPDF\Pro\Filter\DecodeParms`	`final readonly class`	`__construct(int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8)`, `static fromDictionary(string $raw): self`, `isPngPredictor(): bool`
`NextPDF\Pro\Filter\PngPredictor`	`final class`	`static inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string`

代码示例 —— 快速上手

<?php

declare(strict_types=1);

use NextPDF\Pro\Filter\DecodeParms;
use NextPDF\Pro\Filter\PngPredictor;

$parms = DecodeParms::fromDictionary('<< /Predictor 15 /Columns 640 /Colors 3 >>');

if ($parms->isPngPredictor()) {
    $raw = PngPredictor::inverse(
        $flateDecodedBytes,
        $parms->columns,
        $parms->colors,
        $parms->bitsPerComponent,
        $parms->predictor,
    );
}

代码示例 —— 生产环境

<?php

declare(strict_types=1);

use InvalidArgumentException;
use NextPDF\Pro\Filter\DecodeParms;
use NextPDF\Pro\Filter\PngPredictor;

function undoPredictor(string $decoded, string $dictFragment): string
{
    $parms = DecodeParms::fromDictionary($dictFragment);

    if (! $parms->isPngPredictor()) {
        return $decoded; // no predictor, or TIFF predictor — return as-is
    }

    try {
        return PngPredictor::inverse(
            $decoded,
            $parms->columns,
            $parms->colors,
            $parms->bitsPerComponent,
            $parms->predictor,
        );
    } catch (InvalidArgumentException) {
        return $decoded; // malformed predictor metadata — fail safe
    }
}

边界情况与注意事项

TIFF 预测器（标签 2）会被 DecodeParms 识别，但不会被 PngPredictor（仅接受 10–15）逆向过滤。调用方应基于 isPngPredictor() 进行分支。
短于所计算步幅的预测器行会被拒绝；它不会被静默截断。
行步幅由 columns * colors * bitsPerComponent 计算得出；/DecodeParms 与实际流布局不匹配时，会产生参数或截断错误，而不是损坏的输出。

性能

PngPredictor::inverse() 随流长度呈线性，每字节常数很小。DecodeParms 解析是少量有界的正则表达式匹配。参见 performance_budget。

安全说明

参数范围在任何字节处理之前都会被校验，且被截断的行会抛出异常而不是越界读取。在不受信任的流上逆向预测器的调用方，还应像 Pro Diff 和 Classifier 提取器那样，在上游对解压后的大小设限。

一致性

主张	规范条款	状态
`/DecodeParms` 参数与默认值	ISO 32000-2:2020 §7.4.4.4	已验证（单元测试套件）
PNG 预测器逆向过滤，标签 10–15	ISO 32000-2:2020 §7.4.4.4	已验证（单元测试套件）
完整的 PDF 流过滤器框架	—	不支持（不在范围内）

Core 回退/替代方案

PNG 预测器逆向没有暴露出 Core 等价物。Core 自身的流处理是引擎内部的，不属于本公共接口。

Enterprise 边界说明

这是一个狭窄的预测器辅助工具。它不是密码学过滤器、内容清洗器，也不是数据重建/解除武装（disarm）组件；这些事项不在范围之内。

发布边界

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