Flow Layout

At a glance

NextPDF Pro places a sequence of flow elements — text, images, tables, spacers — onto pages, assigning each a concrete page and position. Page-break behavior is selectable: greedy, orphan-avoiding, or keep-together.

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. There is no separate per-feature license flag; the Pro envelope enables it. Compare editions and get a license.

Install

composer require nextpdf/pro:^3

Conceptual overview

The streaming layout engine takes a list of flow elements and a content region, then walks the elements in order and assigns each a page and position. When an element does not fit the remaining vertical space, the engine starts a new page according to the configured strategy:

• StreamingLayoutEngine — the engine. Constructed with a LayoutRegion (the content area per page) and a PageBreakStrategy. It returns a LayoutResult of placed elements.
• FlowElement / FlowElementType — the element model. Text and tables can break across pages; the engine places images and spacers atomically.
• PageBreakStrategy — an enum with three behaviors:
  • Greedy — break as soon as the next element does not fit.
  • AvoidOrphans — break early when only a small amount of space remains, to avoid leaving a single element at the top of a new page.
  • KeepTogether — honor the keep-with-next flag so paired elements stay on the same page when possible.

Flow Layout is an element-placement engine. It computes page and position assignments; it is not an HTML or CSS rendering engine. For HTML-to-PDF, use the Core HTML pipeline.

Why it works this way

The engine assigns each element a page and position in one forward pass. It never buffers a full document tree to reflow later. That keeps memory bounded however long the document runs, and makes cost linear in the element count. Each page-break decision is a local predicate over the current cursor and the chosen strategy. So greedy, orphan-avoidance, and keep-together all resolve within the same streaming walk. The trade-off is forward commitment: an over-tall element overflows rather than rescaling, and keep-together holds only when both paired elements share a page.

Design background: High-volume document generation.

API surface

Class	Responsibility
StreamingLayoutEngine	Assign pages and positions to flow elements.
FlowElement, FlowElementType	Element model and type enum.
LayoutRegion	Per-page content area.
PageBreakStrategy	Page-break behavior enum.
LayoutResult, PlacedElement	Placement output.

Code sample — Quick start

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

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

Code sample — Production

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

Edge cases & gotchas

• The engine still places an element taller than the region, but it may overflow; size elements within the region height.
• KeepTogether keeps pairs together only when both fit on one page.
• AvoidOrphans reserves at least two element heights before breaking.

Performance

Layout is linear in the number of elements. The engine is streaming: it does not retain a full document tree.

Security notes

Flow Layout operates on element metadata you supply. It performs no I/O.

Conformance

Flow Layout implements NextPDF placement behavior; it does not target an external layout standard.

Behavior contract

• StreamingLayoutEngine is constructed with a LayoutRegion and a PageBreakStrategy and returns a LayoutResult of placed elements with concrete page and position assignments.
• PageBreakStrategy has three behaviors: Greedy (break when the next element does not fit), AvoidOrphans (break early, reserving at least two element heights), and KeepTogether (honor keep-with-next so paired elements stay on one page when both fit).
• Text and tables can break across pages; images and spacers are placed atomically. An element taller than the region is still placed but may overflow.
• The engine is streaming: it does not retain a full document tree and performs no I/O.
• This is an element-placement engine. It computes page and position assignments; it is not an HTML or CSS rendering engine.

Enterprise boundary note

Enterprise does not change Flow Layout behavior. Enterprise adds higher-tier features documented separately; they are not required to use the placement engine.

Core fallback / alternative

There is no Core element-placement engine with page-break strategies. For HTML-to-PDF rendering, use the open-source Core HTML pipeline. See /modules/html/.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

See also

• Flow Layout — Deep Reference — full class and method reference.
• Document — document assembly.
• Core HTML module — HTML-to-PDF rendering.