コンテンツにスキップ
NextPDF
getnextpdf.com

Pro エディション

Document — 詳細リファレンス

概要

「概要」という見出しのセクション

Document モジュールは、3 つの Pro アセンブリ・プリミティブを提供します。ページ範囲による分割、複数ドキュメントのマージ、そして PDF ポートフォリオ（Collection）ディクショナリの構築です。PdfSplitter は、ページ範囲を単独で構造的に適合する PDF として抽出し、ドキュメント全体を 1 つの再採番済みファイルへマージします。PdfPortfolio は、埋め込みファイルをソート可能なスキーマ列とともに提示する Collection ディクショナリを構築します。すべてのエントリーポイントは、敵対的な入力に対して入力サイズとオブジェクト数を制限します。

提供状況とライセンス

「提供状況とライセンス」という見出しのセクション

この機能は NextPDF Pro（nextpdf/pro）に含まれ、Pro ティアのライセンスエンベロープで有効化されます。この権限のないデプロイでは、当該機能のクラスは読み込まれません。エディションを比較してライセンスを入手する。

公開 API サーフェス

「公開 API サーフェス」という見出しのセクション

すべてのモジュール型は NextPDF\Pro\Document 名前空間に属します。PageRange と MergeResult は NextPDF\Document の Core 値オブジェクトです。

シンボルパラメーター既定の挙動戻り値スロー/失敗条件備考
PdfSplitter::split()string $pdfData, list<PageRange> $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000範囲ごとに単独の PDF セグメントを 1 つ構築SplitResult%PDF ヘッダー欠落時に InvalidArgumentException。サイズ・範囲数・クロージャガード違反時に OverflowExceptionガードはパース前に実行
PdfSplitter::splitEvery()string $pdfData, int $pagesPerSegment連続する N ページ範囲を導出。最後のセグメントは短くなる場合ありSplitResult$pagesPerSegment < 1 またはヘッダー欠落時に InvalidArgumentException既定の上限で split() に委譲
PdfSplitter::extractPages()string $pdfData, PageRange $range単一の範囲を単独 PDF バイト列として返すstringヘッダー欠落時に InvalidArgumentException。クロージャガード違反時に OverflowExceptionこの経路に上限パラメーターなし
PdfSplitter::mergeDocuments()list<string> $pdfs, int $maxInputs = 100, int $maxBytesEach = 100_000_000入力を順序どおり 1 つの再採番済み PDF へマージMergeResult空リストまたは非 PDF 入力時に InvalidArgumentException。件数・入力ごとサイズ・クロージャガード違反時に OverflowException3.1.0 以降。最も高い入力バージョンが出力ヘッダーを決定
SplitResultreadonly $segments, $ranges, $totalPages生のセグメントバイト列と元メタデータを保持——final readonly 値オブジェクト
SplitResult::count()—生成されたセグメント数を計数int——
SplitResult::segment()int $index単一セグメントのバイト列を返すstring範囲外インデックス時に OutOfRangeException0 始まりインデックス
PdfPortfolio::__construct()string $viewMode = 'tile'構築時にビューモードを検証—tile/detail/hidden 以外のモード時に InvalidArgumentException—
PdfPortfolio::addSchema()PortfolioField $fieldスキーマ列を追加self—フルーエント
PdfPortfolio::addEntry()PortfolioEntry $entryファイルエントリーを追加self—フルーエント
PdfPortfolio::getSchema()—蓄積されたスキーマフィールドを返すlist<PortfolioField>——
PdfPortfolio::getEntries()—蓄積されたファイルエントリーを返すlist<PortfolioEntry>——
PdfPortfolio::count()—ファイルエントリー数を計数int——
PdfPortfolio::generateCollectionDictionary()—Collection ディクショナリ文字列を出力string—スキーマ・ソートブロックはフィールドが存在するときのみ出現
PortfolioEntry$filename, $data, $description = '', $mimeType = 'application/octet-stream', $customFields = []イミュータブルなファイルエントリー値オブジェクト——size() はデータのバイト長を返す
PortfolioField$name, PortfolioFieldType $type, $displayName = '', $order = 0, $visible = trueイミュータブルなスキーマ列値オブジェクト——effectiveDisplayName() は $name にフォールバック
PortfolioFieldType文字列 enum：Text, Date, Number, FileName, Description, Size, ModDate, CreationDate各ケースを pdfSubtype() 経由で PDF /Subtype へマップstring（S, D, N, F, Desc）—日付系ケースはサブタイプ D を共有。数値系ケースは N を共有

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

public function split(string $pdfData, array $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000): SplitResult


public function mergeDocuments(
    array $pdfs,
    int $maxInputs = 100,
    int $maxBytesEach = 100_000_000,
): MergeResult
public function __construct(
    private readonly string $viewMode = 'tile',
)


public function generateCollectionDictionary(): string

挙動コントラクト

「挙動コントラクト」という見出しのセクション

