Pro エディション

結合

概要

NextPDF\Pro\Merge\SmartMerger は複数の PDF を 1 つに結合し、続いて Pro の拡張機能を適用します。入力ごとのラベルから統合されたブックマークツリー、コンテンツハッシュによるページの重複排除、入力ごとのページ範囲の選択です。基本ドキュメントの組み立ては Pro のオブジェクトグラフ結合エンジンを通じて実行されます。すべての入力を 1 つのオブジェクト空間に採番し直し、実体のあるクロスリファレンステーブルを書き出します。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）で提供され、Pro 層のライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得する。

Merge のクラスは Pro パッケージがインストールされていればいつでも利用できます。このモジュールをゲートするランタイムのケーパビリティフラグはありません。

インストール

composer require nextpdf/pro:^3

概念の概要

SmartMerger は MergeInput 値オブジェクトのリストを受け取ります。各入力は、ソース PDF のバイト列、任意のページ範囲のリスト、そして任意のラベルを保持します。ページ範囲を持つ入力は、結合前に選択されたページに絞り込まれます。結合されたドキュメントは Pro のオブジェクトグラフ結合エンジンによって生成され、これはすべての入力を 1 つの連続したオブジェクト空間に採番し直し、実体のあるクロスリファレンステーブルを出力します。続いて Pro レイヤーが要求された拡張機能を追加します。

SmartMergeConfig が拡張機能を制御します。

ブックマークの統合 は、ラベル付けされた入力ごとに 1 つのアウトラインエントリを挿入し、その入力のセクションの先頭を指し示します。これは ISO 32000-2:2020 §7.7.2 のドキュメントカタログの /Outlines モデルに従います。
ページの重複排除 は、コンテンツハッシュで比較し、入力をまたいでバイト単位で同一の重複ページを除去します。
リンクの書き換え は、結合された出力内の内部 GoTo アクションをスキャンします。

SmartMergeResult は、結合されたバイト列に加えて統計情報を報告します。総ページ数、ソース数、出力サイズ、追加されたブックマーク、除去された重複、検出されたリンク、そして順序付けられた入力ラベルです。

この仕組みが機能する理由

PDF の結合はバイトの連結ではありません。各入力は独自のオブジェクト番号、クロスリファレンステーブル、ページツリーを保持するため、単純な継ぎ合わせでは適合するリーダーで一切ロードできません。そのため SmartMerger は基本の組み立てを Pro のオブジェクトグラフエンジン（PdfSplitter::mergeDocuments()）に委譲します。これはすべての入力を 1 つの連続したオブジェクト空間に採番し直し、単一のページツリーを再構築し、真のバイトオフセットを持つ実体のあるクロスリファレンステーブルを出力します。続いて Pro の拡張機能 — ブックマークの統合、重複排除、リンク検出 — が、組み立てを再実装するのではなく、その検証済みの出力の上に重ねられます。ドキュメント全体の重複排除と検出のみのリンク処理は、信頼できない入力に対して結合を決定論的かつ安全に保つための意図的なスコープ境界です。

設計背景: PDF ファイルの構造。

振る舞いの契約

入力。 空でない MergeInput のリスト。空のリストは InvalidArgumentException を発生させます。入力数と入力ごとのバイトサイズは SmartMergeConfig（maxInputs、maxBytesPerInput）で境界が設けられます。
出力。 SmartMergeResult。出力が %PDF ヘッダーで始まる場合に isValid() が true になります。
ブックマークの統合 は、consolidateBookmarks が有効な場合、空でないラベルを持つ入力ごとに 1 つのエントリを追加します。
重複排除 はオプトイン（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 結合エンジンが支配的であり、入力の総バイト数とページ数に応じてスケールします。重複排除はページごとにコンテンツハッシュを 1 つ追加します。 performance_budget のフロントマターが、結合ごとの参照値です。

セキュリティに関する注意

入力数と入力ごとのサイズは、悪意ある入力によるリソース枯渇を制限するために SmartMergeConfig で境界が設けられます。結合は埋め込みのドキュメントスクリプトを実行しません。バイトストリーム解析の堅牢化については Core のセキュリティモデルを参照してください。

適合性

主張	仕様の節	ステータス
`/Outlines` による統合されたブックマーク	ISO 32000-2:2020 §7.7.2	検証済み（ユニットスイート）
コンテンツハッシュによるページ重複排除	—	検証済み（ユニットスイート）
完全なクロスドキュメントリンクの再解決	—	サポート対象外（検出のみ）

Core のフォールバック/代替手段

Pro の統合を伴わない基本的な連結には、オープンソースの Core NextPDF\Document\PdfMerger がサポートされるスタンドアロンの経路です。SmartMerger はそれに委譲しません。Pro の結合は独自のオブジェクトグラフエンジンで実行されます。 /modules/core/document/ を参照してください。

Enterprise の境界に関する注記

このモジュールは構造的な結合を行います。リーガルホールドのアセンブリ、墨消し、または証拠の管理連鎖（chain-of-custody）のパッケージ化は行いません。それらはここでは提供されません。

公開の境界

このページは、外部から観測可能な振る舞いとサポートされる公開 API サーフェスのみを記述しています。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、およびチケットのプレフィックスは対象外です。