Form

In sintesi

NextPDF Pro legge e scrive i dati dei moduli interattivi: valori dei campi AcroForm, file di dati XFDF e i dati portati dai template XFA (XML Forms Architecture). Completa il reader di moduli open source del Core con il binding dei dati, l’estrazione e la serializzazione.

Disponibilità e licenze

Questa capacità viene distribuita in NextPDF Pro (nextpdf/pro) e si attiva con un license envelope di livello Pro. Un deployment privo di tale entitlement non carica le classi della capacità. Confrontare le edizioni e ottenere una licenza.

Form fa parte dell’edizione Pro. Non esiste un flag di licenza separato per singola funzionalità.

Installazione

composer require nextpdf/pro:^3

La capacità Form richiede una licenza NextPDF Pro valida. Vedere Disponibilità e licenze.

Panoramica concettuale

Un modulo interattivo PDF — talvolta chiamato AcroForm — memorizza ciascun campo in un dizionario di campo, come definito in ISO 32000-2 §12.7. NextPDF Pro si basa sul reader di moduli del Core per aggiungere tre capacità:

• Round-trip degli AcroForm. FormDataExtractor legge le coppie nome/valore dei campi dai campi di modulo analizzati e produce un oggetto XfdfData o una semplice mappa name → value. XfdfWriter esegue l’inverso, generando un documento XFDF.
• Lettura e scrittura XFDF. XFDF è il formato XML di scambio dei dati per i valori dei moduli descritto da ISO 19444-1:2019. XfdfParser legge un file XFDF in dati strutturati; XfdfWriter serializza i valori dei campi in XFDF, con un riferimento opzionale al PDF di origine.
• Estrazione dei dati XFA. XfaParser individua i pacchetti XFA in un documento, concatena i frammenti XML e analizza i pacchetti template e datasets in dati di campo strutturati.

Ambito del supporto XFA

Il supporto XFA in NextPDF Pro è orientato ai dati, non è un motore completo di rendering o scripting XFA. Il parser estrae e struttura i pacchetti template e datasets, così da poter leggere definizioni e valori dei campi. Non esegue gli script di calcolo dei moduli XFA, non disegna i layout XFA dinamici e non esegue il round-trip di ogni tipo di pacchetto XFA. Testare il parser sui propri documenti specifici prima di affidarvisi per un determinato insieme di moduli XFA. Tutte le analisi XML disabilitano il caricamento delle entità esterne (XXE-safe).

Perché funziona così

Il supporto XFA è deliberatamente limitato ai dati, non al rendering. ISO 32000-2 contrassegna come deprecata in PDF 2.0 la voce XFA del dizionario di modulo (§12.7). Un motore completo di layout e scripting XFA inseguirebbe una superficie legacy di cui la maggior parte dei carichi di lavoro non ha più bisogno. NextPDF Pro estrae invece i pacchetti template e datasets, dove risiedono i dati di campo durevoli, e rinuncia al resto. La stessa impostazione guida l’analisi con XXE disattivato e il limite di scansione, perché l’input dei moduli arriva spesso da parti non attendibili. Ciò mantiene la superficie Form di Pro un’estensione sottile e prevedibile del modello AcroForm del Core.

Contesto di progettazione: Dal modulo compilabile al record congelato: compilazione e appiattimento degli AcroForm.

Superficie API

Class	Responsibility
FormDataExtractor	Estrarre i valori dei campi AcroForm come XfdfData o array.
XfdfParser	Analizzare un documento XFDF in dati strutturati.
XfdfWriter	Serializzare i valori dei campi in XFDF, riferimento PDF opzionale.
XfaParser	Estrarre e analizzare i pacchetti template e datasets XFA.
FormDataBinder	Associare una mappa di dati ai campi di modulo.

Il riferimento completo a livello di metodi è nel riferimento approfondito di Form.

Esempio di codice — Avvio rapido

use NextPDF\Pro\Form\FormDataExtractor;
use NextPDF\Pro\Form\XfdfWriter;

$values = FormDataExtractor::toArray($fields);
$xfdf   = XfdfWriter::fromFields($fields, 'invoice.pdf');

Esempio di codice — Produzione

use NextPDF\Pro\Form\XfaParser;
use NextPDF\Pro\Form\Exception\XfaParseException;

try {
    $formData = (new XfaParser())->parse($pdfBytes);
    $logger->info('xfa.parsed', ['fields' => count($formData->fields)]);
} catch (XfaParseException $e) {
    $logger->warning('xfa.parse_failed', ['reason' => $e->getMessage()]);
}

Casi limite e insidie

• XfaParser rifiuta input PDF più grande del suo limite di scansione anziché leggere dati non delimitati.
• Un documento può portare sia moduli interattivi sia non interattivi; l’estrazione punta ai dizionari di campo terminali.
• XFDF esegue il round-trip di strutture di campo piatte; le gerarchie di campi profondamente annidate potrebbero richiedere una gestione esplicita.

Prestazioni

L’estrazione e la serializzazione sono lineari rispetto al numero di campi di modulo. Il costo dell’analisi XFA scala con la dimensione dei pacchetti XML incorporati.

Note sulla sicurezza

Tutte le analisi XML disabilitano la risoluzione delle entità esterne per prevenire l’XXE. Trattare come ostile l’input XFDF e XFA proveniente da fonti non attendibili e convalidare l’insieme dei campi analizzati prima di associarlo nuovamente a un documento.

Conformità

Behavior	Reference	Status
Interactive form / field dictionary model	ISO 32000-2 §12.7	Aligned (paraphrased)
XFDF data-exchange format	ISO 19444-1:2019	Aligned

Questa tabella registra le specifiche rispetto alle quali NextPDF Pro è costruito. Non costituisce una dichiarazione di certificazione formale.

Contratto di comportamento

• FormDataExtractor legge le coppie nome/valore dai dizionari di campo terminali analizzati e restituisce un oggetto XfdfData o un semplice array name → value.
• XfdfParser analizza un documento XFDF in dati strutturati; XfdfWriter serializza i valori dei campi in XFDF con un riferimento opzionale al PDF di origine.
• XfaParser individua i pacchetti XFA, concatena i frammenti XML e analizza i pacchetti template e datasets in dati di campo strutturati. Rifiuta input PDF più grande del suo limite di scansione anziché leggere dati non delimitati.
• Il supporto XFA è orientato ai dati: il parser estrae e struttura i pacchetti template e datasets. Non esegue gli script di calcolo dei moduli XFA, non disegna i layout XFA dinamici e non esegue il round-trip di ogni tipo di pacchetto XFA.
• Tutte le analisi XML disabilitano la risoluzione delle entità esterne (XXE-safe).

Nota sul confine Enterprise

Enterprise non modifica il comportamento di Form. Enterprise aggiunge funzionalità di fascia superiore di compliance e archiviazione documentate separatamente; non sono richieste per il round-trip degli AcroForm, la lettura/scrittura XFDF o l’estrazione dei dati XFA.

Core fallback / alternativa

Il reader di moduli open source di NextPDF Core legge i campi di modulo. La lettura/scrittura XFDF, l’estrazione dei dati XFA e il binding dei campi sono aggiunte di Pro. Vedere /modules/form/.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Interop — DTO versionati di dati di modulo per sistemi esterni.
• Core Form module — reader di moduli open source.
• Form — Deep Reference — riferimento a livello di metodi per le classi Form di Pro.