Pro 版本

Writer

速覽

Writer 模組會將增量更新（incremental-update）修訂版附加到一份 PDF，並將小型物件打包進 Object Stream。增量 writer 強制一條唯附加（append-only）規則：在該修訂版之前已存在的位元組不得改變。

可用性與授權

此功能隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 級授權封套啟用。未持有該權利的部署不會載入此功能的類別。比較各版本並取得授權。沒有獨立的個別功能授權旗標；程式碼隨 Pro 版本一起出貨。

安裝

composer require nextpdf/pro:^3

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

概念總覽

提供兩項能力：

IncrementalUpdateWriter 會寫入一個新的修訂版。它會以合併後的項目重寫 catalog、為新增與修改的物件附加一個傳統交叉參照表，並寫入一個連結到前一修訂版的 trailer。它強制一條 fail-closed 的唯附加規則。
ObjectStreamWriter 會將小型物件分組進一個單一的壓縮 Object Stream。這會縮減交叉參照表的大小並改善壓縮。它會拒絕會超過最大串流大小的物件，並拒絕空的串流。

唯附加規則保護既有的簽章。緩衝區在該修訂版之前所持有的每一個位元組，在該修訂版之後都必須以相同位置原樣出現。若任何較早的位元組改變了，writer 會引發一個錯誤，且不會產生輸出。

為何如此設計

承載重量的抉擇在於唯附加閘門的所在位置。它位於 writer 範圍，而不僅在較高層的協調器中，因此每一個現在與未來的呼叫者都繼承 fail-closed 的涵蓋。此檢查是一個純前綴相等測試：writer 在附加前快照緩衝區前綴，接著在附加後確認每一個較早的位元組都未改變。這保護了任何其 /ByteRange 涵蓋該前綴的簽章，因為單一個被更動的位元組會悄然使其失效。傳統交叉參照表與一個 /Prev 指標承載新的修訂版，因為增量更新必須是附加而非重寫。驗證成本在既有前綴上呈線性，而該成本是刻意接受的：已簽署位元組的完整性優先於一份副本。

設計背景：增量更新及其重要性。

行為合約

IncrementalUpdateWriter::writeRevision(...) 會回傳新交叉參照表的位元組偏移，讓你能串接後續修訂版。
writer 會驗證原始前綴在寫入前後是位元組相等的。一個分歧會引發一個帶有唯附加違規狀態的 writer 例外。
新的修訂版使用一個傳統交叉參照表與一個帶有 /Prev 指標的 trailer；跨修訂版混用表與串流是被允許的。
當加入一個物件會超過最大串流大小（索引加主體未壓縮 65,536 個位元組）時，ObjectStreamWriter::addObject() 會引發一個溢位錯誤。
當未加入任何物件時，ObjectStreamWriter::build() 會引發一個錯誤；否則它會回傳壓縮後的 Object Stream 內容。

程式碼範例——快速上手

以下反映已記錄的公開 API。本儲存庫並未為此模組隨附一個可執行的範例。

use NextPDF\Pro\Writer\ObjectStreamWriter;

$writer = new ObjectStreamWriter();
$writer->addObject(10, $serializedObjectBody);
$objStm = $writer->build();

程式碼範例——正式環境

use NextPDF\Pro\Writer\IncrementalUpdateWriter;

$newXrefOffset = IncrementalUpdateWriter::writeRevision(
    $buffer,
    $registry,
    $prevXrefOffset,
    $catalogObject,
    $catalogEntries,
    $catalogUpdates,
    $newObjectNumbers,
    $fileId,
);
// A WriterException here means the append-only rule was violated.
// Treat it as a hard failure; do not emit the output.

邊界案例與陷阱

唯附加檢查會複製既有前綴。其成本會隨已寫入文件的大小增長。此成本是刻意的，並保護已簽署的位元組。
Object Stream 大小上限是在壓縮之前的索引與主體合計。請據此分組物件。
Object Stream 不得包含某些物件型別（例如加密字典）。請將那些以直接間接物件放置。

效能

唯附加驗證在既有文件前綴的大小上呈線性。Object Stream 打包會縮減交叉參照大小並改善壓縮，代價是一次額外的壓縮過程。沒有已發布的吞吐量數字。請以具代表性的文件量測。

安全注意事項

增量 writer 是 fail-closed 的。若一個程式碼路徑會改變一個某較早簽章所涵蓋的位元組，writer 會引發一個錯誤，而非產生一份文件。這為修訂版串接的工作流程保護簽章完整性。不會記錄任何文件內容。

一致性

原始碼標註了 ISO 32000-2 中的增量更新文法與 Object Stream 模型，以及 ETSI EN 319 142-1 PAdES 設定檔中的修訂版串接需求。由於撰寫時 RAG 語料庫無法使用，因此本頁僅重述原始碼本身所宣告的條款參考，並不主張任何額外的外部條款識別碼。

Enterprise 邊界註記

Enterprise 在行為層級加入建構於增量更新之上的更高階簽章生命週期功能（長期驗證與更新）。Writer 模組僅提供修訂版原語；那些更高階功能另行記錄，且寫入一個修訂版並不需要它們。

Core 回退/替代方案

沒有 Pro 時，請使用 NextPDF Core 的基礎 writer；帶有唯附加閘門的增量更新修訂版與 Object Stream 打包是 Pro 的新增項目。請參閱 /modules/writer/。

發布邊界

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