AST

En bref

Le module AST transforme un PDF en un arbre de document immuable et navigable. Il utilise l’arbre de structure balisé lorsqu’il est présent et se rabat sur un constructeur heuristique pour les documents non balisés, attachant des boîtes englobantes et du texte à chaque nœud.

Disponibilité et licence

Cette fonctionnalité est livrée dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de palier Pro. Un déploiement sans ce droit ne charge pas les classes de la fonctionnalité. Comparer les éditions et obtenir une licence.

Il n’existe aucun indicateur de licence par fonctionnalité. Le code est livré avec l’édition Pro ; le comportement de construction est entièrement régi par AstBuildOptions (limites de ressources et plages de pages), et non par un commutateur de licence.

Installation

composer require nextpdf/pro:^3

Le code réside sous l’espace de noms NextPDF\Pro\Ast.

Vue d’ensemble conceptuelle

AstBuilder orchestre le pipeline PDF-vers-arbre : vérifier le cache, rejeter tôt une entrée chiffrée, lire l’arbre de structure pour les PDF balisés, se rabattre sur un chemin non balisé sinon, attacher les boîtes englobantes à partir de l’analyse du flux de contenu, puis mettre le résultat en cache. La sortie est un AstDocument dont les nœuds sont immuables ; les mises à jour reconstruisent le sous-arbre affecté de bas en haut plutôt que de le muter sur place.

Deux stratégies de repli existent pour les PDF non balisés : un repli minimal et un constructeur heuristique facultatif (AstBuildOptions::$useHeuristic). Le module fournit également un chemin d’émetteur qui peut réécrire un AST vers un PDF et vérifier le résultat, ainsi qu’un journal de mutations pour suivre les changements appliqués à l’arbre.

Pourquoi cela fonctionne ainsi

L’arbre est immuable par construction. Chaque modification ne reconstruit que le chemin racine-vers-nœud affecté et partage les sous-arbres intacts par identité, de sorte qu’un AstDocument construit peut être conservé, mis en cache et confié à des lecteurs concurrents sans copies défensives. Cela reflète la façon dont un PDF lui-même change sur le disque : le chemin de réécriture ajoute une mise à jour incrémentale via AstWriter plutôt que de réécrire le fichier, laissant les octets d’origine — et toute signature existante — intacts. Une révision en ajout seul est aussi peu coûteuse à vérifier structurellement, c’est pourquoi AstWriter peut contrôler sa propre sortie avant de la renvoyer. Reconstruire les sous-arbres plutôt que de muter sur place est la décision unique qui rend le module à la fois navigable et éditable en toute sécurité.

Contexte de conception : Les mises à jour incrémentales et leur importance.

Contrat de comportement

• AstBuilder::build($sourceHash) accepte l’hexadécimal SHA-256 complet du PDF source et renvoie un AstDocument.
• Les PDF chiffrés sont rejetés avec une erreur dédiée de chiffrement non pris en charge ; déchiffre avant de construire.
• Lorsqu’aucun arbre de structure n’est présent, le constructeur utilise automatiquement le chemin non balisé — heuristique si activé, repli minimal sinon.
• Les limites de ressources dans AstBuildOptions (nombre maximal de nœuds, profondeur maximale, mémoire maximale, délai d’horloge murale) provoquent une erreur de limite de construction ou de dépassement de délai plutôt qu’un travail non borné.
• La clé de cache incorpore l’empreinte source et l’empreinte des options, de sorte que deux constructions avec des entrées et des options identiques renvoient le même arbre.
• AstNode est immuable ; les consommateurs reçoivent de nouvelles instances de nœud lorsque l’arbre change.

Exemple de code — Démarrage rapide

Ce qui suit reflète l’API publique documentée. Le dépôt ne livre pas d’exemple exécutable pour ce module.

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

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

Exemple de code — Production

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

Cas limites et pièges

• Les pages dont le flux de contenu ne peut pas être analysé sont ignorées pendant l’attachement des boîtes englobantes ; l’arbre est tout de même renvoyé, simplement sans boîtes pour ces pages.
• Le constructeur heuristique est en opt-in. Lorsqu’il est désactivé, les PDF non balisés produisent un arbre plus grossier issu du repli minimal.
• La plage de pages dans AstBuildOptions utilise des indices à base 0, inclusifs ; laisser les deux bornes à null traite toutes les pages.

Performance

Le coût de construction évolue avec le nombre de nœuds et le nombre de pages ; AstBuildOptions borne les deux. Le cache court-circuite les constructions répétées de la même entrée avec les mêmes options. NextPDF ne publie pas ici de temps fixe par document ; le délai d’horloge murale (30 s par défaut) et le plafond de nœuds (100,000 par défaut) bornent le travail dans le pire des cas. Mesure avec des documents représentatifs.

Notes de sécurité

Traite l’entrée comme non fiable. Le constructeur rejette les PDF chiffrés plutôt que de les traiter partiellement. Les plafonds de ressources (nœuds, profondeur, mémoire, temps) protègent contre les documents pathologiques ou hostiles. Ce module ne journalise aucun contenu de document.

Conformité

Le chemin d’arbre de structure lit les structures de PDF balisé définies par ISO 32000-2 ; la source du module annote les clauses de flux de contenu et de structure pertinentes. Parce que le corpus RAG était indisponible au moment de la rédaction, cette page n’affirme aucun identifiant de clause externe et limite les déclarations de conformité au comportement vérifié par les tests du module.

Note sur la frontière Enterprise

Enterprise ne change pas le comportement d’AST. Enterprise ajoute des capacités de conformité et d’archivage de palier supérieur documentées séparément ; elles ne sont pas requises pour construire ou consommer un AST.

Repli sur le Core / alternative

Sans Pro, il n’y a aucun arbre de document équivalent ; les appelants analysent directement les flux de contenu à l’aide des primitives de NextPDF Core. Voir /modules/ast/.

Frontière de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes auxiliaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Voir aussi

• AST — Référence détaillée
• Projection
• Diff
• Output Pipeline