Table des matières — Référence approfondie

En un coup d’œil

Cette page est la référence de niveau contractuel du module Toc de NextPDF Pro, NextPDF\Pro\Toc. AutoTocCollector analyse le HTML à la recherche des titres H1–H6 et émet des objets de valeur TocHeading. AutoTocRenderer pagine ces titres et rend chaque page de table des matières sous forme d’opérateurs de flux de contenu PDF. AutoTocConfig est la configuration de rendu immuable. Les numéros de page sont fournis par l’appelant ou sont des marqueurs séquentiels ; le module ne résout pas les renvois vivants du document. Cette page énonce l’API publique, le contrat de comportement observable et les modes de défaillance. La configuration orientée tâches et les exemples se trouvent sur la page de capacité Table des matières.

Disponibilité et licence

Cette capacité est fournie 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é. Comparez les éditions et obtenez une licence.

Aucun indicateur de capacité d’exécution ne verrouille ce module. Les classes Toc sont utilisables dès que nextpdf/pro est installé et sous licence.

Surface de l’API publique

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
AutoTocCollector::__construct()	int $maxDepth = 6	Restreint la profondeur à la plage 1–6	—	—	L’instance accumule les titres collectés
AutoTocCollector::extract()	string $html, int $maxDepth = 6	Construit, analyse et retourne les titres en un seul appel	list<TocHeading>	—	Chemin rapide statique
AutoTocCollector::scan()	string $html	Correspond aux H1–H6, retire le balisage, décode les entités, réduit les espaces, ajoute les titres non vides	—	—	Modifie l’état interne
AutoTocCollector::assignSequentialPages()	int $startPage = 1	Avance la page à chaque titre de niveau 0 après le premier	list<TocHeading>	—	Numérotation par marqueurs uniquement
AutoTocCollector::assignPageNumbers()	array<int,int> $pageMap	Applique une correspondance index-vers-page ; les index non mappés conservent leur page actuelle	list<TocHeading>	—	Pages réelles fournies par l’appelant
AutoTocCollector::getHeadings()	—	Retourne les titres collectés	list<TocHeading>	—	—
AutoTocCollector::count()	—	Nombre de titres collectés	int	—	—
AutoTocCollector::reset()	—	Efface les titres collectés	—	—	Réutilise le collecteur entre les analyses
AutoTocRenderer::render()	list<TocHeading> $headings, ?AutoTocConfig $config = null	Filtre par profondeur, pagine, émet un flux de contenu par page	list<string>	—	Retourne [] lorsque tous les titres sont filtrés
AutoTocConfig::__construct()	14 paramètres typés (titre, profondeur, polices, espacement, marges, couleurs, taille de page)	Porteur de configuration immuable	—	—	Readonly ; les couleurs ChartColor par défaut sont noires
AutoTocConfig::default(), ::landscape(), ::letter()	—	Préréglages A4 portrait, A4 paysage et US Letter	self	—	Fabriques statiques
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()	une valeur chacune	Retourne une nouvelle instance avec le champ modifié ; withMaxDepth() restreint à 1–6	self	—	Fluide, non mutant
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	Dérivé
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	Dérivé
AutoTocConfig::entriesPerPage()	—	max(1, floor((pageHeight - 2*topMargin - 2*titleFontSize) / lineSpacing))	int	—	Toujours ≥ 1
TocHeading::__construct()	string $title, int $level, ?int $pageNumber = null, float $y = 0.0	Objet de valeur de titre immuable	—	—	Readonly ; niveau 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	numéro de page et/ou coordonnée Y	Retourne une nouvelle instance avec les champs de position modifiés	self	—	Fluide, non mutant
TocHeading::hasPageNumber()	—	Vrai lorsqu’un numéro de page est attribué	bool	—	—

public function __construct(int $maxDepth = 6)

public static function extract(string $html, int $maxDepth = 6): array

public function scan(string $html): void

public function assignSequentialPages(int $startPage = 1): array

public function assignPageNumbers(array $pageMap): array

public static function render(
    array $headings,
    ?AutoTocConfig $config = null,
): array

public function __construct(
    public string $title = 'Table of Contents',
    public int $maxDepth = 6,
    public float $fontSize = 10.0,
    public float $titleFontSize = 16.0,
    public float $indentPerLevel = 15.0,
    public float $lineHeight = 1.6,
    public bool $showPageNumbers = true,
    public bool $showDotLeader = true,
    public ChartColor $textColor = new ChartColor(0.0, 0.0, 0.0),
    public ChartColor $titleColor = new ChartColor(0.0, 0.0, 0.0),
    public float $leftMargin = 40.0,
    public float $topMargin = 50.0,
    public float $pageWidth = 595.28,
    public float $pageHeight = 841.89,
)

public function entriesPerPage(): int

public function __construct(
    public string $title,
    public int $level,
    public ?int $pageNumber = null,
    public float $y = 0.0,
)

public function withPageNumber(int $pageNumber): self

public function hasPageNumber(): bool

Contrat de comportement

Collecte

