Formulario: campos interactivos AcroForm y aplanado

De un vistazo

El módulo Form permite crear formularios PDF interactivos. Crea campos de texto, casillas de verificación, opciones excluyentes, campos de elección (lista/desplegable), botones y campos de firma. Los organiza en una jerarquía parent/child y los escribe como objetos PDF con flujos de apariencia. También puede aplanar el formulario como contenido estático de página.

Instalación

composer require nextpdf/core:^3

Visión conceptual

Un formulario PDF interactivo se representa mediante AcroForm: una jerarquía de campos a nivel de documento en la que los campos terminales se emparejan con anotaciones de widget en las páginas. ISO 32000-2 §12.7 define ese formulario y sus diccionarios de campo, incluida la raíz AcroForm y la jerarquía de campos. Este módulo actúa como codificador del motor para ese modelo.

FormFieldManager es la superficie de API principal. Expone los constructores textField(), checkBox(), radioButton(), button() y signatureField(), registra los campos y los serializa con writeFields(). Emite un flujo de apariencia Form XObject por cada widget (/Subtype /Form, /BBox), tal como exige §8.10. FormField es el objeto de valor del campo. FormFieldDictionaryBuilder convierte un campo en su diccionario PDF y aplica las entradas y los bits de marca específicos de cada tipo (texto, casilla de verificación, elección, botón). El gestor y FormField están marcados como @since 1.0.0. El constructor de diccionarios está marcado como @since 1.1.0.

FormFieldHierarchy modela el árbol de campos parent/child: addChild(), getRootFieldNames(), getChildren(), getParent() y un visitante walkDepthFirst(). Un nombre de campo plenamente cualificado es la ruta con puntos dentro de esta jerarquía, el modelo que §12.7 especifica para los campos anidados.

FormFlattener representa el formulario como contenido estático de página —flatten() devuelve un FlattenResult—, de modo que un formulario rellenado pueda congelarse para su archivado. FieldMDP y FieldMdpAction modelan la transformación de bloqueo de campos. Un documento firmado puede bloquear un conjunto de campos con nombre frente a modificaciones posteriores. FieldMdpAction enumera el alcance del bloqueo. Su requiresFieldList() indica cuándo se requiere una lista de campos explícita. FieldMDP está marcado como @since 2.0.0.

Superficie de API

Clase	Miembros clave	Función
FormFieldManager	textField(), checkBox(), radioButton(), button(), signatureField(), addChildField(), getHierarchy(), writeFields()	Constructor de campos + serializador (@since 1.0.0)
FormField	objeto de valor del campo	Un campo AcroForm (@since 1.0.0)
FormFieldDictionaryBuilder	buildFieldDictionary(), applyTextFieldOptions(), applyCheckBoxOptions(), applyChoiceFieldOptions(), applyButtonOptions()	Constructor de campo a diccionario (@since 1.1.0)
FormFieldHierarchy	addChild(), getRootFieldNames(), getChildren(), getParent(), walkDepthFirst()	Árbol de campos parent/child (@since 2.0.0)
FormFlattener	flatten(array $fields, array $pages): FlattenResult	Aplana el formulario a contenido estático (@since 1.0.0)
FieldMDP	toTransformParams()	Transformación de bloqueo de campos (FieldMDP) (@since 2.0.0)
FieldMdpAction (enum)	requiresFieldList()	Alcance del bloqueo de campos (@since 2.0.0)

Ejecutar composer docs:generate-api-php -- --module=Form para ver la tabla PHPDoc completa.

Ejemplo de código — Inicio rápido

Fuente: examples/30-form-fields.php.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Form\FormFieldManager;

$form = new FormFieldManager();

$form->textField(name: 'applicant_name', x: 50, y: 700, w: 200, h: 18);
$form->checkBox(name: 'agree_terms', x: 50, y: 660, size: 12);
$form->radioButton(name: 'plan', x: 50, y: 620, size: 12 /* + option set */);

