Inhoudsopgave

In het kort

NextPDF\Pro\Toc verzamelt H1–H6-headings uit HTML en rendert een gepagineerde inhoudsopgave met meerdere niveaus als PDF content-stream-operatoren. Paginanummers worden door de caller aangeleverd (of zijn sequentiële placeholders); de module resolveert geen live document-cross-references.

Beschikbaarheid en licentie

Deze functionaliteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een license envelope op Pro-niveau. Een deployment zonder dat entitlement laadt de klassen van de functionaliteit niet. De Toc-klassen worden geladen zodra nextpdf/pro is geïnstalleerd; geen runtime-capaciteitsvlag schermt de module af. Vergelijk edities en verkrijg een licentie.

Installatie

composer require nextpdf/pro:^3

Conceptueel overzicht

De workflow heeft twee fasen:

• Verzameling. AutoTocCollector::extract($html, maxDepth) scant de HTML naar <h1>–<h6>-tags tot aan de dieptelimiet, verwijdert inner markup, decodeert entities, normaliseert whitespace en zendt TocHeading-waarde- objecten uit (level 0 = H1). Het kan sequentiële paginanummers toewijzen of een door de caller aangeleverde index-naar-pagina-map toepassen.
• Rendering. AutoTocRenderer::render($headings, $config) produceert één PDF content-stream-string per TOC-pagina, met inspringing per niveau, optionele dot leaders en optionele paginanummers. Elke zichtbare regel wordt uitgezonden als een Tj text-showing-bewerking volgens ISO 32000-2:2020 §9.4.

AutoTocConfig is een onveranderlijk, vloeiend geconfigureerd waarde-object dat titel, diepte, lettertypen, spatiëring, marges, kleuren, paginagrootte en het al dan niet tonen van dot leaders en paginanummers beheert.

Waarom het zo werkt

De dragende beslissing is dat de module nooit een paginanummer verzint dat het niet kan kennen. Echte doelpagina’s hangen af van het uiteindelijk opgemaakte document, dat de caller in bezit heeft; een gok zou stilzwijgend afdrijven zodra de paginering verandert. Daarom blijven verzameling en rendering ontkoppeld van de lay-out. AutoTocCollector zendt headings uit met null- of placeholder-pagina’s; echte paginanummers arriveren alleen via een door de caller aangeleverde assignPageNumbers()-map. Rendering produceert vervolgens gewone content-stream-operatoren en laat de paginaplaatsing aan de caller over. Het resultaat blijft deterministisch en eerlijk: de module vermeldt wat het niet weet in plaats van het te verzinnen.

Ontwerpachtergrond: Een API die weigert te gokken.

Gedragscontract

• Invoer. HTML (verzameling) en een lijst van TocHeading (rendering).
• Uitvoer. list<TocHeading> uit de verzameling; list<string> van PDF content-stream-operatoren (één per TOC-pagina) uit de rendering.
• Paginanummers. Ofwel sequentieel toegewezen, aangeleverd via een index-naar-pagina-map, of null gelaten. De module berekent geen echte doel- pagina’s uit een opgemaakt document; het resolveert geen cross-references.
• Diepte. maxDepth wordt geklemd op 1–6. Headings dieper dan de geconfigureerde diepte worden overgeslagen.
• Determinisme. Voor identieke HTML en configuratie zijn verzamelde headings en gerenderde operatoren stabiel.

Publiek API-oppervlak

Type	Soort	Belangrijkste leden
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

Codevoorbeeld — Snelstart

<?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";

Codevoorbeeld — Productie

<?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);
}

Randgevallen en valkuilen

• Lege heading-tekst (na tag stripping) wordt overgeslagen.
• maxDepth wordt geklemd op 1–6 bij zowel collector als config; waarden buiten bereik worden gecorrigeerd, niet afgewezen.
• Paginanummers zijn placeholders tenzij de caller een echte map aanlevert; de module draait geen lay-outpass om echte doelpagina’s te ontdekken.
• De renderer zendt content-stream-operatoren uit voor plaatsing op een pagina; de caller is verantwoordelijk voor het toevoegen van die pagina’s aan het document.

Prestaties

Verzameling is één reguliere-expressie-pass over de HTML. Rendering is lineair in het aantal headings, gepagineerd door entriesPerPage(). Zie performance_budget.

Beveiligingsnotities

HTML wordt gescand met een begrensde heading-reguliere-expressie en tag stripping; geen HTML wordt uitgevoerd en geen externe referenties worden gevolgd. Gerenderde tekst wordt ge-escaped voor content-stream-stringsyntaxis.

Conformiteit

Claim	Specclausule	Status
TOC-regels uitgezonden als Tj text-showing-bewerkingen	ISO 32000-2:2020 §9.4	Geverifieerd (unit suite)
Live document-cross-reference-resolutie	—	Niet ondersteund (door de caller aangeleverde paginanummers)

Core-fallback / alternatief

Er is geen Core-TOC-generator. De bron-HTML voor headings komt doorgaans uit de Core-HTML-pijplijn. Zie /modules/core/html/.

Enterprise-grensnotitie

Deze module verzamelt headings en rendert TOC-operatoren. Het voert geen documentbrede cross-reference-resolutie, indexgeneratie of bookmark-tree-synchronisatie uit; die zaken vallen buiten de scope.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanisme-tabellen, runbook-bestandsnamen en ticket-prefixes vallen buiten de scope.

Zie ook

• TOC-referentie
• Merge
• Template
• Core-HTML-pijplijn