Een PDF-formulier maken en vooraf invullen

In een oogopslag

Een AcroForm is het interactieve formulier binnen een PDF. In dit recipe bouwt u zo’n formulier op en vult u de velden vooraf met beginwaarden. De Core-HasFormFields-trait is een API om formulieren op te stellen: u maakt elk veld aan en geeft in dezelfde aanroep de waarde ervan op. Gebruik het argument default voor tekstvelden, selected voor keuzevelden en checked voor selectievakjes. De PDF opent met de velden al ingevuld; in een conforme lezer blijven ze bewerkbaar. Iedereen die het bestand opent, kan ze nog steeds wijzigen. Dit recipe volgt examples/30-form-fields.php.

Reikwijdte. Core maakt formuliervelden aan en vult ze in tijdens het opbouwen van het document. Het leest geen formulier dat al in een externe PDF aanwezig is en voegt geen waardetoewijzing samen met zo’n formulier. Hier betekent „invullen” het formulier opstellen met waarden, niet een externe PDF laden en invullen. Het round-trippen van een extern formulier is een functionaliteit van Premium en de server, geen openbare API van Core.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Een AcroForm-veld slaat zijn huidige waarde op in het item V van de velddictionary (ISO 32000-2 §12.7). Het kan ook een optionele standaardwaarde opslaan in DV; naar die waarde keert het veld terug wanneer een reset-form-actie wordt uitgevoerd. NextPDF stelt V in op basis van de waarde die u aan elke veldconstructor doorgeeft. Voor de tekstweergave gebruikt het een standaard-appearance-string (DA).

Het profiel is structural omdat het document een trailer-/ID-array bevat. De nabewerking normaliseert die variabele identificator vóór de vergelijking.

API-oppervlak

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

De argumenten default, checked en selected bevatten de waarden waarmee de velden vooraf worden ingevuld.

Codevoorbeeld — snelstart

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

Codevoorbeeld — productie

Het volledige voorbeeld hieronder komt overeen met examples/30-form-fields.php: een registratieformulier met meerdere secties. Voor de harness schrijft het voorbeeld naar NEXTPDF_COOKBOOK_OUTPUT.

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

Verwachte uitvoer:

Wrote pre-filled registration form

Wanneer u de PDF opent, zijn alle velden al ingevuld en blijven ze bewerkbaar.

Randgevallen en valkuilen

Veldnamen moeten uniek zijn. Twee velden met dezelfde naam vormen in conforme lezers één logisch veld met een gedeelde waarde. Dat is handig voor gekoppelde velden, maar kan anders verrassend zijn.
Semantiek van groepen met keuzerondjes. radioButton() koppelt elke optie aan een group. De geselecteerde optie is degene waarvan de value overeenkomt met de waarde van de groep. Per groep kan steeds maar één optie ingeschakeld zijn.
maxLen is een hint. Een maxLen-optie begrenst de invoerlengte in conforme lezers. De optie beperkt niet de opgeslagen waarde die u vooraf invult.
Coördinaten zijn linksboven in de API. De trait rekent ze voor u om naar de oorsprong linksonder in de PDF, dus geef coördinaten linksboven door, zoals in het voorbeeld.
Geen externe-PDF-invulling. Geen enkele Core-methode laadt een bestaand extern formulier en past daarop een waardetoewijzing toe. Zie de reikwijdte hierboven.

Prestaties

Het opstellen van formulieren schaalt lineair met het aantal velden. Elk veld voegt één widget-annotatie en één appearance toe. Een paar honderd velden blijven ruim binnen het budget van 1500 ms / 64 MB.

Beveiligingsopmerkingen

Vooraf ingevulde waarden worden letterlijk in de velddictionary geschreven. Escape of valideer elke waarde uit niet-vertrouwde invoer voordat u die in een document plaatst dat u distribueert. Een vooraf ingevuld formulier biedt geen beveiliging: iedereen die de PDF kan openen, kan de waarden lezen en wijzigen. Wanneer de formulierinhoud gevoelig is, combineert u dit recipe met Versleutelen met machtigingen, en houdt u daarbij rekening met het voorbehoud dat de lezer moet meewerken.

Conformiteit

Bewering	Specificatie	Clausule
De huidige waarde van het veld wordt opgeslagen in het item `V` van de velddictionary.	ISO 32000-2	§12.7
De standaardwaarde wordt opgeslagen in het item `DV` en wordt hersteld bij het resetten van het formulier.	ISO 32000-2	§12.7
Voor de tekstopmaak van velden wordt de standaard-appearance-string `DA` gebruikt.	ISO 32000-2	§12.7

NextPDF genereert de AcroForm-structuur die in de geciteerde clausules wordt beschreven. Het maakt geen aanspraak op volledige ISO 32000-2-conformiteit.