Form — Referencia detallada

De un vistazo

Esta página es la referencia detallada del módulo Form de Pro. Cubre la extracción de valores AcroForm, la lectura y escritura XFDF, el enlazado de datos y la extracción de datos XFA. El módulo consume valores NextPDF\Form\FormField producidos por el lector de formularios de Core y les añade serialización, análisis y enlazado. La compatibilidad con XFA está orientada a los datos: el analizador estructura los paquetes template y datasets. No ejecuta scripts de cálculo XFA ni renderiza diseños XFA dinámicos.

Disponibilidad y licencia

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

No existe ningún indicador de licencia por función. Se trata de una capacidad de la edición Pro.

Superficie pública de la API

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
FormDataExtractor::extract	list<FormField> $fields	Lee el nombre y el valor de cada campo	XfdfData	—	Incluye los campos cuyo valor está vacío.
FormDataExtractor::toArray	list<FormField> $fields	Construye un mapa de cadenas nombre-a-valor	array<string, string>	—	Un nombre duplicado posterior sobrescribe uno anterior.
FormDataExtractor::toXfdf	list<FormField> $fields, ?string $pdfHref = null	Delega en XfdfWriter::fromFields	string (XML XFDF)	—	Vía práctica para exportar en una sola llamada.
FormDataExtractor::extractNonEmpty	list<FormField> $fields	Omite los campos cuyo valor es la cadena vacía	XfdfData	—	—
FormDataExtractor::getEmptyFieldNames	list<FormField> $fields	Lista los nombres de los campos sin valor asignado	list<string>	—	Complemento de extractNonEmpty.
XfdfWriter::fromFields	list<FormField> $fields, ?string $pdfHref = null	Recopila pares nombre-a-valor y delega en fromArray	string (XML XFDF)	—	—
XfdfWriter::fromArray	array<string, string> $data, ?string $pdfHref = null	Envuelve el mapa en XfdfData y delega	string (XML XFDF)	—	—
XfdfWriter::fromXfdfData	XfdfData $data, ?string $pdfHref = null	Serializa a XFDF; los nombres con notación de punto se anidan como elementos <field> jerárquicos	string (XML XFDF)	—	Elimina los caracteres de control ilegales en XML 1.0; véase el contrato de comportamiento.
XfdfParser::parse	string $xfdfXml	Carga el XML de forma segura frente a XXE y aplana los campos a notación de punto	XfdfData	InvalidArgumentException	Límite de entrada de 10 MiB; acepta raíces con y sin espacio de nombres.
XfdfParser::parseFile	string $filePath	Resuelve la ruta, lee el archivo y delega en parse	XfdfData	InvalidArgumentException	Las rutas inexistentes, que no sean archivos o ilegibles lanzan excepción.
XfaParser::parse	string $pdfData	Comprobación del marcador, extracción del XML y análisis de paquetes	XfaFormData	InvalidArgumentException, XfaParseException	La ausencia del marcador /XFA devuelve un resultado vacío, no un error.
XfaParser::hasXfa	string $pdfData	Rastrea los bytes en busca del marcador /XFA	bool	—	Rastreo por marcador de bytes; cualquier aparición del token coincide.
XfaParser::extractXfaXml	string $pdfData	Rastreo del flujo en busca de marcadores XFA y luego búsqueda directa de <xdp:xdp>	string (XML XFA o '')	RuntimeException (declarada)	Rastrea como máximo los primeros 50 MiB de la entrada.
XfaParser::parseXml	string $xml	Extrae los paquetes template y datasets y analiza los elementos <field>	XfaFormData	XfaParseException	Límite de 10 MiB de XML, aplicado antes de cargar el DOM.
FormDataBinder::bind	list<FormField> $fields, XfdfData $data	Crea nuevas instancias FormField con los valores enlazados	FormDataBindResult	—	Los originales nunca se modifican; las casillas de verificación se normalizan a Yes/Off.
FormDataBinder::fromXfdf	list<FormField> $fields, string $xfdfXml	Analiza el XFDF y luego enlaza	FormDataBindResult	InvalidArgumentException	Los modos de fallo son los de XfdfParser::parse.
FormDataBinder::fromArray	list<FormField> $fields, array<string, string> $data	Envuelve el mapa en XfdfData y luego enlaza	FormDataBindResult	—	—
FormDataBindResult	isFullyBound, hasNoUnmatchedKeys, boundCount, fieldCount; readonly fields, boundFieldNames, unmatchedDataKeys, unboundFieldNames	Diagnósticos de enlace inmutables	por método	—	isFullyBound requiere cero claves sin coincidencia y cero campos sin enlazar.
XfdfData	hasField, getValue, count, isEmpty, getFieldNames, withField, withoutField, merge; readonly fields	Contenedor nombre-a-valor inmutable	por método	—	with* y merge devuelven nuevas instancias; merge prefiere los valores del argumento.
XfaFormData	getField, hasField, count, fieldNames; readonly fields, templateXml, datasetsXml	Resultado de análisis XFA inmutable	por método	—	Conserva el XML crudo de los paquetes template y datasets para el round-trip.
XfaFormField	readonly name, type, value, required, caption, options	Registro inmutable de un solo campo	—	—	type es uno de text, numeric, date, choice, button, signature.
XfaPacket	casos de enum Template, Datasets, Config, LocaleSet, ConnectionSet, Form; xmlNamespace()	Enumeración de paquetes respaldada por cadenas	string de xmlNamespace()	—	Las URI de espacio de nombres siguen la 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

