AST — Diepe referentie

In het kort

Deze pagina is de diepe referentie voor de Pro AST-module. Ze behandelt de publieke build-, cache-, mutatie-, write- en emit-oppervlakken, hun gedragscontracten en hun faalmodi. De module parseert een geladen PDF tot een onveranderlijke AstDocument-boom, past gelogde in-memory-mutaties toe en schrijft overlay-gebaseerde incrementele updates. AstDocument en AstNode zijn Core-waardetypen in de NextPDF\Ast-namespace; deze module produceert en consumeert ze.

Beschikbaarheid en licentie

Deze mogelijkheid wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een licentie-envelop op Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de mogelijkheid niet. Vergelijk edities en vraag een licentie aan.

Er bestaat geen per-feature licentie-flag. Dit is een mogelijkheid op Pro-editieniveau. Het build-gedrag wordt volledig geregeld door AstBuildOptions.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
AstBuilder::__construct	PdfReader $reader, AstBuildOptions $options, ?AstCache $cache = null	Bindt een geladen reader aan build-opties; caching is optioneel	AstBuilder	—	Een null-cache betekent dat elke build()-aanroep herbouwt.
AstBuilder::build	string $sourceHash (volledige SHA-256-hex van de PDF-bytes)	Cache-lookup, encryptieafwijzing, structuurboom-pad, untagged fallback, bounding-box-koppeling, cache-opslag	AstDocument	AstUnsupportedEncryptionException, AstBuildLimitException, AstBuildTimeoutException	Een cache-hit retourneert zonder opnieuw te parseren.
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	Onveranderlijk configuratie-waardeobject	AstBuildOptions	—	estimatedTokenBudget is een informatieve hint; het wordt niet afgedwongen.
AstBuildOptions::pageRangeContains	int $pageIndex	Waar wanneer de 0-gebaseerde index binnen het geconfigureerde bereik valt	bool	—	Null-grenzen zijn open-eindig; beide null betekent alle pagina’s.
AstBuildOptions::hash	—	Stabiele SHA-256 over alle optiewaarden	string	—	Gelijke waarden leveren gelijke hashes op over instances heen; gebruikt als het cache-sleutelsegment.
AstCache::__construct	CacheInterface $backend	Omhult elke PSR-16-backend	AstCache	—	—
AstCache::buildKey	string $sourceHash, AstBuildOptions $options	Sleutel = nextpdf_ast_v1_ + eerste 32 hex van de bron-hash + _ + eerste 16 hex van de options-hash	string	—	Optiewijzigingen invalideren gecachte resultaten automatisch.
AstCache::get	string $cacheKey	Decodeert een JSON-payload via strikte per-veld-validatie	?AstDocument	Werpt nooit; fouten retourneren null	Misvormde of gemanipuleerde payloads falen closed als een cache-miss.
AstCache::set	string $cacheKey, AstDocument $document	Slaat JSON op met een TTL van 24 uur, verifieert daarna met een onmiddellijke terugleesactie	void	AstWriteVerificationException (Exception-namespace)	Een schrijffout van de backend of een mislukte round-trip werpt.
AstCache::delete	string $cacheKey	Best-effort-verwijdering	void	Werpt nooit	Verwijderfouten van de backend worden ingeslikt.
AstCache::has	string $cacheKey	Best-effort-bestaanscontrole	bool	Werpt nooit; fouten retourneren false	—
AstMutator::updateNode	AstDocument $document, string $nodeId, array $updates	Vervangt text_content, registreert een Updated-entry	AstDocument (nieuwe instance)	InvalidArgumentException	Alleen de sleutel text_content wordt toegepast; onbekende sleutels worden genegeerd.
AstMutator::deleteNode	AstDocument $document, string $nodeId	Verwijdert de node uit de in-memory-boom, registreert een Deleted-entry	AstDocument (nieuwe instance)	InvalidArgumentException	Alleen verwijdering in-memory; zie het redactie-voorbehoud hieronder.
AstMutator::getMutationLog	—	Retourneert de gedeelde log-instance	MutationLog	—	Geef dezelfde log door aan AstWriter.
AstMutator::resetLog	—	Verwerpt alle geregistreerde mutaties	void	—	Start een verse log.
MutationLog	record, all, isEmpty, count, forNode, mutatedNodeIds	Append-only in-memory-log, invoegvolgorde behouden	per methode	—	forNode retourneert de meest recente entry voor een node; de laatste entry wint.
MutationEntry::__construct	string $nodeId, MutationType $type, ?AstNode $originalNode, ?AstNode $mutatedNode, DateTimeImmutable $timestamp	Onveranderlijk record van één mutatie	MutationEntry	—	originalNode is null voor Inserted; mutatedNode is null voor Deleted.
MutationType	enum-cases Updated, Inserted, Deleted	String-backed classificatie	—	—	Deleted onder OVERLAY verbergt content; het wist geen bytes.
AstWriter::write	string $originalPdfBytes, MutationLog $log	Voegt een incrementele update toe waarvan de overlay-streams de gemuteerde bounding boxes dekken	string (gewijzigde PDF-bytes)	AstWriteException	Een lege log retourneert de invoer ongewijzigd. Inserted-entries en entries zonder bounding box worden overgeslagen.
AstWriter::writeAndVerify	string $originalPdfBytes, MutationLog $log	Draait write(), daarna een structurele uitvoercontrole	string (geverifieerde PDF-bytes)	AstWriteException, AstWriteVerificationException (Writer-namespace)	Verificatie is structureel, niet semantisch.
AstPdfEmitter::emit	AstNode $root, BinaryBuffer $buffer, ObjectRegistry $registry, array $pageObjects	Schrijft een StructTreeRoot, StructElem-keten en ParentTree voor de aangeleverde boom	EmitResult	AstEmitException	De root moet een Document-node met kinderen zijn. Round-trip-emitter voor structuurboom-verificatie.
EmitResult::__construct	int $structTreeRootObject, int $rootElementObject, int $parentTreeObject, int $elementObjectCount, int $parentTreeNextKey	Onveranderlijk record van de geëmitteerde object-identifiers	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

