Creare e precompilare un modulo PDF

In breve

Un AcroForm è il modulo interattivo contenuto in un PDF. Questa ricetta ne crea uno e ne precompila i campi con valori iniziali. Il trait HasFormFields di Core è un’API per la creazione di moduli: consente di creare ogni campo e fornirne il valore nella stessa chiamata. Usare l’argomento default per i campi di testo, selected per i campi di scelta e checked per le caselle di controllo. Il PDF si apre quindi con i campi già compilati; i campi restano modificabili in un reader conforme e chiunque apra il file può comunque modificarli. Questa ricetta segue examples/30-form-fields.php.

Limite dell’ambito. Core crea e compila i campi del modulo durante la costruzione del documento. Non legge un modulo già esistente in un PDF di terze parti né vi applica una mappa di valori. Qui «compilare» significa creare il modulo con i valori, non caricare e compilare un PDF esterno. L’elaborazione round-trip di un modulo esterno è una funzionalità di Premium e del server, non un’API pubblica di Core.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Un campo AcroForm conserva il proprio valore corrente nella voce V del dizionario del campo (ISO 32000-2 §12.7). Può inoltre contenere un valore predefinito facoltativo in DV, a cui il campo ritorna quando viene eseguita un’azione di reimpostazione del modulo. NextPDF imposta V a partire dal valore passato a ciascun costruttore di campo. Il rendering del testo utilizza una stringa di aspetto predefinita (DA).

Il profilo è structural perché il documento contiene un array /ID nel trailer. Il passaggio di post-elaborazione normalizza quell’identificatore volatile prima del confronto.

Superficie dell’API

NextPDF\Core\Concerns\HasFormFields (integrato in 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

Gli argomenti default, checked e selected forniscono i valori di precompilazione.

Esempio di codice — Avvio rapido

<?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";

Esempio di codice — Produzione

L’esempio completo riportato di seguito rispecchia examples/30-form-fields.php, un modulo di registrazione con diverse sezioni. Scrive nel percorso indicato da NEXTPDF_COOKBOOK_OUTPUT per l’harness di test.

<?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";

Output previsto:

Wrote pre-filled registration form

All’apertura del PDF, ogni campo è già compilato e resta modificabile.

Casi limite e insidie

I nomi dei campi devono essere univoci. Due campi che condividono lo stesso nome diventano un unico campo logico con un valore condiviso nei reader conformi. È il comportamento desiderato per i campi collegati, ma può sorprendere negli altri casi.
Semantica dei gruppi di pulsanti di opzione. radioButton() associa ogni opzione a un group. L’opzione selezionata è quella il cui value corrisponde al valore del gruppo. È attiva una sola opzione per gruppo alla volta.
maxLen è un suggerimento. Un’opzione maxLen limita la lunghezza dell’input nei reader conformi. Non limita il valore memorizzato durante la precompilazione.
Nell’API le coordinate hanno origine in alto a sinistra. Il trait converte automaticamente verso l’origine in basso a sinistra del PDF; quindi passare le coordinate in alto a sinistra, come mostra l’esempio.
Nessuna compilazione di PDF esterni. Nessun metodo di Core carica un modulo di terze parti esistente e vi applica una mappa di valori. Vedere il limite dell’ambito riportato sopra.

Prestazioni

La creazione del modulo scala linearmente con il numero di campi. Ogni campo aggiunge un’annotazione widget e un aspetto. Alcune centinaia di campi restano ampiamente entro il budget di 1500 ms / 64 MB.

Note sulla sicurezza

I valori precompilati vengono scritti così come sono nel dizionario del campo. Eseguire l’escape o convalidare qualsiasi valore proveniente da input non attendibile prima di inserirlo in un documento da distribuire. Un modulo precompilato non è protetto: chiunque possa aprire il PDF può leggere e modificare i valori. Quando il contenuto del modulo è sensibile, combinare questa ricetta con Cifratura con autorizzazioni e tenere presente l’avvertenza sulla cooperazione del reader riportata in quella pagina.

Conformità

Dichiarazione	Specifica	Clausola
Il valore corrente del campo è memorizzato nella voce `V` del dizionario del campo.	ISO 32000-2	§12.7
Il valore predefinito è memorizzato nella voce `DV` e viene ripristinato alla reimpostazione del modulo.	ISO 32000-2	§12.7
La formattazione del testo del campo utilizza la stringa di aspetto predefinita `DA`.	ISO 32000-2	§12.7

NextPDF emette la struttura AcroForm descritta dalle clausole citate. Non dichiara la piena conformità a ISO 32000-2.