Excepciones

• NextPDF\Pro\Form\Exception\XfaParseException extiende RuntimeException — la carga útil XFA no se puede analizar en un XfaFormData. La subclasificación es deliberada: los puntos de llamada catch (RuntimeException $e) existentes siguen funcionando.
• SPL InvalidArgumentException — entrada vacía, sobredimensionada, mal formada o no XFDF en XfdfParser; entrada PDF vacía en XfaParser::parse; rutas ilegibles en XfdfParser::parseFile.

Contrato de comportamiento

Extracción AcroForm. FormDataExtractor recorre la lista de campos que se le pasa y lee el nombre y el valor de cada campo. extract devuelve un XfdfData; toArray devuelve un mapa de cadenas nombre-a-valor simple. extractNonEmpty descarta los campos cuyo valor es la cadena vacía; getEmptyFieldNames devuelve la lista de nombres complementaria. La extracción nunca muta los campos de entrada.

Escritura XFDF. XfdfWriter produce un documento conforme a la estructura ISO 19444-1:2019. La salida comienza con la declaración XML XFDF y una raíz xfdf en el espacio de nombres XFDF de Adobe (http://ns.adobe.com/xfdf/) con xml:space="preserve". Un pdfHref no nulo emite una referencia <f href="..."/> de vuelta al PDF de origen. Los nombres de campo con notación de punto (por ejemplo address.city) se anidan en un árbol de elementos <field> jerárquico. Los valores y atributos escapan los cinco metacaracteres XML. Los nombres de campo, los valores y el pdfHref se normalizan además para garantizar la buena formación: los caracteres de control C0 que XML 1.0 prohíbe se eliminan, mientras que TAB, LF y CR se conservan. Esta normalización es lossy por diseño, de modo que el escritor siempre emite XFDF bien formado y reanalizable, sin importar los bytes suministrados por el llamante.

Lectura XFDF. XfdfParser acepta raíces xfdf con y sin espacio de nombres y coincide el nombre de la raíz sin distinguir mayúsculas y minúsculas, porque algunos productores emiten un elemento raíz en mayúsculas. Los árboles <field> jerárquicos se aplanan de nuevo a nombres con notación de punto, de modo que la escritura y la lectura hacen round-trip. Toda carga de XML deshabilita el acceso a la red y la resolución de entidades externas. parseFile añade la resolución de rutas y las comprobaciones de legibilidad antes del mismo análisis.

Enlazado de datos. FormDataBinder::bind empareja las claves de datos con los nombres de campo. Dado que FormField es inmutable, el enlazado crea nuevas instancias con valores actualizados; los originales nunca se modifican. El resultado informa de tres conjuntos de diagnóstico: los nombres de campo enlazados, las claves de datos sin campo coincidente y los campos que no recibieron datos. Los valores de casilla de verificación se normalizan al modelo de estado on/off de ISO 32000-2:2020, 12.7.5.2.3: yes, true, 1 y on sin distinguir mayúsculas se asignan a Yes; cualquier otro valor se asigna a Off.

Extracción de datos XFA. XfaParser::parse acepta bytes PDF crudos. Primero rastrea el marcador /XFA; en ausencia del marcador devuelve un XfaFormData vacío. La extracción prueba a continuación dos estrategias: un rastreo de bloques stream…endstream en busca de indicadores de XML XFA y luego una búsqueda directa de un documento <xdp:xdp>. Un único fragmento xdp:xdp se devuelve tal cual; varios fragmentos se concatenan en un envoltorio xdp:xdp sintetizado. parseXml extrae los paquetes template y datasets y analiza cada elemento <field> del template en un XfaFormField: el atributo name es obligatorio, el type deriva del elemento hijo UI del campo, el indicador required deriva de un elemento validate con nullTest puesto a error, y las opciones de choice provienen de los hijos items.

La compatibilidad con XFA está orientada a los datos. El analizador estructura los paquetes template y datasets. No ejecuta scripts de cálculo XFA, no renderiza diseños XFA dinámicos ni hace round-trip de todos los tipos de paquete. Valide el analizador con su conjunto específico de documentos antes de confiar en él.

Casos límite y modos de fallo

• XfdfParser::parse('') lanza InvalidArgumentException. Una entrada superior a 10 MiB lanza InvalidArgumentException nombrando el límite.
• El XML mal formado lanza InvalidArgumentException acarreando los mensajes de libxml recopilados. Un documento bien formado cuya raíz no es xfdf lanza excepción y nombra el elemento raíz real.
• Un documento XFDF sin un elemento <fields> se analiza como un XfdfData vacío; eso no es un error.
• Los elementos de campo sin un atributo name se omiten tanto en el análisis XFDF como en el XFA. Un campo XFDF sin un hijo <value> no aporta ninguna entrada.
• XfaParser::parse('') lanza InvalidArgumentException. Un PDF sin el marcador /XFA, o uno cuyo XML XFA no puede localizarse, devuelve un XfaFormData vacío en lugar de lanzar excepción.
• hasXfa es un rastreo por marcador de bytes: cualquier token /XFA del archivo coincide, incluido uno en un objeto no utilizado. El paso de extracción posterior decide si existe XML utilizable.
• La extracción XFA examina como máximo los primeros 50 MiB de la cadena de bytes del PDF; el contenido más allá de ese límite no se rastrea.
• Un XML XFA superior a 10 MiB lanza XfaParseException antes de materializar cualquier árbol DOM. Un XML XFA mal formado lanza XfaParseException con los mensajes de libxml.
• La normalización de casillas de verificación nunca deja pasar valores no reconocidos; cualquier cosa fuera de las formas on aceptadas se asigna a Off.
• La eliminación de caracteres de control del escritor es lossy: los bytes C0 ilegales en XML 1.0 presentes en nombres, valores o el pdfHref se descartan para que la salida siga bien formada. TAB, LF y CR sobreviven.
• Todo análisis de XML deshabilita la resolución de entidades externas y el acceso a la red (seguro frente a XXE).
• Este módulo no realiza operaciones criptográficas; el modo FIPS no cambia su comportamiento.

Conformidad

Comportamiento	Referencia	Estado
Modelo de formulario interactivo / diccionario de campos	ISO 32000-2:2020, 12.7	Alineado (fundamentado en el producto)
Normalización del estado on/off de casillas (Yes/Off)	ISO 32000-2:2020, 12.7.5.2.3	Alineado; cláusula citada en el registro de citas de esta página
Estructura de intercambio de datos XFDF	ISO 19444-1:2019	Alineado (fundamentado en el producto)
Nombres de paquete XFA y URI de espacio de nombres	XFA Specification 3.3	Alineado (fundamentado en el producto)

El corpus RAG disponible en el momento de la redacción no incluye ISO 19444-1:2019, la XFA Specification ni W3C XML 1.0, de modo que esas declaraciones de alineación están fundamentadas en el producto a partir de anotaciones de origen y pruebas en lugar de citarse por cláusula. Estas declaraciones describen la capacidad frente a los documentos referenciados. NextPDF no posee ninguna certificación de conformidad, y la compatibilidad con una cláusula no es una declaración de certificación.

Notas de desarrollo

• Todos los puntos de entrada excepto XfaParser son estáticos. XfaParser es instanciable y sin estado; una instancia se puede reutilizar de forma segura entre documentos.
• El round-trip previsto es: el lector de formularios de Core produce valores FormField; FormDataExtractor o XfdfWriter los serializa; XfdfParser vuelve a leer los datos; FormDataBinder los aplica a una lista de campos. Los nombres jerárquicos sobreviven al round-trip a través de la notación de punto.
• Utilice los diagnósticos de FormDataBindResult (isFullyBound, unmatchedDataKeys, unboundFieldNames) para detectar la deriva entre un archivo de datos XFDF y una plantilla PDF revisada antes de aceptar un rellenado.
• XfdfData es un objeto de valor: withField, withoutField y merge devuelven nuevas instancias. En colisiones de clave, merge prefiere los valores del argumento.
• XfaFormData conserva el XML crudo de los paquetes template y datasets (templateXml, datasetsXml) para que pueda posprocesar los paquetes que el modelo de campos no cubre.
• Este módulo no analiza por sí mismo los diccionarios AcroForm a partir de los bytes del PDF; consume campos producidos por el lector de formularios de Core. Solo XfaParser opera sobre contenido PDF crudo.

Límite de publicación

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

Véase también

• Form — visión general de la capacidad
• Interop — Referencia detallada
• Módulo Form de Core