Uitzonderingshiërarchie

• NextPDF\Pro\Ast\Exception\AstException extends RuntimeException — basis van de build-hiërarchie.
• AstBuildLimitException extends AstException — een node-, diepte- of geheugenplafond werd overschreden.
• AstBuildTimeoutException extends AstBuildLimitException — de wandtijd-build-time-out is verstreken.
• AstNoStructTreeException extends AstException — geen structuurboom aanwezig. AstBuilder::build() vangt hem intern op en valt terug; aanroepers van build() observeren hem niet.
• AstUnsupportedEncryptionException extends AstException — de invoer-PDF is versleuteld.
• NextPDF\Pro\Ast\Exception\AstWriteVerificationException extends AstException — cache-schrijfverificatie is mislukt.
• NextPDF\Pro\Ast\Writer\AstWriteException extends RuntimeException — writer-invoer- of structuurfout.
• NextPDF\Pro\Ast\Writer\AstWriteVerificationException extends AstWriteException — structurele verificatie na het schrijven is mislukt.

Er bestaan twee verschillende AstWriteVerificationException-klassen in verschillende namespaces. AstCache::set() werpt de klasse uit de Exception-namespace; AstWriter::writeAndVerify() werpt de klasse uit de Writer-namespace. Match de namespace in catch-clausules.

Gedragscontract

AstBuilder::build($sourceHash) vereist de volledige SHA-256-hex van de bronbytes. De pijplijn is: optionele cache-lookup, encryptieafwijzing, structuurboom-pad, untagged fallback, bounding-box-koppeling, optionele cache-opslag.

De cache-sleutel combineert de bron-hash met de AstBuildOptions-hash. De options-hash is stabiel over instances met identieke waarden, dus identieke invoer en opties retourneren dezelfde boom. Wanneer er geen cache wordt aangeleverd, herbouwt elke aanroep. Gecachte payloads zijn JSON, nooit native PHP-serialisatie: het leespad valideert elk veld en instantieert alleen AST-waardetypen, dus een vergiftigde cache-entry kan geen object-injectie triggeren en degradeert tot een cache-miss.

Het structuurboom-pad draait wanneer er een structuurboom aanwezig is. Resource-plafonds — node-aantal, diepte, geheugendelta en wandtijd — worden afgedwongen tijdens het lezen van de structuurboom en werpen AstBuildLimitException of AstBuildTimeoutException. Als de reader geen structuurboom rapporteert, schakelt de builder over naar het untagged pad: de heuristische builder wanneer useHeuristic waar is, anders de bare fallback-builder. Bounding boxes worden gekoppeld door de content-stream van elke pagina binnen het bereik te analyseren; een pagina waarvan de content-stream niet kan worden geparseerd, wordt overgeslagen en laat de rest van de boom intact.

AstNode is onveranderlijk. Boomupdates herbouwen getroffen nodes bottom-up; ongewijzigde subbomen worden op identiteit geretourneerd. AstMutator volgt hetzelfde contract: elke mutatie retourneert een nieuwe AstDocument, herbouwt alleen het pad van root naar target en registreert een MutationEntry in de gedeelde MutationLog.

AstWriter past een MutationLog toe in OVERLAY-modus als een append-only incrementele update: nieuwe overlay-content-streams, bijgewerkte pagina-objecten, een cross-reference-sectie die alleen nieuwe objecten dekt, en een trailer waarvan de /Prev naar de vorige startxref wijst. De originele bytes blijven intact, volgens het incremental-update-model van ISO 32000-2:2020, 7.5.6. Vervangingstekst getekend voor Updated-entries escapet \, ( en ) in literale strings, volgens ISO 32000-2:2020, 7.3.4.2.

AstPdfEmitter::emit() is de symmetrische inverse van het lezen van de structuurboom: bomen die door de reader worden geproduceerd, roundtrippen naar structureel equivalente bomen, op node-id-hernummering en gedocumenteerde canonicalisatie-klassen na. MCID’s die aanwezig zijn op nodes worden verbatim opnieuw geëmitteerd, nooit opnieuw toegewezen.

