AST — Riferimento approfondito

In sintesi

Questa pagina è il riferimento approfondito per il modulo AST di Pro. Copre le superfici pubbliche di build, cache, mutazione, scrittura ed emissione, i loro contratti di comportamento e le loro modalità di errore. Il modulo analizza un PDF caricato in un albero AstDocument immutabile, applica mutazioni in memoria registrate e scrive aggiornamenti incrementali basati su overlay. AstDocument e AstNode sono tipi valore di Core nel namespace NextPDF\Ast; questo modulo li produce e li consuma.

Disponibilità e licenza

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

Non esiste alcun flag di licenza per singola funzionalità. Questa è una funzionalità dell’edizione Pro. Il comportamento di build è governato interamente da AstBuildOptions.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
AstBuilder::__construct	PdfReader $reader, AstBuildOptions $options, ?AstCache $cache = null	Associa un reader caricato alle opzioni di build; la cache è facoltativa	AstBuilder	—	Una cache null significa che ogni chiamata a build() ricostruisce.
AstBuilder::build	string $sourceHash (SHA-256 esadecimale completo dei byte del PDF)	Ricerca in cache, rifiuto della cifratura, percorso dell’albero di struttura, fallback non taggato, attacco dei bounding box, memorizzazione in cache	AstDocument	AstUnsupportedEncryptionException, AstBuildLimitException, AstBuildTimeoutException	Un hit di cache restituisce senza rieseguire l’analisi.
AstBuildOptions::__construct	?int $pageRangeStart = null, ?int $pageRangeEnd = null, int $maxNodes = 100_000, int $maxDepth = 200, ?int $estimatedTokenBudget = null, int $maxMemoryBytes = 268435456, float $timeoutSeconds = 30.0, bool $useHeuristic = false	Oggetto valore di configurazione immutabile	AstBuildOptions	—	estimatedTokenBudget è un suggerimento informativo; non viene applicato.
AstBuildOptions::pageRangeContains	int $pageIndex	Vero quando l’indice a base 0 ricade nell’intervallo configurato	bool	—	I limiti null sono aperti; entrambi null significa tutte le pagine.
AstBuildOptions::hash	—	SHA-256 stabile su tutti i valori delle opzioni	string	—	Valori uguali producono hash uguali tra istanze; usato come segmento della chiave di cache.
AstCache::__construct	CacheInterface $backend	Incapsula qualsiasi backend PSR-16	AstCache	—	—
AstCache::buildKey	string $sourceHash, AstBuildOptions $options	Chiave = nextpdf_ast_v1_ + primi 32 esadecimali dell’hash di origine + _ + primi 16 esadecimali dell’hash delle opzioni	string	—	Le modifiche alle opzioni invalidano automaticamente i risultati in cache.
AstCache::get	string $cacheKey	Decodifica un payload JSON tramite validazione stretta campo per campo	?AstDocument	Non solleva mai; i fallimenti restituiscono null	Payload malformati o manomessi falliscono in modo chiuso come cache miss.
AstCache::set	string $cacheKey, AstDocument $document	Memorizza JSON con un TTL di 24 ore, poi verifica con una rilettura immediata	void	AstWriteVerificationException (namespace Exception)	Un fallimento di scrittura del backend o un round-trip fallito solleva.
AstCache::delete	string $cacheKey	Rimozione best-effort	void	Non solleva mai	I fallimenti di eliminazione del backend vengono ignorati.
AstCache::has	string $cacheKey	Controllo di esistenza best-effort	bool	Non solleva mai; i fallimenti restituiscono false	—
AstMutator::updateNode	AstDocument $document, string $nodeId, array $updates	Sostituisce text_content, registra una voce Updated	AstDocument (nuova istanza)	InvalidArgumentException	Viene applicata solo la chiave text_content; le chiavi sconosciute vengono ignorate.
AstMutator::deleteNode	AstDocument $document, string $nodeId	Rimuove il nodo dall’albero in memoria, registra una voce Deleted	AstDocument (nuova istanza)	InvalidArgumentException	Solo rimozione in memoria; vedere l’avvertenza sull’oscuramento più sotto.
AstMutator::getMutationLog	—	Restituisce l’istanza condivisa del log	MutationLog	—	Passare lo stesso log ad AstWriter.
AstMutator::resetLog	—	Scarta tutte le mutazioni registrate	void	—	Avvia un log nuovo.
MutationLog	record, all, isEmpty, count, forNode, mutatedNodeIds	Log in memoria append-only, ordine di inserimento preservato	per metodo	—	forNode restituisce la voce più recente per un nodo; vince l’ultima voce.
MutationEntry::__construct	string $nodeId, MutationType $type, ?AstNode $originalNode, ?AstNode $mutatedNode, DateTimeImmutable $timestamp	Record immutabile di una mutazione	MutationEntry	—	originalNode è null per Inserted; mutatedNode è null per Deleted.
MutationType	casi enum Updated, Inserted, Deleted	Classificazione basata su stringa	—	—	Deleted in modalità OVERLAY nasconde il contenuto; non cancella i byte.
AstWriter::write	string $originalPdfBytes, MutationLog $log	Aggiunge un aggiornamento incrementale i cui overlay stream coprono i bounding box mutati	string (byte PDF modificati)	AstWriteException	Un log vuoto restituisce l’input invariato. Le voci Inserted e le voci senza bounding box vengono saltate.
AstWriter::writeAndVerify	string $originalPdfBytes, MutationLog $log	Esegue write(), poi un controllo strutturale dell’output	string (byte PDF verificati)	AstWriteException, AstWriteVerificationException (namespace Writer)	La verifica è strutturale, non semantica.
AstPdfEmitter::emit	AstNode $root, BinaryBuffer $buffer, ObjectRegistry $registry, array $pageObjects	Scrive uno StructTreeRoot, una catena StructElem e un ParentTree per l’albero fornito	EmitResult	AstEmitException	La radice deve essere un nodo Document con figli. Emitter di round-trip per la verifica dell’albero di struttura.
EmitResult::__construct	int $structTreeRootObject, int $rootElementObject, int $parentTreeObject, int $elementObjectCount, int $parentTreeNextKey	Record immutabile degli identificatori di oggetto emessi	EmitResult	—	—

