Pro エディション

Merge — 詳細リファレンス

概要

このページは、NextPDF Pro Merge モジュール NextPDF\Pro\Merge のコントラクトレベルのリファレンスです。SmartMerger は複数の入力ドキュメントを 1 つに組み立て、Pro の強化処理を適用します。すなわち、入力ごとのラベルから統合されたブックマークツリー、ドキュメント全体の重複排除、入力ごとのページ範囲の選択、内部リンクの検出です。SemanticSplitter は、構造を認識する分割用のコンパニオンエントリポイントです。このページでは、公開 API、観測可能な挙動のコントラクト、リソースの上限、失敗モードを規定します。タスク指向のセットアップとサンプルは、Merge ケーパビリティページにあります。

提供状況とライセンス

このケーパビリティは NextPDF Pro（nextpdf/pro）で提供され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイメントでは、このケーパビリティのクラスは読み込まれません。エディションを比較してライセンスを入手する。

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

公開 API サーフェス

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`SmartMerger::__construct()`	`?PdfMerger $coreMerger = null`, `?PdfSplitter $splitter = null`	レガシーの Core マージャーを受け取り無視。`null` の splitter はデフォルトの Pro splitter を構築	—	—	`$coreMerger` は後方互換の構築のためだけに保持
`SmartMerger::merge()`	`list<MergeInput> $inputs`, `SmartMergeConfig $config = new SmartMergeConfig()`	ページ範囲を絞り込み、入力全体を重複排除し、ベース組み立てを委譲した後、config に従ってブックマークを注入しリンクをカウント	`SmartMergeResult`	空の入力リストで `InvalidArgumentException`。入力数が `maxInputs` を超えるか、入力が `maxBytesPerInput` を超える場合に `OverflowException`	唯一の結合エントリポイント
`MergeInput::__construct()`	`string $pdfData`, `list<PageRange> $pageRanges = []`, `string $label = ''`	値オブジェクト。空の `$pageRanges` は全ページを選択	—	—	Readonly
`MergeInput::hasPageRanges()`	—	入力が少なくとも 1 つのページ範囲を持つとき true	`bool`	—	—
`SmartMergeConfig::__construct()`	`bool $consolidateBookmarks = true`, `bool $deduplicatePages = false`, `bool $rewriteLinks = true`, `int $maxInputs = 100`, `int $maxBytesPerInput = 100_000_000`	強化処理のトグルとリソース上限を保持する値オブジェクト	—	—	Readonly。重複排除はオプトイン
`SmartMergeConfig::default()`	—	ブックマークとリンクスキャンをオン、重複排除をオフ	`self`	—	静的ファクトリ
`SmartMergeConfig::basic()`	—	すべての強化処理をオフ。ベース連結のみ	`self`	—	静的ファクトリ
`SmartMergeResult::__construct()`	`string $pdfData`, `int $totalPages`, `int $sourceCount`, `int $mergedSize`, `int $bookmarksAdded = 0`, `int $duplicatesRemoved = 0`, `int $linksRewritten = 0`, `list<string> $inputLabels = []`	結合されたバイト列と統合統計の Readonly キャリア	—	—	Readonly
`SmartMergeResult::isValid()`	—	出力が `%PDF` ヘッダーで始まるとき true	`bool`	—	ヘッダーチェックのみ
`SmartMergeResult::hasOptimizations()`	—	重複が 1 つでも削除されたか、リンクが 1 つでもカウントされたとき true	`bool`	—	—
`SemanticSplitter::__construct()`	`?PdfSplitter $splitter = null`	`null` 引数はデフォルトの Pro splitter を構築	—	—	テスト用のコンストラクタ注入
`SemanticSplitter::splitByStructure()`	`string $pdfData`, `float $headingFontThreshold = 14.0`	見出しサイズの `Tf` 演算子をセクション開始として検出し、その境界で分割。構造が検出されない場合はドキュメント全体を 1 セクションとして返す	`SplitResult`	バッファが空、または `%PDF` ヘッダーを欠く場合に `InvalidArgumentException`。入力が 100 MB を超える場合に `OverflowException`	Core のページ範囲分割にフォールバック

エントリーポイントのシグネチャ

public function __construct(
    ?PdfMerger $coreMerger = null,
    ?PdfSplitter $splitter = null,
)

