Crea y rellena previamente un formulario PDF

De un vistazo

Un AcroForm es el formulario interactivo que forma parte de un PDF. Esta receta crea uno y rellena previamente sus campos con valores iniciales. El trait HasFormFields del núcleo es una API de creación de formularios: permite crear cada campo y proporcionar su valor en la misma llamada. Se usa el argumento default para los campos de texto, selected para los campos de selección y checked para las casillas de verificación. Así, el PDF se abre con los campos ya rellenados, que siguen siendo editables en un lector conforme. La persona que abra el archivo aún puede modificarlos. Esta receta sigue examples/30-form-fields.php.

Límite de alcance. El núcleo crea y rellena campos de formulario mientras construye el documento. No lee un formulario ya existente en un PDF de terceros ni fusiona en él un mapa de valores. Aquí, «rellenar» significa crear el formulario con valores, no cargar y rellenar un PDF externo. El flujo de ida y vuelta con un formulario externo es una capacidad de Premium y del servidor, no una API pública del núcleo.

Instalación

composer require nextpdf/core:^3

Panorama conceptual

Un campo de AcroForm guarda su valor actual en la entrada V del diccionario del campo (ISO 32000-2 §12.7). También puede contener un valor predeterminado opcional en DV, al que el campo vuelve cuando se ejecuta una acción de restablecimiento del formulario. NextPDF asigna V a partir del valor que se pasa a cada constructor de campo. El renderizado del texto usa una cadena de apariencia predeterminada (DA).

El perfil es structural porque el documento incluye un arreglo /ID en el tráiler. El paso posterior normaliza ese identificador volátil antes de realizar la comparación.

Superficie de la API

NextPDF\Core\Concerns\HasFormFields (incorporado en Document):

textField(string $name, float $x, float $y, float $w, float $h, string $default = '', array $options = []): static
checkBox(string $name, float $x, float $y, float $size, bool $checked = false): static
radioButton(string $name, float $x, float $y, float $size, string $value, string $group): static
comboBox(string $name, float $x, float $y, float $w, float $h, array $items, string $selected = ''): static
listBox(string $name, float $x, float $y, float $w, float $h, array $items, string $selected = ''): static
button(string $name, float $x, float $y, float $w, float $h, string $caption, string $action = ''): static

Los argumentos default, checked y selected contienen los valores usados para el rellenado previo.

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Pre-filled Form');
$doc->addPage();

// Text field pre-filled with a value (sets the field dictionary /V entry).
$doc->textField(name: 'full_name', x: 20, y: 30, w: 90, h: 8, default: 'Ada Lovelace');

// Choice field pre-selected.
$doc->comboBox(
    name: 'country',
    x: 20, y: 45, w: 90, h: 8,
    items: ['United Kingdom', 'Taiwan', 'Japan'],
    selected: 'Taiwan',
);

// Checkbox pre-checked.
$doc->checkBox(name: 'newsletter', x: 20, y: 60, size: 5, checked: true);

$doc->save(__DIR__ . '/prefilled-form.pdf');
echo "Wrote prefilled-form.pdf\n";

Ejemplo de código — Producción

El ejemplo completo siguiente refleja examples/30-form-fields.php, un formulario de registro con varias secciones. Usa NEXTPDF_COOKBOOK_OUTPUT como destino para el arnés de pruebas.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Customer Registration — Pre-filled');
$doc->addPage();

$doc->setFont('helvetica', 'B', 20);
$doc->cell(0, 14, 'Customer Registration Form', newLine: true);
$doc->ln(4);

$leftMargin = 15.0;
$fieldX     = 70.0;
$fieldW     = 120.0;
$fieldH     = 8.0;
$rowSpacing = 12.0;

// --- Personal information, pre-filled ---
$prefill = [
    'full_name' => 'Ada Lovelace',
    'email'     => '[email protected]',
    'phone'     => '+44 20 7946 0000',
    'company'   => 'Analytical Engines Ltd',
];

$y = 40.0;
$doc->setFont('helvetica', '', 10);
foreach ($prefill as $name => $value) {
    $doc->setXY($leftMargin, $y);
    $doc->cell(50, $fieldH, ucwords(str_replace('_', ' ', $name)) . ':');
    $doc->textField(
        name: $name,
        x: $fieldX,
        y: $y,
        w: $fieldW,
        h: $fieldH,
        default: $value,
        options: ['maxLen' => 80],
    );
    $y += $rowSpacing;
}

// --- Choice field, pre-selected ---
$y += 6;
$doc->setXY($leftMargin, $y);
$doc->cell(50, $fieldH, 'Country:');
$doc->comboBox(
    name: 'country',
    x: $fieldX,
    y: $y,
    w: $fieldW,
    h: $fieldH,
    items: ['United States', 'United Kingdom', 'Germany', 'Japan', 'Taiwan'],
    selected: 'United Kingdom',
);

// --- Checkboxes, pre-set ---
$y += $rowSpacing + 6;
$doc->setXY($leftMargin, $y);
$doc->cell(0, 7, 'Subscribe to newsletter');
$doc->checkBox(name: 'newsletter', x: $leftMargin + 70, y: $y, size: 5, checked: true);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/registration-prefilled.pdf');

echo "Wrote pre-filled registration form\n";

Salida esperada:

Wrote pre-filled registration form

Al abrir el PDF, cada campo ya está rellenado y sigue siendo editable.

Casos límite y trampas

Los nombres de los campos deben ser únicos. Dos campos que comparten un nombre se convierten en un único campo lógico con un valor compartido en los lectores conformes. Eso es lo esperado para campos enlazados, pero resulta inesperado en caso contrario.
Semántica de los grupos de botones de opción. radioButton() vincula cada opción a un group. La opción seleccionada es aquella cuyo value coincide con el valor del grupo. Solo una opción por grupo está activa a la vez.
maxLen es una sugerencia. Una opción maxLen limita la longitud de entrada en los lectores conformes. No limita el valor almacenado que se establece al rellenar previamente el campo.
En la API, las coordenadas son la esquina superior izquierda. El trait realiza por sí mismo la conversión al origen en la esquina inferior izquierda del PDF; por tanto, pasar las coordenadas de la esquina superior izquierda, como muestra el ejemplo.
Sin rellenado de PDF externo. Ningún método del núcleo carga un formulario de terceros existente y aplica un mapa de valores. Véase el límite de alcance anterior.

Rendimiento

La creación de formularios escala linealmente con la cantidad de campos. Cada campo añade una anotación de widget y una apariencia. Unos pocos cientos de campos se mantienen con holgura dentro del presupuesto de 1500 ms / 64 MB.

Notas de seguridad

Los valores rellenados previamente se escriben tal cual en el diccionario del campo. Se debe escapar o validar cualquier valor procedente de una entrada no confiable antes de colocarlo en un documento que se vaya a distribuir. Un formulario rellenado previamente no está protegido: cualquiera que pueda abrir el PDF puede leer y cambiar los valores. Cuando el contenido del formulario sea sensible, conviene combinar esta receta con Cifrar con permisos, y tener en cuenta la advertencia sobre la cooperación del lector indicada allí.

Conformidad

Declaración	Especificación	Cláusula
El valor actual del campo se almacena en la entrada `V` del diccionario del campo.	ISO 32000-2	§12.7
El valor predeterminado se almacena en la entrada `DV` y se restaura al restablecer el formulario.	ISO 32000-2	§12.7
El formato del texto del campo utiliza la cadena de apariencia predeterminada `DA`.	ISO 32000-2	§12.7

NextPDF emite la estructura AcroForm descrita por las cláusulas citadas. No declara conformidad completa con ISO 32000-2.