AST

De un vistazo

El módulo AST convierte un PDF en un árbol de documento inmutable y navegable. Usa el árbol de estructura etiquetada cuando está presente y recurre a un constructor heurístico para los documentos sin etiquetar, adjuntando cuadros delimitadores y texto a cada nodo.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa titularidad no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

No existe ningún indicador de licencia por función. El código se distribuye con la edición Pro; el comportamiento de construcción lo gobierna por completo AstBuildOptions (límites de recursos y rangos de páginas), no un interruptor de licencia.

Instalación

composer require nextpdf/pro:^3

El código vive bajo el espacio de nombres NextPDF\Pro\Ast.

Descripción conceptual

AstBuilder orquesta el pipeline de PDF a árbol: comprobar la caché, rechazar la entrada cifrada de forma temprana, leer el árbol de estructura para los PDF etiquetados, recurrir a una ruta sin etiquetar en caso contrario, adjuntar cuadros delimitadores a partir del análisis del flujo de contenido y luego almacenar en caché el resultado. La salida es un AstDocument cuyos nodos son inmutables; las actualizaciones reconstruyen el subárbol afectado de abajo hacia arriba en lugar de mutar en el sitio.

Existen dos estrategias de alternativa para los PDF sin etiquetar: una alternativa básica y un constructor heurístico opcional (AstBuildOptions::$useHeuristic). El módulo también proporciona una ruta de emisor que puede escribir un AST de vuelta a un PDF y verificar el resultado, además de un registro de mutaciones para rastrear los cambios aplicados al árbol.

Por qué funciona así

El árbol es inmutable por construcción. Cada edición reconstruye únicamente la ruta afectada de la raíz al nodo y comparte los subárboles intactos por identidad, de modo que un AstDocument ya construido es seguro para retener, almacenar en caché y entregar a lectores concurrentes sin copias defensivas. Esto refleja cómo cambia en disco un PDF en sí: la ruta de reescritura añade una actualización incremental a través de AstWriter en lugar de reescribir el archivo, dejando intactos los bytes originales —y cualquier firma existente—. Una revisión de solo anexado también es barata de verificar estructuralmente, y por eso AstWriter puede comprobar su propia salida antes de devolverla. Reconstruir los subárboles en lugar de mutar en el sitio es la única decisión que hace que el módulo sea a la vez navegable y editable de forma segura.

Contexto de diseño: Actualizaciones incrementales y por qué importan.

Contrato de comportamiento

• AstBuilder::build($sourceHash) acepta el hex SHA-256 completo del PDF de origen y devuelve un AstDocument.
• Los PDF cifrados se rechazan con un error dedicado de cifrado no compatible; descifre antes de construir.
• Cuando no hay ningún árbol de estructura presente, el constructor usa la ruta sin etiquetar automáticamente — heurística si está activada, alternativa básica en caso contrario.
• Los límites de recursos en AstBuildOptions (máximo de nodos, máximo de profundidad, máximo de memoria, tiempo de espera de reloj de pared) provocan un error de límite de construcción o de tiempo de espera de construcción en lugar de un trabajo no acotado.
• La clave de caché incorpora el hash de origen y el hash de opciones, por lo que dos construcciones con entradas y opciones idénticas devuelven el mismo árbol.
• AstNode es inmutable; los consumidores reciben nuevas instancias de nodo cuando el árbol cambia.

Ejemplo de código — Inicio rápido

Lo siguiente refleja la API pública documentada. El repositorio no incluye ningún ejemplo ejecutable para este módulo.

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

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

Ejemplo de código — Producción

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

Casos límite y trampas

• Las páginas cuyo flujo de contenido no se puede analizar se omiten durante la adjunción de cuadros delimitadores; el árbol se devuelve igualmente, solo que sin cuadros para esas páginas.
• El constructor heurístico es opcional. Con él desactivado, los PDF sin etiquetar producen un árbol más grueso a partir de la alternativa básica.
• El rango de páginas en AstBuildOptions usa índices inclusivos basados en 0; dejar ambos límites en nulo procesa todas las páginas.

Rendimiento

El costo de construcción escala con el recuento de nodos y el recuento de páginas; AstBuildOptions acota ambos. La caché cortocircuita las construcciones repetidas de la misma entrada con las mismas opciones. NextPDF no publica aquí un tiempo fijo por documento; el tiempo de espera de reloj de pared (predeterminado 30 s) y el techo de nodos (predeterminado 100.000) acotan el trabajo en el peor caso. Mida con documentos representativos.

Notas de seguridad

Trate la entrada como no confiable. El constructor rechaza los PDF cifrados en lugar de procesarlos parcialmente. Los techos de recursos (nodos, profundidad, memoria, tiempo) protegen frente a documentos patológicos u hostiles. Este módulo no registra ningún contenido del documento.

Conformidad

La ruta del árbol de estructura lee las estructuras de PDF etiquetado definidas por ISO 32000-2; el código fuente del módulo anota las cláusulas relevantes de flujo de contenido y de estructura. Como el corpus de RAG no estaba disponible en el momento de la redacción, esta página no afirma ningún identificador de cláusula externo y limita las declaraciones de conformidad al comportamiento verificado por las pruebas del módulo.

Nota sobre la frontera de Enterprise

Enterprise no cambia el comportamiento de AST. Enterprise añade capacidades de cumplimiento y archivado de nivel superior documentadas por separado; no son necesarias para construir ni consumir un AST.

Alternativa de Core

Sin Pro, no hay ningún árbol de documento equivalente; los llamantes analizan los flujos de contenido directamente usando las primitivas de NextPDF Core. Consulte /modules/ast/.

Frontera de publicación

Esta página documenta únicamente el comportamiento observable desde fuera y la superficie de API pública admitida. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.

Véase también

• AST — Referencia detallada
• Projection
• Diff
• Output Pipeline