Pro 版本

合併

速覽

NextPDF\Pro\Merge\SmartMerger 會將多份 PDF 合併為一份，接著套用 Pro 增強功能：由各輸入標籤建立的整合書籤樹、以內容雜湊進行的頁面去重，以及各輸入的頁面範圍選取。基礎文件組裝會透過 Pro 物件圖合併引擎執行。它會將每個輸入重新編號到單一物件空間，並寫入一份真實的交互參照表。

供應與授權

此能力隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 層級的授權封套啟用。未具備該授權的部署不會載入此能力的類別。比較版本並取得授權。

只要 Pro 套件已安裝，Merge 類別即可使用。沒有任何執行階段能力旗標閘控此模組。

安裝

composer require nextpdf/pro:^3

概念總覽

SmartMerger 接受一份 MergeInput 值物件的清單。每個輸入都承載來源 PDF 位元組、一份可選的頁面範圍清單，以及一個可選的標籤。帶有頁面範圍的輸入會在合併前被縮減為所選頁面。合併後的文件由 Pro 物件圖合併引擎產生，它會將每個輸入重新編號到單一連續的物件空間，並發出一份真實的交互參照表； Pro 層接著加入所請求的增強功能。

SmartMergeConfig 控制這些增強功能：

書籤整合 會為每個有標籤的輸入插入一個大綱項目，指向該輸入區段的起點。這遵循 ISO 32000-2:2020 §7.7.2 中的文件目錄 /Outlines 模型。
頁面去重 會跨輸入移除位元組完全相同的重複頁面，以內容雜湊進行比較。
連結重寫 會掃描合併輸出中的內部 GoTo 動作。

SmartMergeResult 會回報合併後的位元組，外加統計：總頁數、來源數量、輸出大小、加入的書籤數、移除的重複數、偵測到的連結數，以及有序的輸入標籤。

為何如此設計

合併 PDF 並非位元組串接：每個輸入都承載自己的物件編號、交互參照表與頁面樹，因此天真的拼接在任何符合規範的閱讀器中都無法載入。因此 SmartMerger 會將基礎組裝委派給 Pro 物件圖引擎（PdfSplitter::mergeDocuments()），它會將每個輸入重新編號到單一連續的物件空間、重建單一頁面樹，並發出一份帶有真實位元組偏移的真實交互參照表。Pro 增強功能—— 書籤整合、去重與連結偵測——接著疊加於該經驗證的輸出之上，而非重新實作組裝。整份文件去重與僅偵測的連結處理是刻意的範圍界線，讓合併在不受信任的輸入上保持確定且安全。

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

行為合約

輸入。 一份非空的 MergeInput 清單。空清單會引發 InvalidArgumentException。輸入數量與各輸入位元組大小受 SmartMergeConfig（maxInputs、maxBytesPerInput）所界定。
輸出。 一個 SmartMergeResult。當輸出以 %PDF 標頭開頭時，isValid() 為 true。
書籤整合 在啟用 consolidateBookmarks 時，會為每個帶有非空標籤的輸入加入一個項目。
去重需明確選用（deduplicatePages，預設關閉），並以內容雜湊比對整頁，而非視覺上相似的頁面。
連結重寫 在目前版本中會偵測並計數內部 GoTo 動作；它不會執行完整的跨文件目的地重新解析。請將 linksRewritten 視為一個偵測計數。
確定性。 對相同的輸入與組態而言，合併後的位元組串流是穩定的，前提是符合 Pro 合併引擎已記載的確定性設定檔。

公開 API 介面

型別	種類	主要成員
`NextPDF\Pro\Merge\SmartMerger`	`final class`	`__construct(?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null)`, `merge(array $inputs, SmartMergeConfig $config = new SmartMergeConfig()): SmartMergeResult`
`NextPDF\Pro\Merge\MergeInput`	`final readonly class`	`__construct(string $pdfData, array $pageRanges = [], string $label = '')`, `hasPageRanges(): bool`
`NextPDF\Pro\Merge\SmartMergeConfig`	`final readonly class`	`__construct(bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000)`, `default()`, `basic()`
`NextPDF\Pro\Merge\SmartMergeResult`	`final readonly class`	`string $pdfData`, `int $totalPages`, `int $sourceCount`, `int $bookmarksAdded`, `int $duplicatesRemoved`, `int $linksRewritten`, `array $inputLabels`, `isValid(): bool`, `hasOptimizations(): bool`

程式碼範例——快速上手

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMerger;

$result = (new SmartMerger())->merge([
    new MergeInput(file_get_contents('cover.pdf'), label: 'Cover'),
    new MergeInput(file_get_contents('body.pdf'),  label: 'Body'),
]);

echo $result->totalPages, " pages, ",
     $result->bookmarksAdded, " bookmarks\n";

程式碼範例——正式環境

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMergeConfig;
use NextPDF\Pro\Merge\SmartMerger;

function assemblePacket(array $sections): string
{
    $inputs = [];
    foreach ($sections as $label => $bytes) {
        $inputs[] = new MergeInput($bytes, label: (string) $label);
    }

    $config = new SmartMergeConfig(
        consolidateBookmarks: true,
        deduplicatePages: true,
        rewriteLinks: false,
        maxInputs: 50,
    );

    $result = (new SmartMerger())->merge($inputs, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('merge produced invalid output');
    }

    return $result->pdfData;
}

邊界案例與陷阱

單一輸入是有效的，會合併成該文件的一份正規化副本。
去重比較整頁的位元組內容；僅在中繼資料或物件編號上有差異的頁面不會被視為重複。
對輸入的頁面範圍選取會在合併排序之前套用。
linksRewritten 是一個偵測到的動作計數，而非每一個跨文件連結目標都已被重新指向的保證。

效能

成本主要由 Pro 合併引擎主導，並隨輸入總位元組與頁數縮放。去重會為每頁加入一次內容雜湊。 performance_budget front-matter 是每次合併的參考。

安全注意事項

輸入數量與各輸入大小受 SmartMergeConfig 界定，以限制惡意輸入造成的資源耗竭。合併不會執行嵌入的文件指令碼。位元組串流剖析的強化，請參閱 Core 安全模型。

一致性

聲明	規範條款	狀態
透過 `/Outlines` 整合書籤	ISO 32000-2:2020 §7.7.2	已驗證（單元測試套件）
以內容雜湊進行頁面去重	—	已驗證（單元測試套件）
完整的跨文件連結重新解析	—	不支援（僅偵測）

Core 回退/替代方案

若只需不帶 Pro 整合的基本串接，開源 Core NextPDF\Document\PdfMerger 是受支援的獨立路徑。SmartMerger 並不委派給它；Pro 合併是在其自有的物件圖引擎上執行。請參閱 /modules/core/document/。

Enterprise 邊界註記

此模組執行的是結構性合併。它不執行法律保留組裝、遮蔽或證據監管鏈封裝；那些並非此處所提供。

發佈邊界

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