Pro édition

Table des matières

En bref

NextPDF\Pro\Toc collecte les titres H1–H6 depuis le HTML et rend une table des matières paginée et multi-niveaux sous forme d’opérateurs de flux de contenu PDF. Les numéros de page sont fournis par l’appelant (ou des placeholders séquentiels) ; le module ne résout pas les références croisées de document en temps réel.

Disponibilité et licence

Cette fonctionnalité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement sans cette autorisation ne charge pas les classes de la fonctionnalité. Les classes Toc se chargent dès que nextpdf/pro est installé ; aucun indicateur de capacité d’exécution ne restreint le module. Compare les éditions et obtiens une licence.

Installation

composer require nextpdf/pro:^3

Aperçu conceptuel

Le flux de travail comporte deux phases :

Collecte. AutoTocCollector::extract($html, maxDepth) balaie le HTML à la recherche de balises <h1>–<h6> jusqu’à la limite de profondeur, dépouille le balisage interne, décode les entités, normalise les espaces et émet des objets valeur TocHeading (niveau 0 = H1). Il peut attribuer des numéros de page séquentiels ou appliquer une carte index-vers-page fournie par l’appelant.
Rendu. AutoTocRenderer::render($headings, $config) produit une chaîne de flux de contenu PDF par page de TOC, avec une indentation par niveau, des points de conduite optionnels et des numéros de page optionnels. Chaque ligne visible est émise comme une opération de présentation de texte Tj selon ISO 32000-2:2020 §9.4.

AutoTocConfig est un objet valeur immuable, configuré de façon fluide, contrôlant le titre, la profondeur, les polices, l’espacement, les marges, les couleurs, la taille de page, et le fait que les points de conduite et les numéros de page soient affichés.

Pourquoi ça fonctionne ainsi

La décision structurante est que le module n’invente jamais un numéro de page qu’il ne peut pas connaître. Les vraies pages cibles dépendent du document finalement mis en page, qui appartient à l’appelant ; une supposition dériverait silencieusement à chaque changement de pagination. Ainsi, la collecte et le rendu restent découplés de la mise en page. AutoTocCollector émet des titres avec des pages null ou placeholder ; les vrais numéros de page n’arrivent que via une carte assignPageNumbers() fournie par l’appelant. Le rendu produit ensuite de simples opérateurs de flux de contenu, laissant le placement des pages à l’appelant. Le résultat reste déterministe et honnête : le module déclare ce qu’il ne sait pas plutôt que de le fabriquer.

Contexte de conception : Une API qui refuse de deviner.

Contrat de comportement

Entrée. HTML (collecte) et une liste de TocHeading (rendu).
Sortie. list<TocHeading> issue de la collecte ; list<string> d’opérateurs de flux de contenu PDF (un par page de TOC) issus du rendu.
Numéros de page. Soit attribués séquentiellement, soit fournis via une carte index-vers-page, soit laissés null. Le module ne calcule pas les vraies pages cibles à partir d’un document mis en page ; il ne résout pas les références croisées.
Profondeur. maxDepth est borné à 1–6. Les titres plus profonds que la profondeur configurée sont ignorés.
Déterminisme. Pour un HTML et une configuration identiques, les titres collectés et les opérateurs rendus sont stables.

Surface d’API publique

Type	Genre	Membres clés
`NextPDF\Pro\Toc\AutoTocCollector`	`final class`	`static extract(string $html, int $maxDepth = 6): list<TocHeading>`, `scan(string $html): void`, `assignSequentialPages(int $startPage = 1): list<TocHeading>`, `assignPageNumbers(array $pageMap): list<TocHeading>`
`NextPDF\Pro\Toc\AutoTocRenderer`	`final class`	`static render(array $headings, ?AutoTocConfig $config = null): list<string>`
`NextPDF\Pro\Toc\AutoTocConfig`	`final readonly class`	`default()`, `landscape()`, `letter()`, `withTitle()`, `withMaxDepth()`, `withFontSize()`, `withDotLeader()`, `withPageNumbers()`, `withIndentPerLevel()`, `entriesPerPage(): int`
`NextPDF\Pro\Toc\TocHeading`	`final readonly class`	`string $title`, `int $level`, `?int $pageNumber`, `float $y`, `withPageNumber()`, `withPosition()`, `hasPageNumber(): bool`

Exemple de code — Démarrage rapide

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocRenderer;

$headings = AutoTocCollector::extract($html, maxDepth: 3);
$streams  = AutoTocRenderer::render($headings);

echo count($streams), " TOC page(s) of content-stream operators\n";

Exemple de code — Production

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocConfig;
use NextPDF\Pro\Toc\AutoTocRenderer;

function buildToc(string $html, array $headingPageMap): array
{
    $collector = new AutoTocCollector(maxDepth: 4);
    $collector->scan($html);

    // Caller supplies real page numbers from its own layout pass.
    $headings = $collector->assignPageNumbers($headingPageMap);

    $config = AutoTocConfig::default()
        ->withTitle('Contents')
        ->withMaxDepth(4)
        ->withDotLeader(true)
        ->withPageNumbers(true);

    return AutoTocRenderer::render($headings, $config);
}

Cas limites et pièges

Un texte de titre vide (après le dépouillement des balises) est ignoré.
maxDepth est borné à 1–6 à la fois au niveau du collecteur et de la configuration ; les valeurs hors plage sont corrigées, et non rejetées.
Les numéros de page sont des placeholders à moins que l’appelant ne fournisse une vraie carte ; le module n’exécute pas de passe de mise en page pour découvrir les vraies pages cibles.
Le moteur de rendu émet des opérateurs de flux de contenu pour le placement sur une page ; c’est l’appelant qui est responsable d’ajouter ces pages au document.

Performance

La collecte est une seule passe d’expression régulière sur le HTML. Le rendu est linéaire en nombre de titres, paginé par entriesPerPage(). Voir performance_budget.

Notes de sécurité

Le HTML est balayé avec une expression régulière de titre bornée et un dépouillement de balises ; aucun HTML n’est exécuté et aucune référence externe n’est suivie. Le texte rendu est échappé pour la syntaxe des chaînes de flux de contenu.

Conformité

Affirmation	Clause de spéc	Statut
Lignes de TOC émises comme des opérations de présentation de texte `Tj`	ISO 32000-2:2020 §9.4	Vérifié (suite unitaire)
Résolution de références croisées de document en temps réel	—	Non pris en charge (numéros de page fournis par l’appelant)

Repli / alternative Core

Il n’existe pas de générateur de TOC dans Core. Le HTML source des titres provient typiquement du pipeline HTML de Core. Voir /modules/core/html/.

Note sur la frontière Enterprise

Ce module collecte les titres et rend les opérateurs de TOC. Il n’effectue pas de résolution de références croisées à l’échelle du document, de génération d’index, ni de synchronisation d’arbre de signets ; ces préoccupations sont hors de portée.

Frontière de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’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 tickets sont hors de portée.