public function build(string $sourceHash): AstDocument

public function updateNode(AstDocument $document, string $nodeId, array $updates): AstDocument
public function deleteNode(AstDocument $document, string $nodeId): AstDocument

public function write(string $originalPdfBytes, MutationLog $log): string
public function writeAndVerify(string $originalPdfBytes, MutationLog $log): string

Gerarchia delle eccezioni

• NextPDF\Pro\Ast\Exception\AstException estende RuntimeException — base della gerarchia di build.
• AstBuildLimitException estende AstException — è stato superato un tetto di nodi, profondità o memoria.
• AstBuildTimeoutException estende AstBuildLimitException — è trascorso il timeout di build a tempo di orologio.
• AstNoStructTreeException estende AstException — nessun albero di struttura presente. AstBuilder::build() la intercetta internamente e ricorre al fallback; i chiamanti di build() non la osservano.
• AstUnsupportedEncryptionException estende AstException — il PDF di input è cifrato.
• NextPDF\Pro\Ast\Exception\AstWriteVerificationException estende AstException — la verifica di scrittura in cache è fallita.
• NextPDF\Pro\Ast\Writer\AstWriteException estende RuntimeException — fallimento di input o di struttura del writer.
• NextPDF\Pro\Ast\Writer\AstWriteVerificationException estende AstWriteException — la verifica strutturale post-scrittura è fallita.

Esistono due classi AstWriteVerificationException distinte in namespace differenti. AstCache::set() solleva la classe del namespace Exception; AstWriter::writeAndVerify() solleva la classe del namespace Writer. Abbinare il namespace nelle clausole catch.

Contratto di comportamento

AstBuilder::build($sourceHash) richiede l’SHA-256 esadecimale completo dei byte di origine. La pipeline è: ricerca facoltativa in cache, rifiuto della cifratura, percorso dell’albero di struttura, fallback non taggato, attacco dei bounding box, memorizzazione facoltativa in cache.

La chiave di cache combina l’hash di origine con l’hash di AstBuildOptions. L’hash delle opzioni è stabile tra istanze con valori identici, così che input e opzioni identici restituiscano lo stesso albero. Quando non viene fornita alcuna cache, ogni chiamata ricostruisce. I payload in cache sono JSON, mai serializzazione PHP nativa: il percorso di lettura valida ogni campo e istanzia solo tipi valore AST, così che una voce di cache avvelenata non possa innescare object injection e degradi a un cache miss.

Il percorso dell’albero di struttura viene eseguito quando è presente un albero di struttura. I tetti delle risorse — numero di nodi, profondità, delta di memoria e tempo a orologio — vengono applicati durante la lettura dell’albero di struttura e sollevano AstBuildLimitException o AstBuildTimeoutException. Se il reader segnala l’assenza di un albero di struttura, il builder passa al percorso non taggato: il builder euristico quando useHeuristic è true, altrimenti il builder di fallback essenziale. I bounding box vengono attaccati analizzando il content stream di ciascuna pagina nell’intervallo; una pagina il cui content stream non può essere analizzato viene saltata e lascia intatto il resto dell’albero.

AstNode è immutabile. Gli aggiornamenti dell’albero ricostruiscono i nodi interessati dal basso verso l’alto; i sottoalberi invariati sono restituiti per identità. AstMutator segue lo stesso contratto: ogni mutazione restituisce un nuovo AstDocument, ricostruisce solo il percorso dalla radice al target e registra una MutationEntry nel MutationLog condiviso.

AstWriter applica un MutationLog in modalità OVERLAY come aggiornamento incrementale append-only: nuovi overlay content stream, oggetti pagina aggiornati, una sezione di riferimenti incrociati che copre solo i nuovi oggetti e un trailer il cui /Prev punta al startxref precedente. I byte originali restano intatti, secondo il modello di aggiornamento incrementale di ISO 32000-2:2020, 7.5.6. Il testo di sostituzione disegnato per le voci Updated fa l’escape di \, ( e ) nelle stringhe letterali, secondo ISO 32000-2:2020, 7.3.4.2.

