Pro 版本

Document

速览

Document 模块按页范围将一份 PDF 拆分为多个分段，并组装带可排序模式列（schema columns）的 PDF Portfolio（Collection）。这两项操作都针对恶意输入设有边界约束。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）发布，并以 Pro 层级的授权信封（license envelope）激活。未持有该授权的部署不会加载此能力的类。Document 属于 Pro 版本的一部分，没有单独的按功能授权标志。比较各版本并获取授权。

安装

composer require nextpdf/pro:^3

代码位于 NextPDF\Pro\Document 命名空间下。

概念概述

提供两项能力：

PdfSplitter 将页范围提取为独立的 PDF 分段。它通过在原始输入中扫描页对象来检测页面，并将选定的页面包裹进一个最小化的目录（catalog）和页树（page tree）中。它支持基于范围的拆分、固定大小的拆分（splitEvery），以及单范围提取（extractPages）。
PdfPortfolio 构建一个 PDF Collection 字典，按既定模式聚合文件附件。它支持平铺（tile）、详情（detail）和隐藏（hidden）三种视图模式，并发出一个适合纳入文档目录的字典。

为何如此设计

拆分 PDF 并不是一次字节切片。一个页对象会通过间接引用引用共享的资源、字体和内容流；它还从其页树祖先继承 /MediaBox 和 /Resources。因此拆分器将每个分段重建为一个自包含的对象图：它遍历所选页面的传递引用闭包，物化被继承的属性，重新编号到全新的 id 空间，并写出带有字节级精确偏移量的交叉引用表。该闭包遍历是有边界的，否则一个恶意的扇出图可能把无界的工作量拖入单个分段。其结果作为一份有效的独立 PDF 打开，而不是带有悬空引用的片段。

设计背景：PDF 文件的解剖。

行为契约

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) 强制施加输入大小上限和范围数量上限，并拒绝不以 PDF 头部开头的输入。
splitEvery($pdfData, $pagesPerSegment) 拒绝小于 1 的分段大小；最后一个分段可能包含较少的页面。
PdfPortfolio 在构造时拒绝除平铺、详情或隐藏之外的任何视图模式。
addSchema() 和 addEntry() 返回 portfolio 以支持链式调用；generateCollectionDictionary() 返回 Collection 字典字符串。
模式字段名会被清洗以用作 PDF 名称对象；字符串值会针对 PDF 字面字符串进行转义。

代码示例 —— 快速上手

下面反映的是有文档记录的公共 API。该代码库不附带本模块的可运行示例。

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

代码示例 —— 生产环境

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

边界情况与注意事项

拆分器将每个分段重建为一个全新的对象图，带有真实、字节级精确的交叉引用表；分段是有效的独立 PDF。它重新编号到新的 id 空间，而不是保留源字节布局，因此在增量更新或签名工作流中，请将分段字节交给 Writer 模块处理。
匹配不到任何页面的范围会产出一个最小化的单页分段，而不是报错。
Portfolio 排序默认按第一个模式字段升序排列。

性能

拆分和 portfolio 组装随输入大小和条目数量呈线性。默认输入上限为 100 MB，默认范围上限为 1000；两者均可由调用方向下调整。请用有代表性的文档进行测量。

安全说明

请将输入视为不受信任。大小和数量保护约束了资源使用。该模块在字段名进入输出字典之前对其进行清洗，并对字符串值进行转义。它不记录任何文档内容。

一致性

Portfolio 字典遵循 PDF Collections 模型，拆分器遵循 ISO 32000-2 定义的页对象模型；源代码标注了相关条款。撰写时 RAG 语料库不可用，因此本页不主张任何外部条款标识符，并将一致性陈述限定为本模块测试所验证的行为。

Enterprise 边界说明

Enterprise 不改变 Document 的行为。Enterprise 增加了更高层级的归档与合规功能，单独编写文档；它们对于拆分或 Portfolio 组装并非必需。

Core 回退/替代方案

没有 Pro 时，请使用 NextPDF Core 的基础文档原语；按页范围拆分和 Portfolio 组装是 Pro 的新增内容。参见 /modules/document/。

发布边界

本页仅描述外部可观察的行为以及受支持的公共 API 表面。内部命名空间路径、辅助类、机制表、运行手册文件名和工单前缀均不在范围之内。