Pro 版本

投影

速覽

Projection 會將一份 PDF 內容串流剖析為一份扁平的符記清單，並從那些符記發出一份新的內容串流。發出作業需要一個明確宣告的意圖。此模組不是一個通用的 PDF 編輯器。

**註。**此處的「Projection」指的是內容串流符記投影。它不是座標或地理空間投影。地理空間功能請參閱 Geo 模組。

供應與授權

此功能隨附於 NextPDF Pro（nextpdf/pro），並以一份 Pro 級授權封套啟用。未具備該授權權益的部署不會載入此功能的類別。比較各版本並取得授權。

沒有獨立的逐功能授權旗標。一個必填的 ProjectionIntent 引數會在 API 層級閘控發出作業，而非授權開關。

安裝

composer require nextpdf/pro:^3

程式碼位於 NextPDF\Pro\Projection 命名空間下。

概念總覽

ContentProjectionWriter 提供三個靜態作業：

tokenize() 會將一份內容串流剖析為一份扁平、有序的符記清單。這是唯讀的，且不需要意圖。
emit() 會從一份（可能已修改的）符記清單寫出一份新的內容串流。它需要一個 ProjectionIntent。
roundTrip() 會進行符記化，接著不做變更地重新發出，用於驗證。

輸出在概念上是一份新的內容串流，而非原始內容串流的編輯副本。發出器會正規化空白與註解，但讓運算子序列與運算元值維持精確。意圖 enum 恰好有兩個案例——清理（遮蔽）與隱寫嵌入——並刻意不設通用案例，讓靜態分析能偵測非預期的使用。

為何如此設計

Projection 拒絕成為一個通用的 PDF 編輯器。發出作業會從一份扁平的符記清單重建一份全新的內容串流，因此原始內容永遠不會被就地變更。那個單向模型正是讓遮蔽值得信任之處：被移除的符記在輸出中是缺席的，而非被塗蓋掉。因此 emit() 要求一個明確的 ProjectionIntent，而該 enum 只提供清理與隱寫嵌入——沒有通用案例。靜態分析於是能標記任何缺少已宣告、已知目的的發出作業。此設計以編輯的便利換取一項保證：破壞性意圖在呼叫處永遠可見。

設計背景：遮蔽不是一個黑色矩形。

行為合約

tokenize($contentStream) 會回傳一份涵蓋字串、名稱、數字、陣列、字典、布林、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，與原始內容的位元組層級比較也會不同。

效能

符記化與發出與內容串流長度成線性關係。符記化器會界定八進位逸出讀取與十六進位字串處理。沒有公布的吞吐量數字。請以具代表性的內容串流量測。

安全注意事項

必填的意圖引數可防止它被當成通用編輯器濫用。清理意圖具破壞性且不可逆；請先驗證 round-trip，並在散布前確認遮蔽後的輸出。此模組不記錄任何內容。

一致性

符記化遵循 ISO 32000-2 中的詞法與內容串流慣例；來源會標註相關條款。撰寫時 RAG 語料庫無法使用，因此本頁不主張任何外部條款識別碼，並將一致性陳述限定於該模組測試所驗證的行為。

Enterprise 邊界註記

Enterprise 不會改變 Projection 的行為。Enterprise 加入的是另行記載的更高階隱私與合規功能；使用 projection API 並不需要它們。

Core 回退/替代方案

沒有 Core 對應功能。若無 Pro，呼叫端必須自行建構內容串流符記化器；意圖閘控的投影模型是 Pro 獨有的新增功能。

發布邊界

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