Pro エディション

フローレイアウト

概要

NextPDF Pro は、フロー要素（テキスト、画像、テーブル、スペーサー）のシーケンスをページ上に配置し、それぞれに具体的なページと位置を割り当てます。ページ分割の振る舞いは選択可能で、貪欲（greedy）、孤立行回避（orphan-avoiding）、まとめ保持（keep-together）のいずれかです。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）で提供され、Pro ティアのライセンスエンベロープで有効化されます。その権利を持たないデプロイでは、この機能のクラスは読み込まれません。機能ごとの個別ライセンスフラグはありません。Pro のエンベロープがこれを有効にします。エディションを比較してライセンスを取得する。

インストール

composer require nextpdf/pro:^3

概念の概要

ストリーミングレイアウトエンジンは、フロー要素のリストとコンテンツ領域を受け取り、要素を順に走査して、それぞれにページと位置を割り当てます。要素が残りの垂直スペースに収まらない場合、エンジンは設定された戦略に従って新しいページを開始します。

StreamingLayoutEngine — エンジンです。LayoutRegion（ページごとのコンテンツ領域）と PageBreakStrategy で構築します。配置された要素の LayoutResult を返します。
FlowElement / FlowElementType — 要素モデルです。テキストとテーブルはページをまたいで分割できます。エンジンは画像とスペーサーを不可分に配置します。
PageBreakStrategy — 3 つの振る舞いを持つ enum です。
- Greedy — 次の要素が収まらなくなった時点で分割します。
- AvoidOrphans — 残りスペースがわずかしかない場合に早めに分割し、新しいページの先頭に要素が 1 つだけ残らないようにします。
- KeepTogether — keep-with-next フラグを尊重し、可能な場合にペアの要素を同じページに保ちます。

フローレイアウトは要素配置エンジンです。ページと位置の割り当てを計算します。HTML や CSS のレンダリングエンジンではありません。HTML から PDF への変換には、Core の HTML パイプラインを使用してください。

この設計の理由

エンジンは、1 回の前方パスで各要素にページと位置を割り当てます。後でリフローするためにドキュメントツリー全体をバッファリングすることはありません。そのため、ドキュメントがどれだけ長く続いてもメモリは有界に保たれ、コストは要素数に対して線形になります。各ページ分割の判断は、現在のカーソルと選択された戦略に対するローカルな述語です。したがって、貪欲、孤立行回避、まとめ保持のいずれも、同じストリーミング走査の中で解決されます。トレードオフは前方コミットです。背が高すぎる要素は再スケーリングされずにオーバーフローし、まとめ保持はペアの両方の要素が同じページを共有する場合にのみ成立します。

設計の背景：大量ドキュメント生成。

API サーフェス

クラス	責務
`StreamingLayoutEngine`	フロー要素にページと位置を割り当てる。
`FlowElement`, `FlowElementType`	要素モデルと種別 enum。
`LayoutRegion`	ページごとのコンテンツ領域。
`PageBreakStrategy`	ページ分割の振る舞い enum。
`LayoutResult`, `PlacedElement`	配置の出力。

コードサンプル — クイックスタート

use NextPDF\Pro\FlowLayout\{StreamingLayoutEngine, LayoutRegion, PageBreakStrategy};

$engine = new StreamingLayoutEngine(
    region:   new LayoutRegion(/* x, y, width, height */),
    strategy: PageBreakStrategy::AvoidOrphans,
);
$result = $engine->layout($elements);

コードサンプル — 本番

$result = $engine->layout($elements);
foreach ($result->placements as $placed) {
    $logger->debug('flow.placed', [
        'page' => $placed->pageIndex,
        'type' => $placed->element->type->value,
    ]);
}

エッジケースと落とし穴

領域より背の高い要素も、エンジンは依然として配置しますが、オーバーフローする場合があります。要素は領域の高さに収まるようサイズを調整してください。
KeepTogether は、両方が 1 ページに収まる場合にのみペアをまとめて保持します。
AvoidOrphans は、分割する前に少なくとも要素 2 つ分の高さを確保します。

パフォーマンス

レイアウトは要素数に対して線形です。エンジンはストリーミングであり、ドキュメントツリー全体を保持しません。

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

フローレイアウトは、あなたが供給する要素のメタデータを操作します。I/O は行いません。

適合性

フローレイアウトは NextPDF の配置の振る舞いを実装します。外部のレイアウト標準を対象とはしません。

振る舞いの契約

StreamingLayoutEngine は、LayoutRegion と PageBreakStrategy で構築され、具体的なページと位置の割り当てを持つ配置済み要素の LayoutResult を返します。
PageBreakStrategy は 3 つの振る舞いを持ちます。Greedy（次の要素が収まらないときに分割）、AvoidOrphans（早めに分割し、少なくとも要素 2 つ分の高さを確保）、KeepTogether（keep-with-next を尊重し、両方が収まる場合にペアの要素を 1 ページに保つ）です。
テキストとテーブルはページをまたいで分割できます。画像とスペーサーは不可分に配置されます。領域より背の高い要素も配置されますが、オーバーフローする場合があります。
エンジンはストリーミングであり、ドキュメントツリー全体を保持せず、I/O を行いません。
これは要素配置エンジンです。ページと位置の割り当てを計算します。HTML や CSS のレンダリングエンジンではありません。

Enterprise の境界に関する注意

Enterprise はフローレイアウトの振る舞いを変更しません。Enterprise は別途文書化された上位ティアの機能を追加しますが、それらは配置エンジンの使用には必要ありません。

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

ページ分割戦略を備えた Core の要素配置エンジンはありません。HTML から PDF へのレンダリングには、オープンソースの Core HTML パイプラインを使用してください。/modules/html/ を参照してください。

公開範囲の境界

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