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() 為 true。
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() 分支。
短於所計算 stride 的預測器列會被拒絕；它不會被默默截斷。
列 stride 由 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 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名與工單前綴皆不在範圍內。