AST

Auf einen Blick

Das AST-Modul verwandelt ein PDF in einen unveränderlichen, navigierbaren Dokumentbaum. Es nutzt den Tagged-Structure-Baum, sofern vorhanden, und fällt für untagged Dokumente auf einen heuristischen Builder zurück, wobei es an jeden Knoten Bounding-Boxes und Text anhängt.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird mit NextPDF Pro (nextpdf/pro) ausgeliefert und wird mit einem Lizenzumschlag der Pro-Stufe aktiviert. Ein Deployment ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und Lizenz erwerben.

Es existiert kein Lizenz-Flag pro Funktion. Der Code wird mit der Pro-Edition ausgeliefert; das Build-Verhalten wird ausschließlich durch AstBuildOptions (Ressourcenlimits und Seitenbereiche) bestimmt, nicht durch einen Lizenzschalter.

Installation

composer require nextpdf/pro:^3

Der Code liegt unter dem Namespace NextPDF\Pro\Ast.

Konzeptioneller Überblick

AstBuilder orchestriert die PDF-zu-Baum-Pipeline: den Cache prüfen, verschlüsselte Eingabe früh ablehnen, den Strukturbaum für Tagged-PDFs lesen, andernfalls auf einen Untagged-Pfad zurückfallen, Bounding-Boxes aus der Content-Stream-Analyse anhängen und dann das Ergebnis cachen. Die Ausgabe ist ein AstDocument, dessen Knoten unveränderlich sind; Updates rekonstruieren den betroffenen Teilbaum bottom-up, statt in-place zu mutieren.

Für untagged PDFs existieren zwei Fallback-Strategien: ein nackter Fallback und ein optionaler heuristischer Builder (AstBuildOptions::$useHeuristic). Das Modul stellt außerdem einen Emitter-Pfad bereit, der ein AST zurück in ein PDF schreiben und das Ergebnis verifizieren kann, sowie ein Mutations-Log zur Verfolgung der am Baum vorgenommenen Änderungen.

Warum es so funktioniert

Der Baum ist per Konstruktion unveränderlich. Jede Bearbeitung baut nur den betroffenen Pfad von der Wurzel zum Knoten neu auf und teilt die unberührten Teilbäume über die Identität, sodass ein gebautes AstDocument sicher gehalten, gecacht und gleichzeitigen Lesern übergeben werden kann, ohne defensive Kopien. Dies spiegelt wider, wie sich ein PDF selbst auf der Festplatte ändert: Der Write-back-Pfad hängt über AstWriter ein inkrementelles Update an, statt die Datei neu zu schreiben, und lässt die ursprünglichen Bytes — und alle vorhandenen Signaturen — intakt. Eine Append-only-Revision lässt sich zudem strukturell günstig verifizieren, weshalb AstWriter seine eigene Ausgabe prüfen kann, bevor er sie zurückgibt. Teilbäume zu rekonstruieren, statt in-place zu mutieren, ist die eine Entscheidung, die das Modul zugleich navigierbar und sicher editierbar macht.

Design-Hintergrund: Inkrementelle Updates und warum sie wichtig sind.

Verhaltensvertrag

• AstBuilder::build($sourceHash) akzeptiert den vollständigen SHA-256-Hex des Quell-PDFs und gibt ein AstDocument zurück.
• Verschlüsselte PDFs werden mit einem dedizierten Unsupported-Encryption-Fehler abgelehnt; entschlüsseln Sie vor dem Bauen.
• Wenn kein Strukturbaum vorhanden ist, nutzt der Builder automatisch den Untagged-Pfad — heuristisch, falls aktiviert, sonst den nackten Fallback.
• Ressourcenlimits in AstBuildOptions (max nodes, max depth, max memory, Wall-Clock-Timeout) verursachen einen Build-Limit- oder Build-Timeout-Fehler statt unbegrenzter Arbeit.
• Der Cache-Schlüssel bezieht den Quell-Hash und den Options-Hash ein, sodass zwei Builds mit identischen Eingaben und Optionen denselben Baum zurückgeben.
• AstNode ist unveränderlich; Konsumenten erhalten neue Knoteninstanzen, wenn sich der Baum ändert.

Codebeispiel — Schnellstart

Das Folgende spiegelt die dokumentierte öffentliche API wider. Das Repository liefert kein lauffähiges Beispiel für dieses Modul.

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

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

Codebeispiel — Produktion

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

Sonderfälle & Fallstricke

• Seiten, deren Content-Stream nicht geparst werden kann, werden während des Bounding-Box-Anhängens übersprungen; der Baum wird dennoch zurückgegeben, nur ohne Boxen für diese Seiten.
• Der heuristische Builder ist Opt-in. Ist er deaktiviert, ergeben untagged PDFs einen gröberen Baum aus dem nackten Fallback.
• Der Seitenbereich in AstBuildOptions verwendet 0-basierte, inklusive Indizes; lässt man beide Grenzen null, werden alle Seiten verarbeitet.

Performance

Die Build-Kosten skalieren mit der Knotenzahl und der Seitenzahl; AstBuildOptions begrenzt beide. Der Cache kürzt wiederholte Builds derselben Eingabe mit denselben Optionen ab. NextPDF veröffentlicht hier kein festes Timing pro Dokument; der Wall-Clock-Timeout (Standard 30 s) und die Knotenobergrenze (Standard 100.000) begrenzen die Worst-Case-Arbeit. Messen Sie mit repräsentativen Dokumenten.

Sicherheitshinweise

Behandeln Sie Eingaben als nicht vertrauenswürdig. Der Builder lehnt verschlüsselte PDFs ab, statt sie teilweise zu verarbeiten. Ressourcenobergrenzen (Knoten, Tiefe, Speicher, Zeit) schützen vor pathologischen oder feindlichen Dokumenten. Dieses Modul protokolliert keinen Dokumentinhalt.

Konformität

Der Strukturbaum-Pfad liest Tagged-PDF-Strukturen, die durch ISO 32000-2 definiert sind; die Modulquelle annotiert die relevanten Content-Stream- und Strukturklauseln. Da der RAG-Korpus zur Autorenzeit nicht verfügbar war, behauptet diese Seite keine externen Klausel-Identifikatoren und begrenzt Konformitätsaussagen auf das durch die Tests des Moduls verifizierte Verhalten.

Hinweis zur Enterprise-Grenze

Enterprise ändert das AST-Verhalten nicht. Enterprise ergänzt höherstufige Compliance- und Archivierungsfähigkeiten, die separat dokumentiert sind; sie sind zum Bauen oder Konsumieren eines AST nicht erforderlich.

Core-Fallback / Alternative

Ohne Pro gibt es keinen äquivalenten Dokumentbaum; Aufrufer parsen Content-Streams direkt mit NextPDF-Core-Primitiven. Siehe /modules/ast/.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Geltungsbereichs.

Siehe auch

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