ドキュメント

概要

ドキュメントモジュールは、PDF をページ範囲ごとにセグメントへ分割し、ソート可能なスキーマ列を持つ PDF ポートフォリオ（コレクション）を組み立てます。どちらの操作も、敵対的な入力に対して上限が設けられています。

提供とライセンス

この機能は NextPDF Pro（nextpdf/pro）に同梱され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイでは、この機能のクラスはロードされません。ドキュメントは Pro エディションの一部であり、機能ごとの個別ライセンスフラグはありません。エディションを比較してライセンスを取得する。

インストール

composer require nextpdf/pro:^3

コードは NextPDF\Pro\Document 名前空間の下にあります。

概念の概要

2 つの機能が提供されます。

• PdfSplitter は、ページ範囲を独立した PDF セグメントへ抽出します。生入力内のページオブジェクトをスキャンしてページを検出し、選択したページを最小限のカタログとページツリーで包みます。範囲ベースの分割、固定サイズの分割（splitEvery）、単一範囲の抽出（extractPages）に対応します。
• PdfPortfolio は、定義されたスキーマでファイル添付を集約する PDF コレクション辞書を構築します。タイル、詳細、非表示の表示モードに対応し、ドキュメントカタログへの組み込みに適した辞書を出力します。

なぜこのように機能するのか

PDF の分割は、バイト列の切り出しではありません。ページオブジェクトは、共有リソース、フォント、コンテンツストリームを間接参照で参照します。また、ページツリーの祖先から /MediaBox と /Resources を継承します。そのためスプリッターは、各セグメントを自己完結したオブジェクトグラフとして再構築します。選択したページの推移的な参照クロージャをたどり、継承された属性を実体化し、新しい ID 空間へ採番し直し、バイト単位で正確なオフセットを持つクロスリファレンステーブルを書き出します。クロージャのたどりには上限が設けられています。さもなければ、敵対的なファンアウトグラフが 1 つのセグメントへ無制限の処理を引き込みかねないためです。結果は、ぶら下がった参照を持つ断片ではなく、有効な独立した PDF として開きます。

設計の背景については、PDF ファイルの解剖学 を参照してください。

振る舞いの契約

• PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) は、入力サイズの上限と範囲数の上限を適用し、PDF ヘッダーで始まらない入力を拒否します。
• splitEvery($pdfData, $pagesPerSegment) は、1 未満のセグメントサイズを拒否します。最後のセグメントには、より少ないページが含まれる場合があります。
• PdfPortfolio は、構築時にタイル、詳細、非表示以外の表示モードを拒否します。
• addSchema() と addEntry() は、流れるようなチェーンのためにポートフォリオを返します。generateCollectionDictionary() はコレクション辞書文字列を返します。
• スキーマフィールド名は、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 空間へ採番し直すため、増分更新や署名のワークフローには、セグメントのバイト列をライターモジュールへ渡してください。
• どのページにも一致しない範囲は、エラーではなく最小限の 1 ページのセグメントを生成します。
• ポートフォリオのソートは、デフォルトで最初のスキーマフィールドの昇順になります。

パフォーマンス

分割とポートフォリオの組み立ては、入力サイズとエントリ数に対して線形です。デフォルトの入力上限は 100 MB、デフォルトの範囲上限は 1000 で、どちらも呼び出し側が下方向に調整できます。代表的なドキュメントで計測してください。

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

入力は信頼できないものとして扱ってください。サイズと数のガードがリソース使用量の上限を決めます。モジュールは、フィールド名をサニタイズし、文字列値をエスケープしてから出力辞書に到達させます。ドキュメントの内容をログに記録しません。

適合性

ポートフォリオ辞書は PDF コレクションモデルに従い、スプリッターは ISO 32000-2 が定義するページオブジェクトモデルに従います。ソースには関連する条項が注記されています。執筆時点では RAG コーパスが利用できなかったため、このページは外部の条項識別子を主張せず、適合性に関する記述をモジュールのテストで検証された振る舞いに限定します。

Enterprise の境界に関する注意

Enterprise はドキュメントの振る舞いを変更しません。Enterprise は別途文書化された上位ティアのアーカイブおよびコンプライアンス機能を追加しますが、それらは分割やポートフォリオの組み立てには必要ありません。

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

Pro がない場合は、NextPDF Core の基本的なドキュメントプリミティブを使用してください。ページ範囲の分割とポートフォリオの組み立ては Pro の追加機能です。/modules/document/ を参照してください。

公開の境界

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

関連項目

• ドキュメント — 詳細リファレンス
• ライター
• マージ
• 出力パイプライン