Indice

In breve

NextPDF\Pro\Toc raccoglie le intestazioni H1–H6 dall’HTML e renderizza un sommario impaginato e multilivello come operatori di content stream PDF. I numeri di pagina sono forniti dal chiamante (o sono placeholder sequenziali); il modulo non risolve i riferimenti incrociati live del documento.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con una envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Le classi Toc si caricano ogni volta che nextpdf/pro è installato; nessun flag di capability a runtime applica il gate al modulo. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

Il flusso di lavoro ha due fasi:

• Raccolta. AutoTocCollector::extract($html, maxDepth) esegue la scansione dell’ HTML alla ricerca di tag <h1>–<h6> fino al limite di profondità, rimuove il markup interno, decodifica le entità, normalizza gli spazi ed emette value object TocHeading (level 0 = H1). Può assegnare numeri di pagina sequenziali o applicare una mappa indice-pagina fornita dal chiamante.
• Rendering. AutoTocRenderer::render($headings, $config) produce una stringa di content stream PDF per ciascuna pagina del TOC, con rientro per livello, dot leader opzionali e numeri di pagina opzionali. Ogni riga visibile viene emessa come un’operazione di visualizzazione del testo Tj, secondo ISO 32000-2:2020 §9.4.

AutoTocConfig è un value object immutabile, configurato in modo fluente, che controlla titolo, profondità, font, spaziatura, margini, colori, dimensione della pagina e se i dot leader e i numeri di pagina vengono mostrati.

Perché funziona così

La decisione portante è che il modulo non inventa mai un numero di pagina che non può conoscere. Le pagine target reali dipendono dal documento finale impaginato, di cui il chiamante è proprietario; una supposizione andrebbe silenziosamente alla deriva ogni volta che l’impaginazione cambia. Perciò raccolta e rendering restano disaccoppiati dal layout. AutoTocCollector emette intestazioni con pagine null o placeholder; i numeri di pagina reali arrivano solo tramite una mappa assignPageNumbers() fornita dal chiamante. Il rendering produce quindi semplici operatori di content stream, lasciando il posizionamento delle pagine al chiamante. Il risultato resta deterministico e onesto: il modulo dichiara ciò che non conosce anziché fabbricarlo.

Sfondo progettuale: Un’API che si rifiuta di indovinare.

Contratto di comportamento

• Input. HTML (raccolta) e una lista di TocHeading (rendering).
• Output. list<TocHeading> dalla raccolta; list<string> di operatori di content stream PDF (uno per pagina del TOC) dal rendering.
• Numeri di pagina. Assegnati in modo sequenziale, forniti tramite una mappa indice-pagina, oppure lasciati null. Il modulo non calcola le pagine target reali da un documento impaginato; non risolve i riferimenti incrociati.
• Profondità. maxDepth è limitato a 1–6. Le intestazioni più profonde della profondità configurata vengono saltate.
• Determinismo. Per HTML e configurazione identici, le intestazioni raccolte e gli operatori renderizzati sono stabili.

Superficie API pubblica

Tipo	Genere	Membri chiave
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

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

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

Casi limite e accorgimenti

• Il testo di intestazione vuoto (dopo la rimozione dei tag) viene saltato.
• maxDepth è limitato a 1–6 sia nel collector sia nella config; i valori fuori intervallo vengono corretti, non rifiutati.
• I numeri di pagina sono placeholder a meno che il chiamante non fornisca una mappa reale; il modulo non esegue una passata di layout per individuare le pagine target reali.
• Il renderer emette operatori di content stream per il posizionamento su una pagina; il chiamante è responsabile dell’aggiunta di quelle pagine al documento.

Prestazioni

La raccolta è una singola passata con espressione regolare sull’HTML. Il rendering è lineare nel conteggio delle intestazioni, impaginato da entriesPerPage(). Vedere performance_budget.

Note di sicurezza

L’HTML viene analizzato con un’espressione regolare di intestazione delimitata e la rimozione dei tag; nessun HTML viene eseguito e nessun riferimento esterno viene seguito. Il testo renderizzato è sottoposto a escape per la sintassi delle stringhe del content stream.

Conformità

Asserzione	Clausola della specifica	Stato
Righe del TOC emesse come operazioni di visualizzazione del testo Tj	ISO 32000-2:2020 §9.4	Verificato (suite di unit test)
Risoluzione dei riferimenti incrociati live del documento	—	Non supportato (numeri di pagina forniti dal chiamante)

Fallback / alternativa di Core

Non esiste un generatore di TOC di Core. L’HTML sorgente delle intestazioni proviene tipicamente dalla pipeline HTML di Core. Vedere /modules/core/html/.

Nota sul confine Enterprise

Questo modulo raccoglie le intestazioni e renderizza gli operatori del TOC. Non esegue la risoluzione dei riferimenti incrociati a livello di documento, la generazione di indici o la sincronizzazione dell’albero dei segnalibri; tali aspetti sono fuori ambito.

Confine di pubblicazione

Questa pagina documenta soltanto il comportamento osservabile dall’esterno e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

• Riferimento TOC
• Merge
• Template
• Pipeline HTML di Core