AutoTocCollector::scan() correspond à <h1>–<h6> avec un motif borné (insensible à la casse, le point correspondant au saut de ligne) qui exige une balise ouvrante et fermante équilibrée du même niveau. Le contenu intérieur de chaque correspondance est débalisé, ses entités décodées (ENT_QUOTES | ENT_HTML5, UTF-8) et ses espaces réduits. Les résultats vides sont écartés. level est le numéro de balise moins un, si bien que H1 est le niveau 0. Une balise plus profonde que maxDepth est ignorée. extract() est la fabrique en un appel couvrant la construction, l’analyse et la relecture.

Attribution des numéros de page

Deux stratégies explicites existent, toutes deux pilotées par l’appelant.

• assignSequentialPages($startPage) fait avancer le compteur de page lorsqu’un titre de niveau 0 est atteint après la première entrée, puis estampille chaque titre.
• assignPageNumbers($pageMap) applique une correspondance index-vers-page ; un index non mappé conserve son numéro de page existant.

Aucune des deux stratégies n’inspecte un document mis en page.

Rendu et pagination

AutoTocRenderer::render() conserve les titres dont le level est inférieur à maxDepth, retourne [] lorsqu’il n’en survit aucun, puis scinde le reste en blocs de AutoTocConfig::entriesPerPage(). Chaque bloc devient une chaîne de flux de contenu. Par entrée, l’indentation est leftMargin + level * indentPerLevel ; la taille de police diminue de 0,5 pt par niveau et est plafonnée à 6,0 pt ; le niveau 0 utilise la clé de police grasse, les niveaux plus profonds la clé régulière. Lorsque les numéros de page sont activés et présents, un guide de points optionnel comble l’espace et le numéro est aligné à droite. Le titre et chaque chaîne d’entrée sont affichés avec l’opérateur Tj conformément à ISO 32000-2:2020 §9.4, et chaque chaîne est échappée selon la syntaxe des chaînes littérales PDF conformément au §7.3.4.2. Un HTML et une configuration identiques produisent des titres et des opérateurs stables.

Cas limites et modes de défaillance

• Un balisage de titre mal formé n’est pas collecté. Un <h2> non fermé sans </h2> correspondant échoue au motif de paire équilibrée et est ignoré.
• Un texte de titre vide après débalisage et découpage est écarté.
• maxDepth est restreint à 1–6 à la fois au constructeur du collecteur et dans AutoTocConfig::withMaxDepth() ; les valeurs hors plage sont corrigées, non rejetées.
• Les numéros de page sont contrôlés par l’appelant. Aucune passe de mise en page interne ne découvre la page réelle où atterrit un titre, si bien que le module ne peut pas résoudre les renvois vivants.
• Le module ne lève aucune exception. render() retourne un tableau vide lorsque tous les titres sont filtrés par profondeur ; il ne lève jamais sur une entrée vide.
• Le dimensionnement retombe sur le plancher max(1, …), si bien que entriesPerPage() vaut toujours au moins 1 et que la pagination progresse toujours.
• Le moteur de rendu produit uniquement des opérateurs dessinables. L’appelant place les flux retournés sur des pages réelles et fournit les ressources /TocFont, /TocBoldFont et /TocTitleFont.

Comportement en mode FIPS

Aucune opération cryptographique n’a lieu dans ce module, donc aucun comportement spécifique au mode FIPS n’existe. Rien ici ne consomme d’aléa, de hachage ou de signature.

Conformité

Affirmation	Norme	Clause
Titre de la table des matières et texte des entrées affichés avec l’opérateur de rendu de texte Tj	ISO 32000-2:2020	§9.4
Chaînes émises échappées en tant que chaînes littérales PDF, avec la barre oblique inverse doublée et les parenthèses échappées	ISO 32000-2:2020	§7.3.4.2
Arbre PDF /Outlines ou liens vers destinations nommées	—	Non construit (opérateurs de flux de contenu uniquement)
Résolution des renvois vivants du document	—	Non prise en charge (numéros de page fournis par l’appelant)

Toutes les clauses sont paraphrasées ; NextPDF ne reproduit pas le texte normatif. Ce sont des énoncés de capacité, non des certifications ; NextPDF ne détient aucune certification et n’en accorde aucune.

Notes de développement

• Disponibilité au sein du paquet Pro : AutoTocCollector, AutoTocRenderer, AutoTocConfig et TocHeading depuis 1.9.0. Tous sont à jour dans nextpdf/pro 3.1.0.
• Les couleurs d’AutoTocConfig sont des valeurs NextPDF\Pro\Chart\ChartColor. Les couleurs de texte et de titre par défaut sont noires (0.0, 0.0, 0.0).
• Partez de AutoTocConfig::default(), ::landscape() ou ::letter(), puis chaînez les withers. L’objet est en lecture seule, si bien que chaque wither retourne une nouvelle instance.
• Attribuez de vrais numéros de page avec assignPageNumbers() depuis votre propre passe de mise en page ; assignSequentialPages() ne fournit que des marqueurs.
• entriesPerPage(), lineSpacing() et contentWidth() sont des dérivations pures de la configuration ; appelez-les pour prédimensionner la mise en page avant le rendu.
• getHeadings(), count() et reset() lisent et effacent l’état accumulé du collecteur entre les analyses.

Limite de publication

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

Voir aussi

• Table des matières (capacité) — installation, démarrage rapide et exemples de production.
• Merge — Référence approfondie
• Template — Référence approfondie