AST

In sintesi

Il modulo AST trasforma un PDF in un albero del documento immutabile e navigabile. Usa l’albero della struttura taggata quando è presente e ricade su un costruttore euristico per i documenti non taggati, collegando bounding box e testo a ogni nodo.

Disponibilità e licenze

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Non esiste alcun flag di licenza per-funzionalità. Il codice è distribuito con l’edizione Pro; il comportamento di build è governato interamente da AstBuildOptions (limiti di risorse e intervalli di pagine), non da un interruttore di licenza.

Installazione

composer require nextpdf/pro:^3

Il codice risiede sotto il namespace NextPDF\Pro\Ast.

Panoramica concettuale

AstBuilder orchestra la pipeline da PDF ad albero: controlla la cache, rifiuta in anticipo l’input cifrato, legge l’albero della struttura per i PDF taggati, ricade su un percorso non taggato altrimenti, collega i bounding box dall’analisi del content stream, quindi mette in cache il risultato. L’output è un AstDocument i cui nodi sono immutabili; gli aggiornamenti ricostruiscono il sottoalbero interessato dal basso verso l’alto anziché mutare in loco.

Esistono due strategie di fallback per i PDF non taggati: un fallback nudo e un costruttore euristico facoltativo (AstBuildOptions::$useHeuristic). Il modulo fornisce inoltre un percorso emitter che può riscrivere un AST in un PDF e verificare il risultato, oltre a un log delle mutazioni per tracciare le modifiche applicate all’albero.

Perché funziona così

L’albero è immutabile per costruzione. Ogni modifica ricostruisce solo il percorso interessato dalla radice al nodo e condivide per identità i sottoalberi non toccati, così un AstDocument costruito è sicuro da conservare, mettere in cache e passare a lettori concorrenti senza copie difensive. Ciò rispecchia il modo in cui un PDF stesso cambia su disco: il percorso di write-back appende un aggiornamento incrementale tramite AstWriter anziché riscrivere il file, lasciando intatti i byte originali — e qualsiasi firma esistente. Una revisione append-only è anche economica da verificare strutturalmente, ed è per questo che AstWriter può controllare il proprio output prima di restituirlo. Ricostruire i sottoalberi anziché mutare in loco è l’unica decisione che rende il modulo insieme navigabile e modificabile in sicurezza.

Contesto di progettazione: Aggiornamenti incrementali e perché contano.

Contratto di comportamento

• AstBuilder::build($sourceHash) accetta l’intero SHA-256 esadecimale del PDF di origine e restituisce un AstDocument.
• I PDF cifrati sono rifiutati con un errore dedicato di cifratura non supportata; decifrare prima di costruire.
• Quando non è presente alcun albero della struttura, il costruttore usa automaticamente il percorso non taggato — euristico se abilitato, fallback nudo altrimenti.
• I limiti di risorse in AstBuildOptions (nodi massimi, profondità massima, memoria massima, timeout wall-clock) causano un errore di limite di build o di timeout di build anziché un lavoro illimitato.
• La chiave di cache incorpora l’hash di origine e l’hash delle opzioni, così che due build con input e opzioni identici restituiscano lo stesso albero.
• AstNode è immutabile; i consumatori ricevono nuove istanze di nodo quando l’albero cambia.

Esempio di codice — Avvio rapido

Quanto segue riflette l’API pubblica documentata. Il repository non include un esempio eseguibile per questo modulo.

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$builder = new AstBuilder($pdfReader, new AstBuildOptions());
$document = $builder->build($sha256OfPdf);

Esempio di codice — Produzione

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$options = new AstBuildOptions(
    maxNodes: 100_000,
    maxDepth: 200,
    maxMemoryBytes: 256 * 1024 * 1024,
    timeoutSeconds: 30.0,
    useHeuristic: true,
);

$builder = new AstBuilder($pdfReader, $options, $astCache);

try {
    $document = $builder->build($sha256OfPdf);
} catch (\NextPDF\Pro\Ast\Exception\AstUnsupportedEncryptionException $e) {
    // Decrypt the source first, then retry.
}

Casi limite e insidie

• Le pagine il cui content stream non può essere effettuato il parsing vengono saltate durante il collegamento dei bounding box; l’albero viene comunque restituito, solo senza box per quelle pagine.
• Il costruttore euristico è opt-in. Con esso disabilitato, i PDF non taggati producono un albero più grossolano dal fallback nudo.
• L’intervallo di pagine in AstBuildOptions usa indici a base 0, inclusivi; lasciare entrambi i limiti null elabora tutte le pagine.

Prestazioni

Il costo di build scala con il conteggio dei nodi e il conteggio delle pagine; AstBuildOptions limita entrambi. La cache cortocircuita le build ripetute dello stesso input con le stesse opzioni. NextPDF non pubblica qui una tempistica fissa per documento; il timeout wall-clock (predefinito 30 s) e il tetto dei nodi (predefinito 100.000) limitano il lavoro nel caso peggiore. Misurare con documenti rappresentativi.

Note di sicurezza

Trattare l’input come non attendibile. Il costruttore rifiuta i PDF cifrati anziché elaborarli parzialmente. I tetti di risorse (nodi, profondità, memoria, tempo) proteggono contro documenti patologici o ostili. Questo modulo non registra alcun contenuto del documento.

Conformità

Il percorso dell’albero della struttura legge le strutture PDF taggate definite da ISO 32000-2; il sorgente del modulo annota le clausole rilevanti di content stream e di struttura. Poiché il corpus RAG non era disponibile al momento della redazione, questa pagina non asserisce alcun identificatore di clausola esterno e limita le dichiarazioni di conformità al comportamento verificato dai test del modulo.

Nota sul confine Enterprise

Enterprise non modifica il comportamento di AST. Enterprise aggiunge capacità di livello superiore di compliance e archiviazione documentate separatamente; non sono richieste per costruire o consumare un AST.

Fallback / alternativa Core

Senza Pro, non esiste alcun albero del documento equivalente; i chiamanti effettuano il parsing dei content stream direttamente usando le primitive di NextPDF Core. Vedere /modules/ast/.

Confine di pubblicazione

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

Vedere anche

• AST — Riferimento approfondito
• Projection
• Diff
• Output Pipeline