AstPdfEmitter::emit() è l’inverso simmetrico della lettura dell’albero di struttura: gli alberi prodotti dal reader fanno round-trip verso alberi strutturalmente equivalenti, a meno della rinumerazione dei node-id e delle classi di canonicalizzazione documentate. Gli MCID presenti sui nodi vengono riemessi verbatim, mai riallocati.

Casi limite e modalità di errore

• L’input cifrato viene rifiutato prima di qualsiasi lavoro sull’albero; non esiste un risultato di albero parziale per i PDF cifrati. Decifrare prima.
• Tetti delle risorse: numero massimo di nodi (predefinito 100.000), profondità massima (predefinita 200), memoria massima (predefinita 256 MiB), timeout a tempo di orologio (predefinito 30 s). Il superamento di un tetto solleva AstBuildLimitException; il timeout solleva AstBuildTimeoutException, una sottoclasse.
• L’intervallo di pagine è a base 0 e inclusivo; limiti null indicano tutte le pagine.
• Una pagina il cui content stream non può essere analizzato viene saltata durante l’attacco dei bounding box; il resto dell’albero non ne risente.
• AstCache::get() non solleva mai: payload malformati, manomessi o non stringa restituiscono null e forzano una ricostruzione. AstCache::set() fallisce in modo esplicito quando la scrittura del backend o la rilettura immediata falliscono.
• AstMutator solleva InvalidArgumentException quando il node id non viene trovato. Le chiavi di aggiornamento sconosciute vengono ignorate silenziosamente; viene applicata solo text_content.
• AstWriter::write() solleva AstWriteException quando l’input manca di un’intestazione %PDF- o di un startxref localizzabile. Le voci senza bounding box vengono saltate silenziosamente. Le pagine che non possono essere localizzate tramite scansione degli oggetti — per esempio con flussi di riferimenti incrociati compressi — vengono saltate; se non è possibile applicare alcun overlay, i byte di input vengono restituiti invariati.
• L’output OVERLAY non è oscuramento. Il rettangolo bianco e il testo ridisegnato vengono aggiunti; i byte di contenuto originali rimangono nel file e sono recuperabili tramite estrazione grezza. Non usarlo per la cancellazione ai sensi dell’art. 17 GDPR o per l’oscuramento legale. Un writer in modalità reconstruct esiste nell’albero dei sorgenti ma è marcato come interno, non è pronto per la produzione ed è al di fuori della superficie API supportata.
• La geometria dell’overlay assume A4 verticale (595 x 842 pt) perché il writer non legge il MediaBox della pagina. Su pagine non A4 l’overlay può risultare leggermente disallineato; l’output rimane strutturalmente valido.
• writeAndVerify() controlla solo la struttura: intestazione, %%EOF finale e crescita dell’output. Non rianalizza semanticamente il documento mutato.
• AstPdfEmitter::emit() solleva AstEmitException quando la radice non è un nodo Document o non ha figli. In questa release le voci companion OBJR (annotazioni) non vengono emesse.
• Questo modulo non esegue alcuna operazione crittografica e non definisce alcun comportamento specifico per FIPS. SHA-256 compare solo come indirizzamento per contenuto per le chiavi di cache.

Conformità

Il percorso dell’albero di struttura legge le funzionalità di struttura logica del PDF taggato definite da ISO 32000-2; il corpus RAG disponibile al momento della stesura non include le clausole di struttura logica, quindi tale affermazione è fondata sul prodotto a partire dalle annotazioni della sorgente. Il layout di aggiornamento incrementale del writer segue ISO 32000-2:2020, 7.5.6 (citato sotto), e il suo escape delle stringhe letterali segue ISO 32000-2:2020, 7.3.4.2 (citato sotto).

Queste affermazioni descrivono la capacità rispetto alle clausole citate. NextPDF non detiene alcuna certificazione di conformità, e il supporto di una clausola non costituisce una dichiarazione di certificazione.

Note di sviluppo

• Comporre un AstBuilder per ogni PdfReader caricato. Riutilizzare un AstCache tra le build per ammortizzare l’analisi; il design della chiave rende le modifiche alle opzioni auto-invalidanti.
• Condividere un unico MutationLog tra un AstMutator e l’AstWriter affinché il writer applichi esattamente la sessione registrata. Chiamare resetLog() tra sessioni di editing indipendenti.
• Impostare useHeuristic a true per i documenti non taggati quando il raggruppamento derivato dal layout è preferibile all’albero di fallback essenziale.
• Le build sono deterministiche per byte e opzioni identici; fare affidamento su questo per test in stile snapshot.
• Intercettare i fallimenti di build tramite la gerarchia NextPDF\Pro\Ast\Exception e i fallimenti di scrittura tramite la gerarchia NextPDF\Pro\Ast\Writer; le due non condividono una base al di sotto di RuntimeException.

Confine di pubblicazione

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

Vedere anche

• AST — panoramica della funzionalità
• Projection — Riferimento approfondito
• Output Pipeline — Riferimento approfondito