Pro Edition

Inhaltsverzeichnis

Auf einen Blick

NextPDF\Pro\Toc sammelt H1–H6-Überschriften aus HTML und rendert ein paginiertes, mehrstufiges Inhaltsverzeichnis als PDF-Content-Stream-Operatoren. Seitenzahlen werden vom Aufrufer bereitgestellt (oder als sequenzielle Platzhalter); das Modul löst keine Live-Dokument-Querverweise auf.

Verfügbarkeit & Lizenzierung

Diese Funktion wird mit NextPDF Pro (nextpdf/pro) ausgeliefert und aktiviert sich mit einem Lizenzumschlag der Pro-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Die Toc-Klassen werden geladen, sobald nextpdf/pro installiert ist; kein Laufzeit-Capability-Flag gatet das Modul. Editionen vergleichen und Lizenz erwerben.

Installation

composer require nextpdf/pro:^3

Konzeptioneller Überblick

Der Workflow hat zwei Phasen:

Sammlung. AutoTocCollector::extract($html, maxDepth) scannt das HTML nach <h1>–<h6>-Tags bis zur Tiefengrenze, entfernt inneres Markup, dekodiert Entities, normalisiert Whitespace und emittiert TocHeading-Value- Objekte (Ebene 0 = H1). Es kann sequenzielle Seitenzahlen zuweisen oder eine vom Aufrufer bereitgestellte Index-zu-Seite-Map anwenden.
Rendering. AutoTocRenderer::render($headings, $config) erzeugt einen PDF-Content-Stream-String pro TOC-Seite, mit Einrückung pro Ebene, optionalen Dot-Leadern und optionalen Seitenzahlen. Jede sichtbare Zeile wird als Tj-Text-Showing-Operation gemäß ISO 32000-2:2020 §9.4 emittiert.

AutoTocConfig ist ein immutables, fluent konfiguriertes Value Object, das Titel, Tiefe, Schriften, Abstand, Ränder, Farben, Seitengröße und das Anzeigen von Dot- Leadern und Seitenzahlen steuert.

Warum es so funktioniert

Die tragende Entscheidung ist, dass das Modul niemals eine Seitenzahl erfindet, die es nicht kennen kann. Die wahren Zielseiten hängen vom final gelayouteten Dokument ab, das dem Aufrufer gehört; eine Schätzung würde bei jeder Änderung der Paginierung stillschweigend abweichen. Deshalb bleiben Sammlung und Rendering vom Layout entkoppelt. AutoTocCollector emittiert Überschriften mit null- oder Platzhalter-Seiten; echte Seitenzahlen kommen nur über eine vom Aufrufer bereitgestellte assignPageNumbers()-Map. Das Rendering erzeugt dann schlichte Content-Stream-Operatoren und überlässt die Seitenplatzierung dem Aufrufer. Das Ergebnis bleibt deterministisch und ehrlich: Das Modul benennt, was es nicht weiß, anstatt es zu erfinden.

Design-Hintergrund: Eine API, die sich weigert zu raten.

Verhaltensvertrag

Eingabe. HTML (Sammlung) und eine Liste von TocHeading (Rendering).
Ausgabe. list<TocHeading> aus der Sammlung; list<string> von PDF- Content-Stream-Operatoren (einer pro TOC-Seite) aus dem Rendering.
Seitenzahlen. Entweder sequenziell zugewiesen, über eine Index-zu-Seite-Map bereitgestellt oder null gelassen. Das Modul berechnet keine echten Zielseiten aus einem gelayouteten Dokument; es löst keine Querverweise auf.
Tiefe. maxDepth wird auf 1–6 begrenzt. Überschriften, die tiefer als die konfigurierte Tiefe sind, werden übersprungen.
Determinismus. Für identisches HTML und identische Konfiguration sind gesammelte Überschriften und gerenderte Operatoren stabil.

Öffentliche API-Oberfläche

Typ	Art	Wichtige Mitglieder
`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`

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

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

Sonderfälle & Fallstricke

Leerer Überschriftentext (nach dem Tag-Stripping) wird übersprungen.
maxDepth wird sowohl beim Collector als auch in der Config auf 1–6 begrenzt; Werte außerhalb des Bereichs werden korrigiert, nicht abgelehnt.
Seitenzahlen sind Platzhalter, sofern der Aufrufer keine echte Map bereitstellt; das Modul führt keinen Layout-Durchlauf durch, um echte Zielseiten zu ermitteln.
Der Renderer emittiert Content-Stream-Operatoren zur Platzierung auf einer Seite; der Aufrufer ist dafür verantwortlich, diese Seiten dem Dokument hinzuzufügen.

Performance

Die Sammlung ist ein einzelner Durchlauf eines regulären Ausdrucks über das HTML. Das Rendering ist linear in der Überschriftenanzahl, paginiert durch entriesPerPage(). Siehe performance_budget.

Sicherheitshinweise

HTML wird mit einem begrenzten Heading-regulären-Ausdruck und Tag-Stripping gescannt; es wird kein HTML ausgeführt und keinen externen Referenzen wird gefolgt. Gerenderter Text wird für die Content-Stream-String-Syntax escaped.

Konformität

Anspruch	Spec-Klausel	Status
TOC-Zeilen als `Tj`-Text-Showing-Operationen emittiert	ISO 32000-2:2020 §9.4	Verifiziert (Unit-Suite)
Auflösung von Live-Dokument-Querverweisen	—	Nicht unterstützt (vom Aufrufer bereitgestellte Seitenzahlen)

Core-Fallback / Alternative

Es gibt keinen Core-TOC-Generator. Das Quell-HTML der Überschriften stammt typischerweise aus der Core-HTML-Pipeline. Siehe /modules/core/html/.

Hinweis zur Enterprise-Grenze

Dieses Modul sammelt Überschriften und rendert TOC-Operatoren. Es führt keine dokumentweite Querverweisauflösung, keine Indexerzeugung und keine Bookmark-Tree-Synchronisierung durch; diese Anliegen liegen außerhalb des Umfangs.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.