Mise en page fluide

En bref

NextPDF Pro place une séquence d’éléments de flux — texte, images, tableaux, espaceurs — sur des pages, en attribuant à chacun une page et une position concrètes. Le comportement de saut de page est sélectionnable : gourmand, évitement des orphelins, ou maintien groupé.

Disponibilité et licence

Cette capacité est livrée dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la capacité. Il n’existe aucun indicateur de licence distinct par fonctionnalité ; c’est l’enveloppe Pro qui l’active. Compare les éditions et obtiens une licence.

Installation

composer require nextpdf/pro:^3

Aperçu conceptuel

Le moteur de mise en page en flux continu prend une liste d’éléments de flux et une région de contenu, puis parcourt les éléments dans l’ordre et attribue à chacun une page et une position. Lorsqu’un élément ne tient pas dans l’espace vertical restant, le moteur démarre une nouvelle page selon la stratégie configurée :

• StreamingLayoutEngine — le moteur. Construit avec une LayoutRegion (la zone de contenu par page) et une PageBreakStrategy. Il renvoie un LayoutResult d’éléments placés.
• FlowElement / FlowElementType — le modèle d’élément. Le texte et les tableaux peuvent se scinder à travers les pages ; le moteur place les images et les espaceurs de façon atomique.
• PageBreakStrategy — une énumération à trois comportements :
  • Greedy — saute dès que l’élément suivant ne tient pas.
  • AvoidOrphans — saute tôt lorsqu’il ne reste qu’un faible espace, afin d’éviter de laisser un élément seul en haut d’une nouvelle page.
  • KeepTogether — honore l’indicateur « garder avec le suivant » pour que les éléments appariés restent sur la même page quand c’est possible.

Flow Layout est un moteur de placement d’éléments. Il calcule des attributions de page et de position ; ce n’est pas un moteur de rendu HTML ou CSS. Pour le HTML-vers-PDF, utilise le pipeline HTML de Core.

Pourquoi ça fonctionne ainsi

Le moteur attribue à chaque élément une page et une position en une seule passe vers l’avant. Il ne met jamais en mémoire tampon un arbre de document complet pour le refluer plus tard. Cela maintient la mémoire bornée quelle que soit la longueur du document, et rend le coût linéaire par rapport au nombre d’éléments. Chaque décision de saut de page est un prédicat local portant sur le curseur courant et la stratégie choisie. Ainsi, gourmand, évitement des orphelins et maintien groupé se résolvent tous au sein du même parcours en flux continu. Le compromis est l’engagement anticipé : un élément trop haut déborde au lieu d’être redimensionné, et le maintien groupé ne tient que lorsque les deux éléments appariés partagent une page.

Contexte de conception : Génération de documents à haut volume.

Surface d’API

Classe	Responsabilité
StreamingLayoutEngine	Attribue pages et positions aux éléments de flux.
FlowElement, FlowElementType	Modèle d’élément et énumération de type.
LayoutRegion	Zone de contenu par page.
PageBreakStrategy	Énumération du comportement de saut de page.
LayoutResult, PlacedElement	Sortie de placement.

Exemple de code — Démarrage rapide

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

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

Exemple de code — Production

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

Cas limites et pièges

• Le moteur place tout de même un élément plus haut que la région, mais il peut déborder ; dimensionne les éléments selon la hauteur de la région.
• KeepTogether ne garde les paires groupées que lorsque les deux tiennent sur une seule page.
• AvoidOrphans réserve au moins deux hauteurs d’élément avant de sauter.

Performance

La mise en page est linéaire par rapport au nombre d’éléments. Le moteur fonctionne en flux continu : il ne conserve pas un arbre de document complet.

Notes de sécurité

Flow Layout opère sur les métadonnées d’élément que tu fournis. Il n’effectue aucune E/S.

Conformité

Flow Layout implémente le comportement de placement de NextPDF ; il ne vise aucune norme de mise en page externe.

Contrat de comportement

• StreamingLayoutEngine est construit avec une LayoutRegion et une PageBreakStrategy et renvoie un LayoutResult d’éléments placés avec des attributions de page et de position concrètes.
• PageBreakStrategy a trois comportements : Greedy (saute quand l’élément suivant ne tient pas), AvoidOrphans (saute tôt en réservant au moins deux hauteurs d’élément) et KeepTogether (honore « garder avec le suivant » pour que les éléments appariés restent sur une page quand les deux tiennent).
• Le texte et les tableaux peuvent se scinder à travers les pages ; les images et les espaceurs sont placés de façon atomique. Un élément plus haut que la région est tout de même placé mais peut déborder.
• Le moteur fonctionne en flux continu : il ne conserve pas un arbre de document complet et n’effectue aucune E/S.
• C’est un moteur de placement d’éléments. Il calcule des attributions de page et de position ; ce n’est pas un moteur de rendu HTML ou CSS.

Note de frontière Enterprise

Enterprise ne change pas le comportement de Flow Layout. Enterprise ajoute des fonctionnalités de niveau supérieur, documentées séparément ; elles ne sont pas requises pour utiliser le moteur de placement.

Repli / alternative Core

Il n’existe aucun moteur de placement d’éléments dans Core avec des stratégies de saut de page. Pour le rendu HTML-vers-PDF, utilise le pipeline HTML open source de Core. Voir /modules/html/.

Périmètre de publication

Cette page ne documente que le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes d’assistance, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de ticket sont hors périmètre.

Voir aussi

• Flow Layout — Référence approfondie — référence complète des classes et méthodes.
• Document — assemblage de documents.
• Module HTML de Core — rendu HTML-vers-PDF.