Pro editie

AST

In het kort

De AST-module zet een PDF om in een onveranderlijke, navigeerbare documentboom. Hij gebruikt de tagged-structuurboom wanneer die aanwezig is en valt terug op een heuristische builder voor untagged documenten, waarbij hij bounding boxes en tekst aan elke node koppelt.

Beschikbaarheid en licentie

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

Er bestaat geen licentievlag per functie. De code wordt geleverd met de Pro-editie; het build-gedrag wordt volledig geregeld door AstBuildOptions (resourcelimieten en paginabereiken), niet door een licentieschakelaar.

Installeren

composer require nextpdf/pro:^3

De code leeft onder de NextPDF\Pro\Ast-namespace.

Conceptueel overzicht

AstBuilder orkestreert de PDF-naar-boom-pijplijn: controleer de cache, wijs versleutelde invoer vroeg af, lees de structuurboom voor tagged PDF’s, val anders terug op een untagged pad, koppel bounding boxes uit content-stream-analyse en cache vervolgens het resultaat. De uitvoer is een AstDocument wiens nodes onveranderlijk zijn; updates reconstrueren de getroffen subboom bottom-up in plaats van ter plaatse te muteren.

Er bestaan twee terugvalstrategieën voor untagged PDF’s: een bare fallback en een optionele heuristische builder (AstBuildOptions::$useHeuristic). De module biedt ook een emitter-pad dat een AST terug naar een PDF kan schrijven en het resultaat kan verifiëren, plus een mutatielog voor het volgen van wijzigingen die op de boom worden toegepast.

Waarom het zo werkt

De boom is onveranderlijk door constructie. Elke bewerking herbouwt alleen het getroffen pad van root naar node en deelt de onaangeroerde subbomen op identiteit, zodat een gebouwde AstDocument veilig is om vast te houden, te cachen en aan gelijktijdige lezers door te geven zonder defensieve kopieën. Dit weerspiegelt hoe een PDF zelf op schijf verandert: het write-back-pad voegt via AstWriter een incrementele update toe in plaats van het bestand te herschrijven, waardoor de oorspronkelijke bytes — en eventuele bestaande handtekeningen — intact blijven. Een append-only revisie is bovendien goedkoop om structureel te verifiëren, en daarom kan AstWriter zijn eigen uitvoer controleren voordat hij die retourneert. Subbomen reconstrueren in plaats van ter plaatse muteren is de ene beslissing die de module zowel navigeerbaar als veilig bewerkbaar maakt.

Ontwerpachtergrond: Incrementele updates en waarom ze ertoe doen.

Gedragscontract

AstBuilder::build($sourceHash) accepteert de volledige SHA-256-hex van de bron-PDF en retourneert een AstDocument.
Versleutelde PDF’s worden afgewezen met een toegewijde unsupported-encryption-fout; ontsleutel vóór het bouwen.
Wanneer er geen structuurboom aanwezig is, gebruikt de builder automatisch het untagged pad — heuristisch indien ingeschakeld, anders bare fallback.
Resourcelimieten in AstBuildOptions (max nodes, max depth, max memory, wall-clock timeout) veroorzaken een build-limit- of build-timeout-fout in plaats van onbegrensd werk.
De cache-sleutel verwerkt de bron-hash en de options-hash, zodat twee builds met identieke invoer en opties dezelfde boom retourneren.
AstNode is onveranderlijk; consumers ontvangen nieuwe node-instances wanneer de boom verandert.

Codevoorbeeld — Snelstart

Het volgende weerspiegelt de gedocumenteerde publieke API. De repository levert geen uitvoerbaar voorbeeld voor deze module.

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

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

Codevoorbeeld — Productie

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.
}

Randgevallen en valkuilen

Pagina’s wiens content stream niet kan worden geparseerd, worden overgeslagen tijdens de bounding-box-koppeling; de boom wordt nog steeds geretourneerd, alleen zonder boxes voor die pagina’s.
De heuristische builder is opt-in. Met deze uitgeschakeld leveren untagged PDF’s een grovere boom uit de bare fallback.
Het paginabereik in AstBuildOptions gebruikt 0-gebaseerde, inclusieve indices; beide grenzen null laten verwerkt alle pagina’s.

Prestaties

De build-kosten schalen met node-aantal en pagina-aantal; AstBuildOptions begrenst beide. De cache short-circuit herhaalde builds van dezelfde invoer met dezelfde opties. NextPDF publiceert hier geen vaste timing per document; de wall-clock timeout (standaard 30 s) en het node-plafond (standaard 100.000) begrenzen het ergste geval. Meet met representatieve documenten.

Beveiligingsnotities

Behandel invoer als niet-vertrouwd. De builder wijst versleutelde PDF’s af in plaats van ze gedeeltelijk te verwerken. Resource-plafonds (nodes, diepte, geheugen, tijd) beschermen tegen pathologische of vijandige documenten. Deze module logt geen documentinhoud.

Conformiteit

Het structuurboom-pad leest tagged-PDF-structuren die zijn gedefinieerd door ISO 32000-2; de bron van de module annoteert de relevante content-stream- en structuurclausules. Omdat het RAG-corpus tijdens het auteuren niet beschikbaar was, beweert deze pagina geen externe clausule-identifiers en beperkt zij conformiteitsuitspraken tot gedrag dat door de tests van de module is geverifieerd.

Opmerking over de Enterprise-grens

Enterprise wijzigt het AST-gedrag niet. Enterprise voegt hogere-tier compliance- en archiveringsmogelijkheden toe die apart zijn gedocumenteerd; die zijn niet vereist om een AST te bouwen of te consumeren.

Core-terugval / alternatief

Zonder Pro is er geen equivalente documentboom; aanroepers parseren content streams rechtstreeks met NextPDF Core-primitieven. Zie /modules/ast/.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-classes, mechanisme-tabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.