// The Writer invokes $form->writeFields(...) during document serialization.

Ejemplo de código — Producción

Construir un conjunto de campos para un documento firmado y bloquear los campos firmados con FieldMDP.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Form\FieldMDP;
use NextPDF\Form\FieldMdpAction;
use NextPDF\Form\FormFieldManager;

$form = new FormFieldManager();
$form->textField(name: 'contract_value', x: 50, y: 700, w: 160, h: 18);
$form->signatureField(name: 'approver_sig', x: 50, y: 600, w: 200, h: 60);

// Lock only the named fields after signing.
$lock = new FieldMDP(
    action: FieldMdpAction::Include,
    fields: ['contract_value'],
);

$transformParams = $lock->toTransformParams();
// $transformParams is attached to the signature's transform method by the signing layer.

Casos límite y trampas

• Un nombre de campo es una ruta con puntos plenamente cualificada dentro de FormFieldHierarchy. Dos campos terminales con el mismo nombre plenamente cualificado son el mismo campo lógico en un visor; la unicidad es responsabilidad del código llamador.
• FieldMdpAction::requiresFieldList() indica cuándo es obligatoria una lista de campos. Una acción Include/Exclude sin la lista requerida es un bloqueo mal formado; hay que comprobar la marca.
• FormFlattener::flatten() es destructivo para la interactividad por diseño: el resultado es contenido estático. Conservar la fuente interactiva si se necesita más adelante.
• Los flujos de apariencia se emiten por cada widget. Un campo sin apariencia se representa de forma inconsistente entre visores; permitir que el gestor genere la apariencia en lugar de omitirla.
• signatureField() crea únicamente el marcador de posición del campo. Producir la firma real es tarea de la capa de Seguridad/firma, no de este módulo.

Rendimiento

La creación y la serialización de campos tienen coste O(n) en función del número de campos, más un flujo de apariencia Form XObject por cada widget. El coste del aplanado escala con el contenido representado, no con el número de campos. La carga de trabajo de referencia predeterminada se mantiene dentro del presupuesto de 1500 ms de tiempo de pared / 64 MB de pico. El perfil de reproducibilidad es structural: los números de objeto y el /ID del tráiler varían entre ejecuciones. Dos documentos con el mismo formulario son estructuralmente iguales, pero no idénticos byte a byte.

Notas de seguridad

Los valores de los campos del formulario son entrada de usuario. El módulo aplica escape a los valores de cadena para la serialización PDF (PdfStringEscaper), de modo que el valor de un campo no pueda salirse de su cadena PDF e inyectar estructura. Cuando un formulario está cifrado, el contenido de los campos queda cubierto por el cifrado AES-256 del documento. FieldMDP es un control de seguridad: bloquea los campos con nombre frente a modificaciones posteriores a la firma. Un bloqueo de campos que no coincide con el conjunto de campos firmados socava ese control; definir el alcance del bloqueo de forma deliberada. Tratar cualquier valor extraído de un formulario rellenado como entrada no confiable. Consultar el modelo de seguridad del motor en /modules/core/security/.

Conformidad

Las estructuras de formulario que emite este módulo siguen el modelo de formulario interactivo de ISO 32000-2 §12.7: la raíz AcroForm, los diccionarios de campo y la jerarquía de campos del documento. Las apariencias por widget se emiten como Form XObjects según §8.10, tal como se documenta en línea en src/Form/. Se trata de hechos de implementación ejercitados por tests/Unit/Form/. No constituyen una declaración de conformidad PDF 2.0 de extremo a extremo. La conformidad del documento completo la validan el oráculo y las suites de referencia en /modules/core/conformance/.

Véase también

• Módulo Navigation — anotaciones de widget con las que se emparejan los campos.
• Módulo Security — la firma y el modelo de confianza FieldMDP.
• Módulo Accessibility — etiquetado de campos de formulario para PDF/UA.
• Visión general de conformidad