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。已存在的值會在剖析階段以 fail-closed 方式驗證，先於任何幾何資訊抵達反向過濾器的列配置之前：

• 任一可辨識鍵若存在負值即遭拒。
• /Columns 超過 1,000,000 即遭拒。
• /Colors 超過 32 即遭拒。
• /BitsPerComponent 不在 {1, 2, 4, 8, 16} 之內即遭拒。
• 推導出的列跨距超過 64,000,000 位元組即遭拒。

isPngPredictor() 在剖析出的預測器為 10 至 15 時回傳 true。Predictor 1（無預測）與 predictor 2（TIFF 群組）回傳 false。

列幾何

PngPredictor::inverse() 會消費一個經 FlateDecode 的位元組串流，其中每一列前面都帶有一個一位元組的過濾標記。它會在剝除標記後發出重建的酬載。列酬載寬度為 ceil(columns * colors * bitsPerComponent / 8) 位元組；列跨距再加上一個標記位元組。左鄰位移（每像素位元組數）為 max(1, floor(colors * bitsPerComponent / 8))，因此次位元組封裝會向下取整為一個位元組。無論位元深度為何，過濾都以完整位元組運作，與 PNG 過濾器語意相符。

逐列重建

標記	過濾器	重建
0	None	passthrough
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() 會拒絕 /Columns 超過 1,000,000 以及 /Colors 超過 32。
• fromDictionary() 會拒絕 /BitsPerComponent 不在 {1, 2, 4, 8, 16} 之內，以及推導出的列跨距超過 64,000,000 位元組。
• inverse() 會拒絕 10-15 以外的預測器。此處絕不會反向過濾 TIFF 預測器（2）；請先以 isPngPredictor() 分支判斷。
• inverse() 會拒絕 columns 或 colors 低於 1，以及 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() 分支判斷；predictor 1 與 TIFF 預測器不需要 PNG 反向處理。
• 此模組會界定自身的每列配置。在不受信任的串流上反向處理預測器的呼叫端，仍應如 Pro 擷取器一般，在上游界定解壓縮後的輸入大小。
• 固定預測器（10-14）與 Optimum（15）共用同一段程式碼路徑；兩種情況下都由逐列標記驅動重建。
• 內部機制細節保留於原始碼儲存庫的內部文件中，不在本手冊的範圍內。

發佈邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名與工單前綴皆不在範圍內。

另請參閱

• Filter（能力） — 安裝、快速上手與生產環境使用範例。
• Diff — 深入參考 — 反向過濾器的使用者。
• Classifier — 深入參考 — 反向過濾器的使用者。