Form: campi AcroForm interattivi e appiattimento

In sintesi

Il modulo Form costruisce moduli PDF interattivi. Crea campi di testo, caselle di controllo, pulsanti di scelta, campi di selezione (elenco/combinata), pulsanti e campi di firma. Li organizza in una gerarchia parent/child. Li scrive come oggetti PDF con flussi di aspetto. Può appiattire il modulo trasformandolo in contenuto di pagina statico.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Un modulo PDF interattivo è l’AcroForm: una gerarchia di campi a livello di documento i cui campi terminali sono associati alle annotazioni widget sulle pagine. La ISO 32000-2 §12.7 definisce questo modulo e i relativi dizionari di campo, incluse la radice AcroForm e la gerarchia dei campi. Nel motore, questo modulo ne fornisce l’encoder.

FormFieldManager è la superficie principale. Espone i builder textField(), checkBox(), radioButton(), button() e signatureField(), tiene traccia dei campi e li serializza con writeFields(). Emette un flusso di aspetto Form XObject per ogni widget (/Subtype /Form, /BBox), come richiede la §8.10. FormField è l’oggetto valore del campo. FormFieldDictionaryBuilder trasforma un campo nel relativo dizionario PDF e applica le voci e i bit di flag specifici del tipo (testo, casella di controllo, selezione, pulsante). Il manager e FormField sono @since 1.0.0. Il builder del dizionario è @since 1.1.0.

FormFieldHierarchy modella l’albero parent/child dei campi: addChild(), getRootFieldNames(), getChildren(), getParent() e un visitatore walkDepthFirst(). Un nome di campo completo è il percorso con punti attraverso questa gerarchia, cioè il modello che la §12.7 specifica per i campi annidati.

FormFlattener rende il modulo come contenuto di pagina statico — flatten() restituisce un FlattenResult — così un modulo compilato può essere congelato per l’archiviazione. FieldMDP e FieldMdpAction modellano la trasformazione di blocco dei campi. Un documento firmato può bloccare un insieme di campi denominati rispetto a ulteriori modifiche. FieldMdpAction enumera l’ambito del blocco. Il suo requiresFieldList() indica quando è obbligatorio un elenco esplicito di campi. FieldMDP è @since 2.0.0.

Superficie API

Classe	Membri principali	Ruolo
FormFieldManager	textField(), checkBox(), radioButton(), button(), signatureField(), addChildField(), getHierarchy(), writeFields()	Builder dei campi e serializzatore (@since 1.0.0)
FormField	oggetto valore del campo	Un campo AcroForm (@since 1.0.0)
FormFieldDictionaryBuilder	buildFieldDictionary(), applyTextFieldOptions(), applyCheckBoxOptions(), applyChoiceFieldOptions(), applyButtonOptions()	Builder da campo a dizionario (@since 1.1.0)
FormFieldHierarchy	addChild(), getRootFieldNames(), getChildren(), getParent(), walkDepthFirst()	Albero parent/child dei campi (@since 2.0.0)
FormFlattener	flatten(array $fields, array $pages): FlattenResult	Appiattisce il modulo in contenuto statico (@since 1.0.0)
FieldMDP	toTransformParams()	Trasformazione di blocco dei campi (FieldMDP) (@since 2.0.0)
FieldMdpAction (enum)	requiresFieldList()	Ambito del blocco dei campi (@since 2.0.0)

Eseguire composer docs:generate-api-php -- --module=Form per ottenere la tabella PHPDoc completa.

Esempio di codice — Avvio rapido

Origine: 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.

Esempio di codice — Produzione

Costruire un insieme di campi per un documento firmato e bloccare i campi firmati 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.

Casi limite e insidie

• Un nome di campo è un percorso completo con punti attraverso FormFieldHierarchy. Due campi terminali con lo stesso nome completo sono lo stesso campo logico per un visualizzatore — l’unicità è responsabilità del chiamante.
• FieldMdpAction::requiresFieldList() indica quando è obbligatorio un elenco di campi. Un’azione Include/Exclude senza l’elenco richiesto è un blocco malformato; controllare il flag.
• FormFlattener::flatten() è intenzionalmente distruttivo per l’interattività — il risultato è contenuto statico. Conservare la sorgente interattiva se servirà in seguito.
• I flussi di aspetto sono emessi per ogni widget. Un campo senza aspetto viene reso in modo non uniforme dai vari visualizzatori; lasciare che il manager generi l’aspetto invece di ometterlo.
• signatureField() crea soltanto il segnaposto del campo. Produrre la firma effettiva è compito del livello Security/firma, non di questo modulo.

Prestazioni

La creazione e la serializzazione dei campi hanno complessità O(n) rispetto al numero di campi, più un flusso di aspetto Form XObject per ogni widget. Il costo dell’appiattimento cresce con il contenuto reso, non con il numero di campi. Il carico di lavoro di riferimento predefinito rientra nel budget di 1500 ms / 64 MB di picco. Il profilo di riproducibilità è structural: i numeri degli oggetti e l’/ID del trailer variano tra le esecuzioni. Due documenti con lo stesso modulo sono strutturalmente uguali ma non identici a livello di byte.

Note di sicurezza

I valori dei campi del modulo sono input dell’utente. Il modulo esegue l’escape dei valori stringa per la serializzazione PDF (PdfStringEscaper), in modo che il valore di un campo non possa uscire dalla propria stringa PDF e iniettare struttura. Quando un modulo è cifrato, il contenuto dei campi è coperto dalla cifratura AES-256 del documento. FieldMDP è un controllo di sicurezza: blocca i campi denominati rispetto alle modifiche successive alla firma. Un blocco dei campi che non corrisponde all’insieme dei campi firmati compromette tale controllo — impostare l’ambito del blocco in modo deliberato. Trattare qualsiasi valore estratto da un modulo compilato come input non attendibile. Vedere il modello di sicurezza del motore in /modules/core/security/.

Conformità

Le strutture dei moduli emesse da questo modulo seguono il modello di modulo interattivo della ISO 32000-2 §12.7 — la radice AcroForm, i dizionari di campo e la gerarchia dei campi del documento. Gli aspetti per ogni widget sono emessi come Form XObject secondo la §8.10 e documentati inline in src/Form/. Sono fatti implementativi verificati da tests/Unit/Form/. Non costituiscono una dichiarazione di conformità PDF 2.0 end-to-end. La conformità dell’intero documento è validata dalle suite oracle e golden in /modules/core/conformance/.

Vedere anche

• Modulo Navigation — le annotazioni widget a cui sono associati i campi.
• Modulo Security — la firma e il modello di fiducia FieldMDP.
• Modulo Accessibility — l’assegnazione dei tag ai campi del modulo per PDF/UA.
• Panoramica sulla conformità.