Form — Referência Profunda

Visão geral

Esta página é a referência profunda do módulo Form do Pro. Ela cobre a extração de valores de AcroForm, a leitura e escrita de XFDF, a vinculação de dados e a extração de dados XFA. O módulo consome valores NextPDF\Form\FormField produzidos pelo leitor de formulários do Core e adiciona serialização, parsing e vinculação sobre eles. O suporte a XFA é orientado a dados: o parser estrutura os pacotes template e datasets. Ele não executa scripts de cálculo XFA nem renderiza layouts XFA dinâmicos.

Disponibilidade & licenciamento

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

Não existe sinalizador de licença por recurso. Este é um recurso da edição Pro.

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
FormDataExtractor::extract	list<FormField> $fields	Lê o nome e o valor de cada campo	XfdfData	—	Inclui campos cujo valor é vazio.
FormDataExtractor::toArray	list<FormField> $fields	Constrói um mapa de string de nome para valor	array<string, string>	—	Um nome duplicado posterior sobrescreve um anterior.
FormDataExtractor::toXfdf	list<FormField> $fields, ?string $pdfHref = null	Delega para XfdfWriter::fromFields	string (XFDF XML)	—	Caminho de conveniência para exportação em uma única chamada.
FormDataExtractor::extractNonEmpty	list<FormField> $fields	Pula campos cujo valor é a string vazia	XfdfData	—	—
FormDataExtractor::getEmptyFieldNames	list<FormField> $fields	Lista os nomes dos campos sem valor definido	list<string>	—	Complemento de extractNonEmpty.
XfdfWriter::fromFields	list<FormField> $fields, ?string $pdfHref = null	Coleta pares nome-valor, delega para fromArray	string (XFDF XML)	—	—
XfdfWriter::fromArray	array<string, string> $data, ?string $pdfHref = null	Encapsula o mapa em XfdfData, delega	string (XFDF XML)	—	—
XfdfWriter::fromXfdfData	XfdfData $data, ?string $pdfHref = null	Serializa para XFDF; nomes em notação de ponto se aninham como elementos <field> hierárquicos	string (XFDF XML)	—	Remove caracteres de controle ilegais em XML 1.0; veja o contrato de comportamento.
XfdfParser::parse	string $xfdfXml	Carrega o XML de forma segura contra XXE e achata os campos para notação de ponto	XfdfData	InvalidArgumentException	Teto de entrada de 10 MiB; aceita raízes com e sem namespace.
XfdfParser::parseFile	string $filePath	Resolve o caminho, lê o arquivo, delega para parse	XfdfData	InvalidArgumentException	Caminhos ausentes, que não sejam arquivo ou ilegíveis geram exceção.
XfaParser::parse	string $pdfData	Verificação de marcador, extração de XML, parsing de pacotes	XfaFormData	InvalidArgumentException, XfaParseException	Ausência do marcador /XFA retorna um resultado vazio, não um erro.
XfaParser::hasXfa	string $pdfData	Varre os bytes em busca do marcador /XFA	bool	—	Varredura de marcador de byte; qualquer ocorrência do token corresponde.
XfaParser::extractXfaXml	string $pdfData	Varredura de stream em busca de marcadores XFA, depois busca direta por <xdp:xdp>	string (XFA XML ou '')	RuntimeException (declarada)	Varre no máximo os primeiros 50 MiB da entrada.
XfaParser::parseXml	string $xml	Extrai os pacotes template e datasets, analisa elementos <field>	XfaFormData	XfaParseException	Teto de 10 MiB de XML, imposto antes do carregamento do DOM.
FormDataBinder::bind	list<FormField> $fields, XfdfData $data	Cria novas instâncias de FormField com valores vinculados	FormDataBindResult	—	Os originais nunca são modificados; caixas de seleção normalizam para Yes/Off.
FormDataBinder::fromXfdf	list<FormField> $fields, string $xfdfXml	Analisa o XFDF, depois vincula	FormDataBindResult	InvalidArgumentException	Os modos de falha são os de XfdfParser::parse.
FormDataBinder::fromArray	list<FormField> $fields, array<string, string> $data	Encapsula o mapa em XfdfData, depois vincula	FormDataBindResult	—	—
FormDataBindResult	isFullyBound, hasNoUnmatchedKeys, boundCount, fieldCount; readonly fields, boundFieldNames, unmatchedDataKeys, unboundFieldNames	Diagnósticos de vínculo imutáveis	por método	—	isFullyBound requer zero chaves não correspondidas e zero campos não vinculados.
XfdfData	hasField, getValue, count, isEmpty, getFieldNames, withField, withoutField, merge; readonly fields	Contêiner imutável de nome para valor	por método	—	with* e merge retornam novas instâncias; merge prefere os valores do argumento.
XfaFormData	getField, hasField, count, fieldNames; readonly fields, templateXml, datasetsXml	Resultado imutável de parsing XFA	por método	—	Carrega o XML bruto dos pacotes template e datasets para ida e volta.
XfaFormField	readonly name, type, value, required, caption, options	Registro imutável de campo único	—	—	type é um de text, numeric, date, choice, button, signature.
XfaPacket	casos de enum Template, Datasets, Config, LocaleSet, ConnectionSet, Form; xmlNamespace()	Enumeração de pacotes lastreada por string	string de xmlNamespace()	—	URIs de namespace seguem a XFA Specification 3.3.