public function merge(
    array $inputs,
    SmartMergeConfig $config = new SmartMergeConfig(),
): SmartMergeResult

public function __construct(
    public string $pdfData,
    public array $pageRanges = [],
    public string $label = '',
)

public function hasPageRanges(): bool

public function __construct(
    public bool $consolidateBookmarks = true,
    public bool $deduplicatePages = false,
    public bool $rewriteLinks = true,
    public int $maxInputs = 100,
    public int $maxBytesPerInput = 100_000_000,
)

public static function default(): self

public static function basic(): self

public function isValid(): bool

public function hasOptimizations(): bool

public function __construct(?PdfSplitter $splitter = null)

public function splitByStructure(
    string $pdfData,
    float $headingFontThreshold = 14.0,
): SplitResult

挙動コントラクト

マージパイプライン

SmartMerger::merge() は固定のパイプラインを実行し、外部からは次のように観測されます。

空の入力リストは InvalidArgumentException を送出します。次に入力数が maxInputs で上限付けされ、超過すると OverflowException を送出します。
各入力は使用前に maxBytesPerInput に対してサイズチェックされます。入力がページ範囲を宣言している場合、まず Pro splitter を通じて選択されたページに絞り込まれ、それらのページのみを寄与します。
deduplicatePages が有効な場合、各入力ドキュメントの完全なバイト列が、非暗号の xxh128 関数でフィンガープリント化されます。バイトが先行する入力と完全に一致する入力は破棄されます。重複排除はドキュメント全体かつバイト単位で厳密です。
ベース組み立ては Pro の PdfSplitter::mergeDocuments() エンジンに委譲され、すべての入力を 1 つの連続したオブジェクト空間に再番号付けし、実際のクロスリファレンステーブルを出力します。
ブックマークの統合は、consolidateBookmarks が有効で、かつ少なくとも 1 つの入力が空でないラベルを持つ場合に適用されます。最小限の /Outlines ディクショナリが挿入され、ドキュメントカタログからリンクされ、結合順に入力ごとに 1 つのアウトラインエントリを持ちます。
rewriteLinks が有効な場合、結合された出力が /S /GoTo アクションについてスキャンされ、その数が報告されます。

結果の統計

SmartMergeResult は、結合されたバイト列に加えて統計を報告します。totalPages はベース結合に由来します。sourceCount は元の入力数であり、重複排除の前に取得されます。mergedSize は出力のバイト長です。bookmarksAdded は空でないラベルを提供した入力のみをカウントします。duplicatesRemoved は破棄された入力全体をカウントします。linksRewritten は検出された GoTo の数です。inputLabels は結合順に解決されたラベルを列挙します。isValid() は %PDF ヘッダーをチェックし、hasOptimizations() は重複が削除されたかリンクがカウントされたときに true になります。

ブックマークのタイトル

各アウトラインエントリは、入力ラベルを /Title として保持し、ISO 32000-2:2020 §7.3.4.2 に従って PDF リテラル文字列としてエスケープされます。まず逆ソリダスが二重化され、丸括弧がエスケープされ、名前付き制御バイトは定義済みのシーケンスを使用し、残りの印字不可能なバイトは 3 桁の 8 進エスケープになります。したがって、悪意のあるラベルであっても、リテラル文字列の区切り文字を非同期化したり、オブジェクト構造を注入したりすることはできません。空のラベルを持つ入力には、1 始まりで Document N のプレースホルダタイトルが付与されます。

ベースの組み立て

レガシーの Core PdfMerger::merge() は、本リリースでは意図的にフェイルクローズドのスタブであり、SmartMerger から呼び出されることはありません。ベース結合は代わりに Pro の PdfSplitter::mergeDocuments() を通じて実行されるため、結合されたファイルは ISO 32000-2:2020 §7.5.4 に従い、間接オブジェクトごとに 1 エントリを持つバイト精度のクロスリファレンステーブルを保持します。決定性は Pro splitter の文書化されたプロファイルに従います。すなわち、同一の入力と構成は安定したバイトストリームを生成します。

構造を考慮した分割

