Formulario

De un vistazo

NextPDF Pro lee y escribe datos de formularios interactivos: valores de campo AcroForm, archivos de datos XFDF y los datos que transportan las plantillas XFA (XML Forms Architecture). Complementa el lector de formularios de Core de código abierto con vinculación de datos, extracción y serialización.

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 ese derecho no carga las clases de la capacidad. Compare ediciones y obtenga una licencia.

Form forma parte de la edición Pro. No hay ningún indicador de licencia independiente por función.

Instalación

composer require nextpdf/pro:^3

La capacidad Form requiere una licencia de NextPDF Pro válida. Consulte Disponibilidad y licencias.

Descripción conceptual

Un formulario PDF interactivo —a veces llamado AcroForm— almacena cada campo en un diccionario de campo, tal como se define en ISO 32000-2 §12.7. NextPDF Pro se basa en el lector de formularios de Core para añadir tres capacidades:

• Ida y vuelta de AcroForm. FormDataExtractor lee los pares nombre/valor de los campos de formulario analizados y produce un objeto XfdfData o un mapa simple name → value. XfdfWriter realiza la operación inversa, generando un documento XFDF.
• Lectura y escritura de XFDF. XFDF es el formato de intercambio de datos XML para valores de formulario descrito por ISO 19444-1:2019. XfdfParser lee un archivo XFDF en datos estructurados; XfdfWriter serializa los valores de campo a XFDF, con una referencia opcional de vuelta al PDF de origen.
• Extracción de datos XFA. XfaParser localiza los paquetes XFA de un documento, concatena los fragmentos XML y analiza los paquetes template y datasets en datos de campo estructurados.

Alcance del soporte de XFA

El soporte de XFA en NextPDF Pro está orientado a datos, no es un motor completo de renderizado ni de scripting de XFA. El analizador extrae y estructura los paquetes template y datasets para que pueda leer las definiciones y los valores de los campos. No ejecuta scripts de cálculo de formularios XFA, no renderiza maquetaciones XFA dinámicas ni hace la ida y vuelta de todos los tipos de paquete XFA. Pruebe el analizador con sus documentos específicos antes de confiar en él para un conjunto de formularios XFA dado. Todo el análisis de XML deshabilita la carga de entidades externas (seguro frente a XXE).

Por qué funciona así

El soporte de XFA se limita a los datos, no al renderizado, de forma deliberada. ISO 32000-2 marca la entrada XFA del diccionario de formulario como obsoleta en PDF 2.0 (§12.7). Un motor completo de maquetación y scripting de XFA perseguiría una superficie heredada que la mayoría de las cargas de trabajo ya no necesitan. En su lugar, NextPDF Pro extrae los paquetes template y datasets, donde reside el dato de campo duradero, y descarta el resto. La misma postura impulsa el análisis con XXE desactivado y el tope de escaneo, porque la entrada de formularios a menudo llega de partes no confiables. Eso mantiene la superficie de formularios de Pro como una extensión fina y predecible del modelo AcroForm de Core.

Contexto de diseño: Del formulario rellenable al registro congelado: rellenar y aplanar AcroForm.

Superficie de la API

Clase	Responsabilidad
FormDataExtractor	Extraer los valores de campo AcroForm como XfdfData o un array.
XfdfParser	Analizar un documento XFDF en datos estructurados.
XfdfWriter	Serializar los valores de campo a XFDF, con referencia PDF opcional.
XfaParser	Extraer y analizar los paquetes template y datasets de XFA.
FormDataBinder	Vincular un mapa de datos de vuelta a los campos de formulario.

La referencia completa a nivel de método está en la referencia profunda de Form.

Ejemplo de código — Inicio rápido

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

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

Ejemplo de código — Producción

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 límite y trampas

• XfaParser rechaza una entrada de PDF mayor que su tope de escaneo en lugar de leer datos no acotados.
• Un documento puede transportar tanto formularios interactivos como no interactivos; la extracción apunta a los diccionarios de campo terminales.
• XFDF hace la ida y vuelta de estructuras de campo planas; las jerarquías de campo muy anidadas pueden requerir un tratamiento explícito.

Rendimiento

La extracción y la serialización son lineales respecto al número de campos de formulario. El coste del análisis de XFA escala con el tamaño de los paquetes XML incrustados.

Notas de seguridad

Todo el análisis de XML deshabilita la resolución de entidades externas para prevenir XXE. Trate las entradas XFDF y XFA de fuentes no confiables como hostiles y valide el conjunto de campos analizado antes de vincularlo de vuelta a un documento.

Conformidad

Comportamiento	Referencia	Estado
Modelo de formulario interactivo / diccionario de campo	ISO 32000-2 §12.7	Alineado (parafraseado)
Formato de intercambio de datos XFDF	ISO 19444-1:2019	Alineado

Esta tabla registra las especificaciones frente a las que está construido NextPDF Pro. No es una declaración de certificación formal.

Contrato de comportamiento

• FormDataExtractor lee los pares nombre/valor de los diccionarios de campo terminales analizados y devuelve un objeto XfdfData o un array simple name → value.
• XfdfParser analiza un documento XFDF en datos estructurados; XfdfWriter serializa los valores de campo a XFDF con una referencia opcional de vuelta al PDF de origen.
• XfaParser localiza los paquetes XFA, concatena los fragmentos XML y analiza los paquetes template y datasets en datos de campo estructurados. Rechaza una entrada de PDF mayor que su tope de escaneo en lugar de leer datos no acotados.
• El soporte de XFA está orientado a datos: el analizador extrae y estructura los paquetes template y datasets. No ejecuta scripts de cálculo de formularios XFA, no renderiza maquetaciones XFA dinámicas ni hace la ida y vuelta de todos los tipos de paquete XFA.
• Todo el análisis de XML deshabilita la resolución de entidades externas (seguro frente a XXE).

Nota sobre el límite de Enterprise

Enterprise no cambia el comportamiento de Form. Enterprise añade funciones de cumplimiento y archivo de nivel superior documentadas por separado; no son necesarias para la ida y vuelta de AcroForm, la lectura/escritura de XFDF ni la extracción de datos XFA.

Alternativa / recurso de reserva de Core

El lector de formularios de código abierto de NextPDF Core lee los campos de formulario. La lectura/escritura de XFDF, la extracción de datos XFA y la vinculación de campos son adiciones de Pro. Consulte /modules/form/.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API 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 tickets quedan fuera de alcance.

Véase también

• Interop — DTO de datos de formulario versionados para sistemas externos.
• Módulo Form de Core — lector de formularios de código abierto.
• Form — Referencia profunda — referencia a nivel de método para las clases de formulario de Pro.