public static function extract(array $fields): XfdfData
public static function toArray(array $fields): array
public static function toXfdf(array $fields, ?string $pdfHref = null): string
public static function extractNonEmpty(array $fields): XfdfData
public static function getEmptyFieldNames(array $fields): array

public static function fromFields(array $fields, ?string $pdfHref = null): string
public static function fromArray(array $data, ?string $pdfHref = null): string
public static function fromXfdfData(XfdfData $data, ?string $pdfHref = null): string

public static function parse(string $xfdfXml): XfdfData
public static function parseFile(string $filePath): XfdfData

public function parse(string $pdfData): XfaFormData
public function hasXfa(string $pdfData): bool
public function extractXfaXml(string $pdfData): string
public function parseXml(string $xml): XfaFormData

public static function bind(array $fields, XfdfData $data): FormDataBindResult
public static function fromXfdf(array $fields, string $xfdfXml): FormDataBindResult
public static function fromArray(array $fields, array $data): FormDataBindResult

Exceções

• NextPDF\Pro\Form\Exception\XfaParseException estende RuntimeException — a carga XFA não pode ser analisada em um XfaFormData. A subclassificação é deliberada: os pontos de chamada catch (RuntimeException $e) existentes continuam funcionando.
• InvalidArgumentException da SPL — entrada vazia, grande demais, malformada ou não-XFDF para XfdfParser; entrada de PDF vazia para XfaParser::parse; caminhos ilegíveis em XfdfParser::parseFile.

Contrato de comportamento

Extração de AcroForm. FormDataExtractor percorre a lista de campos que você passa e lê o nome e o valor de cada campo. extract retorna um XfdfData; toArray retorna um mapa simples de string de nome para valor. extractNonEmpty descarta campos cujo valor é a string vazia; getEmptyFieldNames retorna a lista complementar de nomes. A extração nunca altera os campos de entrada.

