Pro 版本

Writer

速览

Writer 模块向一份 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）的 append-only 规则。
ObjectStreamWriter 将小对象分组进单个被压缩的 Object Stream。这减小交叉引用表的大小并改善压缩。它拒绝会超过最大流大小的对象，并拒绝一个空流。

append-only 规则保护既有签名。缓冲区在修订之前持有的每一个字节，都必须在修订之后在相同位置原样出现。如果任何更早的字节发生变化，writer 会引发一个错误，且不产出输出。

为何如此设计

关键的承重选择在于 append-only 门控所处的位置。它位于 writer 作用域，而不仅仅位于更高层的编排器中，因此每一个现有及未来的调用方都继承了失败关闭的覆盖。该检查是一个纯粹的前缀相等测试：writer 在追加之前对缓冲区前缀拍下快照，然后在追加之后确认每一个更早的字节都未改变。这保护了任何 /ByteRange 覆盖了该前缀的签名，因为一个被改动的字节就会无声地使其失效。传统交叉引用表与一个 /Prev 指针承载新修订，因为增量更新必须追加而非重写。验证代价随既有前缀的大小呈线性，而这一代价是被有意接受的：已签名字节的完整性优先于一份副本。

设计背景：增量更新及其重要性。

行为契约

IncrementalUpdateWriter::writeRevision(...) 返回新交叉引用表的字节偏移量，因此你可以串接后续修订。
writer 验证原始前缀在写入前后字节相等。一处偏差会引发一个携带 append-only 违规状态的 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.

边界情况与注意事项

append-only 检查会复制既有前缀。其代价随已写入文档的大小而增长。此代价是有意为之的，并保护已签名的字节。
Object Stream 大小限制是针对压缩前的合并索引与正文。请据此对对象分组。
Object Stream 不得包含某些对象类型（例如加密字典）。请将那些作为直接的间接对象放置。

性能

append-only 验证在既有文档前缀的大小上呈线性。Object Stream 打包减小交叉引用大小并改善压缩，代价是一次额外的压缩趟。没有已发布的吞吐量数字。请用有代表性的文档测量。

安全说明

增量 writer 是失败关闭（fail-closed）的。如果某个代码路径会改变一个更早签名所覆盖的字节，writer 会引发一个错误，而非产出一份文档。这为修订串接（revision-chained）的工作流程保护签名完整性。不记录任何文档内容。

一致性

源代码注明了 ISO 32000-2 中的增量更新文法与 Object Stream 模型，以及 ETSI EN 319 142-1 PAdES 配置文件中的修订串接要求。由于撰写本页时 RAG 语料不可用，本页仅重复源代码本身所声明的条款引用，且不主张任何额外的外部条款标识。

Enterprise 边界说明

Enterprise 增加在行为层面构建于增量更新之上的更高层签名生命周期功能（长期验证与续期）。Writer 模块仅提供修订原语；那些更高层功能另行记录，且并非写入一个修订所必需。

Core 回退/替代方案

没有 Pro 时，使用 NextPDF Core 的基础 writer；带 append-only 门控的增量更新修订与 Object Stream 打包是 Pro 的增项。参见 /modules/writer/。

发布边界

本页仅记录外部可观测行为与受支持的公开 API 表面。内部命名空间路径、辅助类、机制表、runbook 文件名与工单前缀不在范围之内。