Pro 版本

Document

速覽

Document 模組會依頁面範圍將一份 PDF 切分為多段，並組裝具可排序綱要欄位的 PDF Portfolio（Collection）。這兩項操作對惡意輸入皆設有界限防護。

供應與授權

此功能隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 等級的授權封套啟用。缺少該授權的部署不會載入此功能的類別。Document 屬於 Pro 版本的一部分，沒有獨立的逐功能授權旗標。比較各版本並取得授權。

安裝

composer require nextpdf/pro:^3

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

概念總覽

提供兩項能力：

PdfSplitter 會將頁面範圍抽取為獨立的 PDF 片段。它會在原始輸入中掃描頁面物件以偵測頁面，並將選定頁面包裝在一個最小化的 catalog 與 page tree 中。它支援以範圍切分、固定大小切分（splitEvery），以及單一範圍抽取（extractPages）。
PdfPortfolio 會建構一個 PDF Collection 字典，將檔案附件依已定義的綱要彙整起來。它支援 tile、detail 與 hidden 檢視模式，並發出一個適合納入文件 catalog 的字典。

為何如此設計

切分一份 PDF 並非位元組切片。一個頁面物件會透過間接參照引用共用資源、字型與內容串流。它也會從其 page-tree 祖先繼承 /MediaBox 與 /Resources。因此切分器會將每一段重建為自足的物件圖：它會走訪所選頁面的遞移參照閉包、實體化繼承的屬性、重新編號至全新的 id 空間，並寫入一個具位元組精確偏移量的交叉參照表。此閉包走訪設有界限，因為惡意的扇出圖否則可能將無界限的工作量拉進單一片段。其結果會以有效的獨立 PDF 開啟，而非帶有懸空參照的片段。

設計背景：PDF 檔案的解剖。

行為合約

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) 會強制套用輸入大小上限與範圍數量上限，並拒絕不以 PDF 標頭開頭的輸入。
splitEvery($pdfData, $pagesPerSegment) 會拒絕小於 1 的片段大小；最後一段可能包含較少的頁面。
PdfPortfolio 會在建構時拒絕 tile、detail 或 hidden 以外的任何檢視模式。
addSchema() 與 addEntry() 會回傳 portfolio 以供流暢串接；generateCollectionDictionary() 會回傳 Collection 字典字串。
綱要欄位名稱會被消毒以作為 PDF name 物件使用；字串值會為 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 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名與工單前綴皆不在範圍內。