AST

Visão geral

O módulo AST transforma um PDF em uma árvore de documento imutável e navegável. Ele usa a árvore de estrutura marcada (tagged) quando presente e recorre a um construtor heurístico para documentos não marcados, anexando bounding boxes e texto a cada nó.

Disponibilidade e licenciamento

Este recurso vem no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem essa habilitação não carrega as classes do recurso. Compare as edições e obtenha uma licença.

Não existe nenhum sinalizador de licença por recurso. O código vem com a edição Pro; o comportamento do build é governado inteiramente por AstBuildOptions (limites de recursos e faixas de páginas), não por um interruptor de licença.

Instalação

composer require nextpdf/pro:^3

O código fica sob o namespace NextPDF\Pro\Ast.

Visão conceitual

AstBuilder orquestra o pipeline de PDF para árvore: verifica o cache, rejeita entrada criptografada cedo, lê a árvore de estrutura para PDFs marcados, recorre a um caminho não marcado caso contrário, anexa bounding boxes a partir da análise do content stream e, em seguida, armazena o resultado em cache. A saída é um AstDocument cujos nós são imutáveis; as atualizações reconstroem a subárvore afetada de baixo para cima em vez de mutar no lugar.

Existem duas estratégias de fallback para PDFs não marcados: um fallback simples e um construtor heurístico opcional (AstBuildOptions::$useHeuristic). O módulo também fornece um caminho de emissor que pode gravar um AST de volta para um PDF e verificar o resultado, além de um log de mutação para rastrear mudanças aplicadas à árvore.

Por que funciona assim

A árvore é imutável por construção. Cada edição reconstrói apenas o caminho afetado da raiz ao nó e compartilha as subárvores intocadas por identidade, de modo que um AstDocument já construído é seguro para reter, armazenar em cache e entregar a leitores concorrentes sem cópias defensivas. Isso espelha como um PDF em si muda em disco: o caminho de gravação de volta anexa uma atualização incremental por meio do AstWriter em vez de reescrever o arquivo, deixando os bytes originais — e quaisquer assinaturas existentes — intactos. Uma revisão somente de anexação também é barata de verificar estruturalmente, e é por isso que o AstWriter pode conferir sua própria saída antes de retorná-la. Reconstruir subárvores em vez de mutar no lugar é a única decisão que torna o módulo ao mesmo tempo navegável e editável com segurança.

Contexto de design: Atualizações incrementais e por que elas importam.

Contrato de comportamento

• AstBuilder::build($sourceHash) aceita o hex SHA-256 completo do PDF de origem e retorna um AstDocument.
• PDFs criptografados são rejeitados com um erro dedicado de criptografia não suportada; descriptografe antes de construir.
• Quando não há nenhuma árvore de estrutura presente, o construtor usa o caminho não marcado automaticamente — heurístico se ativado, fallback simples caso contrário.
• Os limites de recursos em AstBuildOptions (máximo de nós, profundidade máxima, memória máxima, timeout de relógio) causam um erro de limite de build ou de timeout de build em vez de trabalho ilimitado.
• A chave de cache incorpora o hash de origem e o hash das opções, de modo que dois builds com entradas e opções idênticas retornam a mesma árvore.
• AstNode é imutável; os consumidores recebem novas instâncias de nó quando a árvore muda.

Exemplo de código — Início rápido

O seguinte reflete a API pública documentada. O repositório não fornece um exemplo executável para este módulo.

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

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

Exemplo de código — Produção

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 extremos e armadilhas

• Páginas cujo content stream não pode ser analisado são ignoradas durante a anexação de bounding boxes; a árvore ainda é retornada, apenas sem caixas para essas páginas.
• O construtor heurístico é opt-in. Com ele desativado, PDFs não marcados geram uma árvore mais grosseira a partir do fallback simples.
• A faixa de páginas em AstBuildOptions usa índices baseados em 0 e inclusivos; deixar ambos os limites nulos processa todas as páginas.

Desempenho

O custo de build escala com a contagem de nós e a contagem de páginas; AstBuildOptions delimita ambos. O cache faz curto-circuito em builds repetidos da mesma entrada com as mesmas opções. O NextPDF não publica um tempo fixo por documento aqui; o timeout de relógio (padrão de 30 s) e o teto de nós (padrão de 100.000) delimitam o trabalho de pior caso. Meça com documentos representativos.

Notas de segurança

Trate a entrada como não confiável. O construtor rejeita PDFs criptografados em vez de processá-los parcialmente. Os tetos de recursos (nós, profundidade, memória, tempo) protegem contra documentos patológicos ou hostis. Este módulo não registra nenhum conteúdo de documento.

Conformidade

O caminho da árvore de estrutura lê estruturas de PDF marcado definidas pela ISO 32000-2; o código-fonte do módulo anota as cláusulas relevantes de content stream e estrutura. Como o corpus RAG estava indisponível no momento da autoria, esta página não afirma nenhum identificador de cláusula externo e limita as declarações de conformidade ao comportamento verificado pelos testes do módulo.

Nota sobre o limite do Enterprise

O Enterprise não altera o comportamento do AST. O Enterprise acrescenta capacidades de nível superior de conformidade e arquivamento documentadas separadamente; elas não são necessárias para construir ou consumir um AST.

Alternativa / fallback do Core

Sem o Pro, não há nenhuma árvore de documento equivalente; os chamadores analisam content streams diretamente usando as primitivas do NextPDF Core. Consulte /modules/ast/.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície da API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora de escopo.

Consulte também

• AST — Referência Detalhada
• Projection
• Diff
• Output Pipeline