Escrita de XFDF. XfdfWriter produz um documento em conformidade com a estrutura da ISO 19444-1:2019. A saída começa com a declaração XML do XFDF e uma raiz xfdf no namespace XFDF da Adobe (http://ns.adobe.com/xfdf/) com xml:space="preserve". Um pdfHref não nulo emite uma referência <f href="..."/> de volta ao PDF de origem. Nomes de campo em notação de ponto (por exemplo address.city) se aninham em uma árvore hierárquica de elementos <field>. Valores e atributos escapam os cinco metacaracteres do XML. Nomes de campo, valores e o pdfHref são adicionalmente normalizados para boa formação: os caracteres de controle C0 que o XML 1.0 proíbe são removidos, enquanto TAB, LF e CR são preservados. Essa normalização é perdedora por design, então o writer sempre emite XFDF bem formado e re-analisável, independentemente dos bytes fornecidos pelo chamador.

Leitura de XFDF. XfdfParser aceita raízes xfdf com e sem namespace e corresponde ao nome da raiz sem diferenciar maiúsculas de minúsculas, porque alguns produtores emitem um elemento raiz em maiúsculas. Árvores hierárquicas de <field> achatam de volta para nomes em notação de ponto, então escrita e leitura fazem ida e volta. Todo o carregamento de XML desabilita o acesso à rede e a resolução de entidades externas. parseFile adiciona resolução de caminho e verificações de legibilidade antes do mesmo parsing.

Vinculação de dados. FormDataBinder::bind corresponde chaves de dados a nomes de campo. Como FormField é imutável, a vinculação cria novas instâncias com valores atualizados; os originais nunca são modificados. O resultado reporta três conjuntos de diagnóstico: nomes de campo vinculados, chaves de dados sem campo correspondente e campos que não receberam dados. Valores de caixa de seleção normalizam para o modelo de estado on/off da ISO 32000-2:2020, 12.7.5.2.3: yes, true, 1 e on (sem diferenciar maiúsculas de minúsculas) mapeiam para Yes; qualquer outro valor mapeia para Off.

Extração de dados XFA. XfaParser::parse aceita bytes brutos de PDF. Primeiro varre em busca do marcador /XFA; na ausência do marcador retorna um XfaFormData vazio. A extração então tenta duas estratégias: uma varredura de blocos stream…endstream em busca de indicadores de XML XFA, depois uma busca direta por um documento <xdp:xdp>. Um único fragmento xdp:xdp é retornado como está; múltiplos fragmentos são concatenados em um envelope xdp:xdp sintetizado. parseXml extrai os pacotes template e datasets e analisa cada elemento <field> do template em um XfaFormField: o atributo name é obrigatório, o type deriva do elemento filho UI do campo, o sinalizador required deriva de um elemento validate com nullTest definido como error, e as opções de choice vêm de filhos items.

O suporte a XFA é orientado a dados. O parser estrutura os pacotes template e datasets. Ele não executa scripts de cálculo XFA, não renderiza layouts XFA dinâmicos nem faz ida e volta de todo tipo de pacote. Valide o parser contra o seu conjunto específico de documentos antes de depender dele.

Casos extremos & modos de falha

• XfdfParser::parse('') lança InvalidArgumentException. Entrada acima de 10 MiB lança InvalidArgumentException nomeando o teto.
• XML malformado lança InvalidArgumentException carregando as mensagens libxml coletadas. Um documento bem formado cuja raiz não é xfdf lança e nomeia o elemento raiz real.
• Um documento XFDF sem um elemento <fields> é analisado para um XfdfData vazio; isso não é um erro.
• Elementos de campo sem um atributo name são ignorados tanto no parsing de XFDF quanto de XFA. Um campo XFDF sem um filho <value> não contribui com nenhuma entrada.
• XfaParser::parse('') lança InvalidArgumentException. Um PDF sem o marcador /XFA, ou um cujo XML XFA não pode ser localizado, retorna um XfaFormData vazio em vez de lançar.
• hasXfa é uma varredura de marcador de byte: qualquer token /XFA no arquivo corresponde, incluindo um em um objeto não utilizado. A etapa de extração subsequente decide se existe XML utilizável.
• A extração XFA examina no máximo os primeiros 50 MiB da string de bytes do PDF; conteúdo além desse limite não é varrido.
• XML XFA acima de 10 MiB lança XfaParseException antes que qualquer árvore DOM seja materializada. XML XFA malformado lança XfaParseException com as mensagens libxml.
• A normalização de caixa de seleção nunca deixa passar valores não reconhecidos; qualquer coisa fora das formas de “on” aceitas mapeia para Off.
• A remoção de caracteres de controle do writer é perdedora: bytes C0 ilegais em XML 1.0 em nomes, valores ou no pdfHref são descartados para que a saída permaneça bem formada. TAB, LF e CR sobrevivem.
• Todo o parsing de XML desabilita a resolução de entidades externas e o acesso à rede (seguro contra XXE).
• Este módulo não realiza operações criptográficas; o modo FIPS não altera o seu comportamento.

Conformidade

Comportamento	Referência	Status
Modelo de formulário interativo / dicionário de campos	ISO 32000-2:2020, 12.7	Alinhado (fundamentado no produto)
Normalização de estado on/off de caixa de seleção (Yes/Off)	ISO 32000-2:2020, 12.7.5.2.3	Alinhado; cláusula citada no registro de citações desta página
Estrutura de troca de dados XFDF	ISO 19444-1:2019	Alinhado (fundamentado no produto)
Nomes de pacotes XFA e URIs de namespace	XFA Specification 3.3	Alinhado (fundamentado no produto)

O corpus RAG disponível no momento da autoria não inclui a ISO 19444-1:2019, a XFA Specification ou o W3C XML 1.0, então essas declarações de alinhamento são fundamentadas no produto a partir de anotações de fonte e testes, em vez de citadas por cláusula. Essas declarações descrevem o recurso em relação aos documentos referenciados. A NextPDF não detém nenhuma certificação de conformidade, e o suporte a uma cláusula não é uma declaração de certificação.

Notas de desenvolvimento

• Todo ponto de entrada exceto XfaParser é estático. XfaParser é instanciável e sem estado; uma instância pode ser reutilizada com segurança entre documentos.
• A ida e volta pretendida é: o leitor de formulários do Core produz valores FormField; FormDataExtractor ou XfdfWriter os serializa; XfdfParser lê os dados de volta; FormDataBinder os aplica a uma lista de campos. Nomes hierárquicos sobrevivem à ida e volta por meio da notação de ponto.
• Use os diagnósticos de FormDataBindResult (isFullyBound, unmatchedDataKeys, unboundFieldNames) para detectar divergência entre um arquivo de dados XFDF e um template PDF revisado antes de aceitar um preenchimento.
• XfdfData é um objeto de valor: withField, withoutField e merge retornam novas instâncias. Em colisões de chave, merge prefere os valores do argumento.
• XfaFormData retém o XML bruto dos pacotes template e datasets (templateXml, datasetsXml) para que você possa pós-processar pacotes que o modelo de campo não cobre.
• Este módulo não analisa dicionários AcroForm a partir dos bytes do PDF por si só; ele consome campos produzidos pelo leitor de formulários do Core. Apenas XfaParser opera sobre conteúdo bruto de PDF.

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 arquivo de runbook e prefixos de ticket estão fora do escopo.

Veja também

• Form — visão geral do recurso
• Interop — Referência Profunda
• Módulo Form do Core