Randgevallen en faalmodi

• Versleutelde invoer wordt afgewezen vóór elk boomwerk; er is geen gedeeltelijk-boomresultaat voor versleutelde PDF’s. Ontsleutel eerst.
• Resource-plafonds: max nodes (standaard 100.000), max diepte (standaard 200), max geheugen (standaard 256 MiB), wandtijd-time-out (standaard 30 s). Het overschrijden van een plafond werpt AstBuildLimitException; de time-out werpt AstBuildTimeoutException, een subklasse.
• Het paginabereik is 0-gebaseerd en inclusief; null-grenzen betekenen alle pagina’s.
• Een pagina waarvan de content-stream niet kan worden geparseerd, wordt overgeslagen tijdens de bounding-box-koppeling; de rest van de boom is onaangetast.
• AstCache::get() werpt nooit: misvormde, gemanipuleerde of niet-string-payloads retourneren null en forceren een herbouw. AstCache::set() faalt luidruchtig wanneer de backend-schrijfactie of de onmiddellijke terugleesactie faalt.
• AstMutator werpt InvalidArgumentException wanneer de node-id niet wordt gevonden. Onbekende update-sleutels worden stilzwijgend genegeerd; alleen text_content wordt toegepast.
• AstWriter::write() werpt AstWriteException wanneer de invoer geen %PDF--header of een lokaliseerbare startxref heeft. Entries zonder bounding box worden stilzwijgend overgeslagen. Pagina’s die niet kunnen worden gelokaliseerd via object-scan — bijvoorbeeld onder gecomprimeerde cross-reference-streams — worden overgeslagen; als er geen overlay kan worden toegepast, worden de invoerbytes ongewijzigd geretourneerd.
• OVERLAY-uitvoer is geen redactie. De witte rechthoek en de opnieuw getekende tekst worden toegevoegd; de originele content-bytes blijven in het bestand en zijn herstelbaar via ruwe extractie. Gebruik het niet voor GDPR Art. 17-wissing of juridische redactie. Er bestaat een reconstruct-modus-writer in de source-tree, maar die is als internal gemarkeerd, is niet production-ready en valt buiten het ondersteunde API-oppervlak.
• Overlay-geometrie gaat uit van A4 staand (595 x 842 pt) omdat de writer de MediaBox van de pagina niet leest. Op niet-A4-pagina’s kan de overlay licht verkeerd uitgelijnd zijn; de uitvoer blijft structureel geldig.
• writeAndVerify() controleert alleen de structuur: header, afsluitende %%EOF en uitvoergroei. Het parseert het gemuteerde document niet semantisch opnieuw.
• AstPdfEmitter::emit() werpt AstEmitException wanneer de root geen Document-node is of geen kinderen heeft. OBJR-companion-entries (annotatie) worden in deze release niet geëmitteerd.
• Deze module voert geen cryptografische bewerkingen uit en definieert geen FIPS-specifiek gedrag. SHA-256 komt alleen voor als content-adressering voor cache-sleutels.

Conformiteit

Het structuurboom-pad leest de logische-structuurfaciliteiten van tagged PDF die zijn gedefinieerd door ISO 32000-2; het RAG-corpus dat beschikbaar was bij het auteuren bevat de logische-structuurclausules niet, dus die uitspraak is product-gegrond vanuit de bronannotaties. De incremental-update-lay-out van de writer volgt ISO 32000-2:2020, 7.5.6 (hieronder geciteerd), en de escaping van literale strings volgt ISO 32000-2:2020, 7.3.4.2 (hieronder geciteerd).

Deze uitspraken beschrijven de mogelijkheid ten opzichte van de geciteerde clausules. NextPDF bezit geen conformiteitscertificering, en ondersteuning voor een clausule is geen certificeringsclaim.

Ontwikkelingsnotities

• Stel één AstBuilder samen per geladen PdfReader. Hergebruik een AstCache over builds heen om het parsen te amortiseren; het sleutelontwerp maakt optiewijzigingen zelf-invaliderend.
• Deel één MutationLog tussen een AstMutator en de AstWriter zodat de writer precies de geregistreerde sessie toepast. Roep resetLog() aan tussen onafhankelijke bewerkingssessies.
• Zet useHeuristic op true voor untagged documenten wanneer lay-out-afgeleide groepering de voorkeur heeft boven de bare fallback-boom.
• Builds zijn deterministisch voor identieke bytes en opties; vertrouw hierop voor snapshot-achtige tests.
• Vang build-fouten via de NextPDF\Pro\Ast\Exception-hiërarchie en write-fouten via de NextPDF\Pro\Ast\Writer-hiërarchie; de twee delen geen basis onder RuntimeException.

Publicatiegrens

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

Zie ook

• AST — mogelijkheidsoverzicht
• Projection — Deep Reference
• Output Pipeline — Deep Reference