SemanticSplitter::splitByStructure() は、ページのコンテンツストリームを headingFontThreshold（デフォルト 14.0）以上の Tf set-font 演算子についてスキャンし、そのような各ページをセクション開始として扱います。境界はページ範囲に変換され、Pro の PdfSplitter::split() に委譲されます。境界が検出されない場合、ドキュメント全体が単一のセクションとして返されます。入力は %PDF で始まり、100 MB の上限内に収まる必要があります。

エッジケースと失敗モード

空の入力リストは、いかなる組み立ての前に InvalidArgumentException で失敗します。
maxInputs（デフォルト 100）を超える入力数、または maxBytesPerInput（デフォルト 100 MB）を超える入力は、OverflowException で失敗します。どちらの上限も、一時的なエラーではなく意図的なフェイルクローズドの拒否です。
重複排除はドキュメント全体かつバイト単位で厳密です。同一にレンダリングされるものの、いずれかのバイトが異なる 2 つの入力は両方とも保持され、duplicatesRemoved はページ指向の deduplicatePages という名前にもかかわらず、破棄された入力全体をカウントします。
sourceCount は、重複排除後のドキュメント数ではなく、元の入力数を反映します。
ブックマークの統合は、少なくとも 1 つの入力が空でないラベルを持つ場合にのみ発火します。consolidateBookmarks が true でもすべてのラベルが空の場合、/Outlines オブジェクトは書き込まれません。
注入されるアウトラインエントリは、タイトルと /Parent、/Prev、/Next のツリーリンクを保持しますが、本リリースでは明示的な /Dest 宛先を埋め込みません。
リンク書き換えは /S /GoTo アクションのみをカウントし、再番号付けされたオブジェクトをまたいで宛先を再指定することはしません。linksRewritten は検出カウントとして扱ってください。
SemanticSplitter の検出は字句的です。Tf フォントサイズ演算子をキーにするため、画像のみのページや通常でないエンコーディングのページは境界を生成せず、単一のドキュメント全体セクションを返します。

FIPS モードの挙動

このモジュールでは暗号操作は一切行われないため、FIPS モード固有の挙動は存在しません。重複排除に使用される xxh128 コンテンツフィンガープリントは非暗号の変更検出ハッシュであり、完全性や証拠としての重みは一切持ちません。

適合性

Claim	Standard	Clause
統合ブックマークを、ドキュメントカタログからリンクされた `/Outlines` ディクショナリとして書き込み	ISO 32000-2:2020	§7.7.2
ベース結合が、すべての間接オブジェクトについてバイト精度のクロスリファレンステーブルを出力	ISO 32000-2:2020	§7.5.4
アウトラインエントリのタイトルを、バックスラッシュと丸括弧の処理を伴う PDF リテラル文字列としてエスケープ	ISO 32000-2:2020	§7.3.4.2
クロスドキュメントのリンク完全再解決	—	非対応（GoTo 検出のみ）
セクションごとの明示的なアウトライン宛先	—	本リリースでは非出力

すべての条項はパラフレーズされており、NextPDF は規範的テキストを複製しません。これらはケーパビリティの記述であり、認証ではありません。NextPDF はいかなる認証も保有せず、いかなる認証も付与しません。

開発上の注意

Pro パッケージ内での提供状況: SmartMerger、MergeInput、SmartMergeConfig、SmartMergeResult、SemanticSplitter は 2.2.0 以降。いずれも nextpdf/pro 3.1.0 で最新です。
ベース結合は Pro の PdfSplitter::mergeDocuments() に委譲します。レガシーの Core PdfMerger::merge() は本リリースではフェイルクローズドのスタブであり、呼び出されることはありません。
deduplicatePages は、入力がバイト単位で同一のドキュメント全体になり得る場合にのみ有効化してください。近似重複や再エンコードされたコピーを畳み込むことはしません。
純粋な連結には SmartMergeConfig::basic() を、ブックマークとリンクスキャンには ::default() を使用してください。
信頼できない入力を結合する際は OverflowException をキャッチしてください。カウントとサイズの上限は意図的な拒否です。
単純なページ範囲分割には Pro の PdfSplitter を直接使用し、見出し駆動のセクション化が必要な場合にのみ SemanticSplitter に手を伸ばしてください。

公開の境界

このページは、外部から観測可能な挙動とサポートされる公開 API のみを文書化します。内部の名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、チケットのプレフィックスは対象外です。