Formulário

Em resumo

O NextPDF Pro lê e grava dados de formulário interativo: valores de campo AcroForm, arquivos de dados XFDF e os dados carregados por templates XFA (XML Forms Architecture). Ele complementa o leitor de formulários do Core open-source com vinculação de dados, extração e serialização.

Disponibilidade e licenciamento

Esta capacidade acompanha o NextPDF Pro (nextpdf/pro) e é ativada por um envelope de licença de nível Pro. Uma implantação sem esse direito de uso não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

O Form faz parte da edição Pro. Não há sinalizador de licença separado por recurso.

Instalação

composer require nextpdf/pro:^3

A capacidade Form requer uma licença válida do NextPDF Pro. Consulte Disponibilidade e licenciamento.

Visão conceitual

Um formulário interativo PDF — às vezes chamado de AcroForm — armazena cada campo em um dicionário de campo, conforme definido na ISO 32000-2 §12.7. O NextPDF Pro se baseia no leitor de formulários do Core para acrescentar três capacidades:

• Round-trip de AcroForm. FormDataExtractor lê pares nome/valor de campo a partir de campos de formulário analisados e produz um objeto XfdfData ou um mapa simples name → value. XfdfWriter faz o inverso, gerando um documento XFDF.
• Leitura e gravação de XFDF. XFDF é o formato de troca de dados em XML para valores de formulário descrito pela ISO 19444-1:2019. XfdfParser lê um arquivo XFDF em dados estruturados; XfdfWriter serializa os valores de campo para XFDF, com uma referência opcional de volta ao PDF de origem.
• Extração de dados XFA. XfaParser localiza os pacotes XFA em um documento, concatena os fragmentos XML e analisa os pacotes template e datasets em dados de campo estruturados.

Escopo do suporte a XFA

O suporte a XFA no NextPDF Pro é orientado a dados, não um mecanismo completo de renderização ou scripting de XFA. O analisador extrai e estrutura os pacotes template e datasets para que você possa ler definições e valores de campo. Ele não executa scripts de cálculo de formulário XFA, não renderiza layouts XFA dinâmicos nem faz round-trip de todos os tipos de pacote XFA. Teste o analisador com seus documentos específicos antes de confiar nele para um determinado conjunto de formulários XFA. Toda análise de XML desativa o carregamento de entidades externas (seguro contra XXE).

Por que funciona assim

O suporte a XFA é delimitado a dados, não a renderização, de propósito. A ISO 32000-2 marca a entrada XFA do dicionário de formulário como deprecada no PDF 2.0 (§12.7). Um mecanismo completo de layout e scripting XFA perseguiria uma superfície legada que a maioria das cargas de trabalho não precisa mais. Em vez disso, o NextPDF Pro extrai os pacotes template e datasets, onde vivem os dados de campo duradouros, e recusa o resto. A mesma postura orienta a análise com XXE desativado e o teto de varredura, porque a entrada de formulário frequentemente chega de partes não confiáveis. Isso mantém a superfície de formulário do Pro como uma extensão fina e previsível do modelo AcroForm do Core.

Contexto de design: Do formulário preenchível ao registro congelado: preenchimento e achatamento de AcroForm.

Superfície da API

Classe	Responsabilidade
FormDataExtractor	Extrair valores de campo AcroForm como XfdfData ou um array.
XfdfParser	Analisar um documento XFDF em dados estruturados.
XfdfWriter	Serializar valores de campo para XFDF, referência PDF opcional.
XfaParser	Extrair e analisar os pacotes template e datasets XFA.
FormDataBinder	Vincular um mapa de dados de volta aos campos de formulário.

A referência completa em nível de método está na referência aprofundada do Form.

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

use NextPDF\Pro\Form\FormDataExtractor;
use NextPDF\Pro\Form\XfdfWriter;

$values = FormDataExtractor::toArray($fields);
$xfdf   = XfdfWriter::fromFields($fields, 'invoice.pdf');

Exemplo de código — Produção

use NextPDF\Pro\Form\XfaParser;
use NextPDF\Pro\Form\Exception\XfaParseException;

try {
    $formData = (new XfaParser())->parse($pdfBytes);
    $logger->info('xfa.parsed', ['fields' => count($formData->fields)]);
} catch (XfaParseException $e) {
    $logger->warning('xfa.parse_failed', ['reason' => $e->getMessage()]);
}

Casos extremos e armadilhas

• XfaParser rejeita entradas de PDF maiores que seu teto de varredura, em vez de ler dados ilimitados.
• Um documento pode carregar tanto formulários interativos quanto não interativos; a extração visa os dicionários de campo terminais.
• O XFDF faz round-trip de estruturas de campo planas; hierarquias de campo profundamente aninhadas podem precisar de tratamento explícito.

Desempenho

A extração e a serialização são lineares no número de campos de formulário. O custo de análise de XFA escala com o tamanho dos pacotes XML incorporados.

Notas de segurança

Toda análise de XML desativa a resolução de entidades externas para prevenir XXE. Trate as entradas XFDF e XFA de fontes não confiáveis como hostis e valide o conjunto de campos analisado antes de vinculá-lo de volta a um documento.

Conformidade

Comportamento	Referência	Status
Modelo de formulário interativo / dicionário de campo	ISO 32000-2 §12.7	Alinhado (parafraseado)
Formato de troca de dados XFDF	ISO 19444-1:2019	Alinhado

Esta tabela registra as especificações em relação às quais o NextPDF Pro é construído. Não é uma declaração de certificação formal.

Contrato de comportamento

• FormDataExtractor lê pares nome/valor de dicionários de campo terminais analisados e retorna um objeto XfdfData ou um array simples name → value.
• XfdfParser analisa um documento XFDF em dados estruturados; XfdfWriter serializa os valores de campo para XFDF com uma referência opcional de volta ao PDF de origem.
• XfaParser localiza os pacotes XFA, concatena os fragmentos XML e analisa os pacotes template e datasets em dados de campo estruturados. Ele rejeita entradas de PDF maiores que seu teto de varredura, em vez de ler dados ilimitados.
• O suporte a XFA é orientado a dados: o analisador extrai e estrutura os pacotes template e datasets. Ele não executa scripts de cálculo de formulário XFA, não renderiza layouts XFA dinâmicos nem faz round-trip de todos os tipos de pacote XFA.
• Toda análise de XML desativa a resolução de entidades externas (seguro contra XXE).

Nota sobre o limite do Enterprise

O Enterprise não altera o comportamento do Form. O Enterprise acrescenta recursos de compliance e arquivamento de nível superior documentados separadamente; eles não são necessários para round-trip de AcroForm, leitura/gravação de XFDF ou extração de dados XFA.

Fallback / alternativa do Core

O leitor de formulários open-source do NextPDF Core lê campos de formulário. A leitura/gravação de XFDF, a extração de dados XFA e a vinculação de campos são acréscimos do Pro. Consulte /modules/form/.

Limite de publicação

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

Veja também

• Interop — DTOs versionados de dados de formulário para sistemas externos.
• Módulo Form do Core — leitor de formulários open-source.
• Form — Referência aprofundada — referência em nível de método para as classes de formulário do Pro.