Flow Layout

In het kort

NextPDF Pro plaatst een reeks flow-elementen — tekst, afbeeldingen, tabellen, spacers — op pagina’s en wijst elk een concrete pagina en positie toe. Het paginaeindgedrag is selecteerbaar: greedy, orphan-vermijdend of keep-together.

Beschikbaarheid en licentie

Deze functionaliteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelope op Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de functionaliteit niet. Er is geen aparte licentievlag per functie; de Pro-envelope schakelt deze in. Vergelijk edities en vraag een licentie aan.

Installatie

composer require nextpdf/pro:^3

Conceptueel overzicht

De streaming-lay-out-engine neemt een lijst met flow-elementen en een contentregio, doorloopt vervolgens de elementen in volgorde en wijst elk een pagina en positie toe. Wanneer een element niet in de resterende verticale ruimte past, start de engine een nieuwe pagina volgens de geconfigureerde strategie:

• StreamingLayoutEngine — de engine. Geconstrueerd met een LayoutRegion (de contentregio per pagina) en een PageBreakStrategy. Deze retourneert een LayoutResult met geplaatste elementen.
• FlowElement / FlowElementType — het elementmodel. Tekst en tabellen kunnen over pagina’s heen breken; de engine plaatst afbeeldingen en spacers atomair.
• PageBreakStrategy — een enum met drie gedragingen:
  • Greedy — breken zodra het volgende element niet past.
  • AvoidOrphans — vroeg breken wanneer er nog maar weinig ruimte over is, om te voorkomen dat één enkel element bovenaan een nieuwe pagina achterblijft.
  • KeepTogether — de keep-with-next-vlag respecteren zodat gepaarde elementen waar mogelijk op dezelfde pagina blijven.

Flow Layout is een element-plaatsingsengine. Deze berekent pagina- en positietoewijzingen; het is geen HTML- of CSS-renderingengine. Voor HTML-naar-PDF gebruik je de Core HTML-pijplijn.

Waarom het zo werkt

De engine wijst elk element in één voorwaartse pass een pagina en positie toe. Deze buffert nooit een volledige documentboom om later te herflowen. Dat houdt het geheugengebruik begrensd hoe lang het document ook loopt, en maakt de kosten lineair in het aantal elementen. Elke paginaeindbeslissing is een lokaal predicaat over de huidige cursor en de gekozen strategie. Zo worden greedy, orphan-vermijding en keep-together allemaal binnen dezelfde streaming-doorloop opgelost. De afweging is voorwaartse commitment: een te hoog element loopt over in plaats van te herschalen, en keep-together geldt alleen wanneer beide gepaarde elementen dezelfde pagina delen.

Ontwerpachtergrond: High-volume documentgeneratie.

API-oppervlak

Klasse	Verantwoordelijkheid
StreamingLayoutEngine	Pagina’s en posities toewijzen aan flow-elementen.
FlowElement, FlowElementType	Elementmodel en type-enum.
LayoutRegion	Contentregio per pagina.
PageBreakStrategy	Enum voor paginaeindgedrag.
LayoutResult, PlacedElement	Plaatsingsuitvoer.

Codevoorbeeld — Snelstart

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

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

Codevoorbeeld — Productie

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

Randgevallen en valkuilen

• De engine plaatst nog steeds een element dat hoger is dan de regio, maar het kan overlopen; geef elementen een grootte binnen de regiohoogte.
• KeepTogether houdt paren alleen samen wanneer beide op één pagina passen.
• AvoidOrphans reserveert ten minste twee elementhoogtes voordat er wordt gebroken.

Prestaties

De lay-out is lineair in het aantal elementen. De engine is streaming: deze houdt geen volledige documentboom vast.

Beveiligingsnotities

Flow Layout werkt op elementmetadata die jij aanlevert. Deze voert geen I/O uit.

Conformiteit

Flow Layout implementeert NextPDF-plaatsingsgedrag; het richt zich niet op een externe lay-outstandaard.

Gedragscontract

• StreamingLayoutEngine wordt geconstrueerd met een LayoutRegion en een PageBreakStrategy en retourneert een LayoutResult met geplaatste elementen met concrete pagina- en positietoewijzingen.
• PageBreakStrategy heeft drie gedragingen: Greedy (breken wanneer het volgende element niet past), AvoidOrphans (vroeg breken, met reservering van ten minste twee elementhoogtes) en KeepTogether (keep-with-next respecteren zodat gepaarde elementen op één pagina blijven wanneer beide passen).
• Tekst en tabellen kunnen over pagina’s heen breken; afbeeldingen en spacers worden atomair geplaatst. Een element dat hoger is dan de regio wordt nog steeds geplaatst maar kan overlopen.
• De engine is streaming: deze houdt geen volledige documentboom vast en voert geen I/O uit.
• Dit is een element-plaatsingsengine. Deze berekent pagina- en positietoewijzingen; het is geen HTML- of CSS-renderingengine.

Enterprise-grensnotitie

Enterprise verandert het Flow Layout-gedrag niet. Enterprise voegt hoger-niveau functies toe die apart worden gedocumenteerd; ze zijn niet vereist om de plaatsingsengine te gebruiken.

Core-fallback / alternatief

Er is geen Core-element-plaatsingsengine met paginaeindstrategieën. Voor HTML-naar-PDF-rendering gebruik je de open-source Core HTML-pijplijn. Zie /modules/html/.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

• Flow Layout — Deep Reference — volledige klasse- en methodereferentie.
• Document — documentsamenstelling.
• Core HTML module — HTML-naar-PDF-rendering.