分割とマージは 1 つのオブジェクトグラフ・パイプラインを共有します。

  • 入力は %PDF ヘッダーで始まる必要があります。サイズと件数のガードはパース前に実行され、違反時に OverflowException を送出します。
  • リーフページはページオブジェクトマーカーの走査で検出され、ページツリーノードは計数から除外されます。
  • パーサーは、ストリームを認識する終端走査によりすべての非圧縮間接オブジェクトをインデックス化します。オブジェクト id は最初の出現が優先されるため、インクリメンタル更新によるオーバーライドは適用されません。
  • 継承可能なページツリー属性（/Resources、/MediaBox、/CropBox、/Rotate）は、/Parent チェーンをたどって抽出済み各ページへ実体化されるため、セグメントは自己完結します。
  • 各ページの推移的な間接参照クロージャは、/Parent 逆辺を除いて収集され、新しい連続した id 空間へ再採番されます。
  • シリアライザーは、ヘッダー、Catalog、Pages ツリー、ページオブジェクト、クロージャオブジェクトを出力し、続いてバイト正確なオフセットを持つクロスリファレンステーブルと、xref キーワードを指す startxref を出力します。
  • mergeDocuments は、入力ごとにパイプラインを繰り返して 1 つの共有 id 空間へまとめます。最も高い入力 PDF バージョンが出力ヘッダーを決定します。これは、フェイルクローズドのまま維持される無効化済み Core マージャーの適合置換です。
  • 出力は決定的です。タイムスタンプもランダム識別子も出力されないため、同一入力からは同一バイト列が得られます。

Portfolio のアセンブリ：

  • コンストラクターはビューモードを検証します。出力される /View トークンは、tile・detail・hidden にそれぞれ /T・/D・/H です。
  • generateCollectionDictionary() は、/Type /Collection、/View トークン、フィールドが存在するときの /Schema ブロック、そして最初のスキーマフィールドに対する昇順の /Sort ディレクティブを出力します。
  • 各スキーマフィールドは、/Subtype（pdfSubtype() 由来）、/N（エスケープ済み表示名）、/O（順序）、/V（可視性）を出力します。
  • フィールド名は有効な PDF 名トークンへサニタイズされ、非単語文字はアンダースコアになります。文字列値は PDF リテラル文字列としてエスケープされます。
  • ファイルエントリーは、書き込みレイヤーによる埋め込みのため getEntries() を通じて公開されます。Collection ディクショナリ自体はビュー・スキーマ・ソートのみを保持します。

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

「エッジケースと失敗モード」という見出しのセクション
  • どのページにも一致しない範囲は、エラーではなく最小限の 1 ページのセグメント（612 x 792 の MediaBox）を生成します。
  • 検出可能なページマーカーを持たないドキュメントは 1 ページとして計数されます。
  • オブジェクトストリーム内に格納されたページは検出されません。抽出に関与するのは非圧縮間接オブジェクトのみです。
  • 重複するオブジェクト id が存在する場合、最小オフセットのリビジョンが使用され、後続のインクリメンタル更新リビジョンは無視されます。
  • セグメントごとの参照クロージャは 50,000 オブジェクトで上限が設けられます。悪意ある自己参照またはファンアウトグラフは OverflowException を送出します。
  • 既定の上限：入力 100 MB、範囲 1,000 件、マージ入力 100 件。すべて呼び出しごとに呼び出し側から調整可能です。
  • splitEvery() は 1 未満のセグメントサイズを InvalidArgumentException で拒否します。
  • SplitResult::segment() は範囲外インデックスを OutOfRangeException で拒否します。
  • 句読点だけが異なる 2 つのスキーマフィールド名は、同一のディクショナリキーにサニタイズされます。後のフィールドが、出力されるスキーマ内で先のフィールドを暗黙的にシャドウします。
  • このモジュールは暗号操作を一切実行しません。FIPS モードはその挙動を変更しません。

適合性

「適合性」という見出しのセクション

セグメントとマージの出力は ISO 32000-2 のページオブジェクトモデルに従い、ソースは関連する各クローズを注記しています。外部から検証可能な主張：

  • トレーラーのレイアウト、startxref のバイトオフセット、%%EOF 終端子は ISO 32000-2:2020, §7.5.5 に従います — reference ef0f2a4b563b84f81b3e6428612bc47c510d94fc8096849d339abf0f3247d845。
  • Collection ディクショナリの /View 値（/T、/D、/H）は ISO 32000-2:2020, §12.3.5 に従います — reference 5cefaaeb40f3ff98e3aba135ac57c9424a05c43144c1b9b5156bfd4295e08ddd。
  • Collection フィールドの /Subtype、/N、/O、/V エントリーは ISO 32000-2:2020, §12.3.5（collection field dictionary）に従います — reference 6300fbfdc8a913a8dc6f6ae34eff99f2bd03c4313a77777cdd5a8dd856d9537a。

これらの記述は、モジュールのテストで検証された実装済み機能を説明するものです。ある構文のサポートは適合の主張ではなく、適合は認証ではありません。NextPDF はこのモジュールについて第三者認証を保有していません。

開発上の注意

「開発上の注意」という見出しのセクション
  • すべてのモジュールクラスは final であり、結果型と値オブジェクト型は readonly です。スプリッターと Portfolio 型は 1.9.0 に由来し、mergeDocuments() は 3.1.0 で追加されました。
  • PageRange と MergeResult は Core 型のため、呼び出し側はエディション間で可搬性を保ちます。
  • セグメントのトレーラーは /Size と /Root のみを保持します。/ID ファイル識別子や /Info ディクショナリは出力されません。
  • インクリメンタル更新や署名のワークフローでは、セグメントバイト列をその場で後編集するのではなく、Writer モジュールへ渡してください。
  • このモジュールはドキュメント内容を一切ログに記録しません。

公開の境界

「公開の境界」という見出しのセクション

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

関連項目

「関連項目」という見出しのセクション