Form — Riferimento approfondito

In breve

Questa pagina è il riferimento approfondito del modulo Form di Pro. Copre l’estrazione dei valori AcroForm, la lettura e la scrittura XFDF, il data binding e l’estrazione dei dati XFA. Il modulo consuma i valori NextPDF\Form\FormField prodotti dal form reader di Core e vi aggiunge serializzazione, parsing e binding. Il supporto XFA è orientato ai dati: il parser struttura i pacchetti template e datasets. Non esegue gli script di calcolo XFA né effettua il rendering dei layout XFA dinamici.

Disponibilità e licenza

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

Non esiste alcun flag di licenza per singola funzionalità. È una funzionalità dell’edizione Pro.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
FormDataExtractor::extract	list<FormField> $fields	Legge il nome e il valore di ciascun campo	XfdfData	—	Include i campi il cui valore è vuoto.
FormDataExtractor::toArray	list<FormField> $fields	Costruisce una mappa di stringhe nome→valore	array<string, string>	—	Un nome duplicato successivo sovrascrive quello precedente.
FormDataExtractor::toXfdf	list<FormField> $fields, ?string $pdfHref = null	Delega a XfdfWriter::fromFields	string (XFDF XML)	—	Percorso di comodo per l’esportazione in una sola chiamata.
FormDataExtractor::extractNonEmpty	list<FormField> $fields	Salta i campi il cui valore è la stringa vuota	XfdfData	—	—
FormDataExtractor::getEmptyFieldNames	list<FormField> $fields	Elenca i nomi dei campi senza valore impostato	list<string>	—	Complemento di extractNonEmpty.
XfdfWriter::fromFields	list<FormField> $fields, ?string $pdfHref = null	Raccoglie le coppie nome→valore, delega a fromArray	string (XFDF XML)	—	—
XfdfWriter::fromArray	array<string, string> $data, ?string $pdfHref = null	Incapsula la mappa in XfdfData, delega	string (XFDF XML)	—	—
XfdfWriter::fromXfdfData	XfdfData $data, ?string $pdfHref = null	Serializza in XFDF; i nomi in notazione a punti si annidano in elementi <field> gerarchici	string (XFDF XML)	—	Rimuove i caratteri di controllo non ammessi da XML 1.0; vedere il contratto di comportamento.
XfdfParser::parse	string $xfdfXml	Carica l’XML in modo sicuro rispetto a XXE e appiattisce i campi in notazione a punti	XfdfData	InvalidArgumentException	Tetto di input di 10 MiB; accetta radici con e senza namespace.
XfdfParser::parseFile	string $filePath	Risolve il percorso, legge il file, delega a parse	XfdfData	InvalidArgumentException	Percorsi mancanti, non-file o illeggibili sollevano un’eccezione.
XfaParser::parse	string $pdfData	Verifica del marker, estrazione XML, parsing dei pacchetti	XfaFormData	InvalidArgumentException, XfaParseException	L’assenza del marker /XFA restituisce un risultato vuoto, non un errore.
XfaParser::hasXfa	string $pdfData	Scandisce i byte alla ricerca del marker /XFA	bool	—	Scansione a marker di byte; corrisponde qualsiasi occorrenza del token.
XfaParser::extractXfaXml	string $pdfData	Scansione degli stream per i marker XFA, poi ricerca diretta di <xdp:xdp>	string (XFA XML o '')	RuntimeException (dichiarata)	Scandisce al più i primi 50 MiB dell’input.
XfaParser::parseXml	string $xml	Estrae i pacchetti template e datasets, analizza gli elementi <field>	XfaFormData	XfaParseException	Tetto XML di 10 MiB, applicato prima del caricamento del DOM.
FormDataBinder::bind	list<FormField> $fields, XfdfData $data	Crea nuove istanze FormField con i valori associati	FormDataBindResult	—	Gli originali non vengono mai modificati; le caselle di controllo si normalizzano in Yes/Off.
FormDataBinder::fromXfdf	list<FormField> $fields, string $xfdfXml	Analizza l’XFDF, poi effettua il binding	FormDataBindResult	InvalidArgumentException	Le modalità di errore sono quelle di XfdfParser::parse.
FormDataBinder::fromArray	list<FormField> $fields, array<string, string> $data	Incapsula la mappa in XfdfData, poi effettua il binding	FormDataBindResult	—	—
FormDataBindResult	isFullyBound, hasNoUnmatchedKeys, boundCount, fieldCount; readonly fields, boundFieldNames, unmatchedDataKeys, unboundFieldNames	Diagnostica di binding immutabile	per metodo	—	isFullyBound richiede zero chiavi non associate e zero campi non associati.
XfdfData	hasField, getValue, count, isEmpty, getFieldNames, withField, withoutField, merge; readonly fields	Contenitore immutabile nome→valore	per metodo	—	with* e merge restituiscono nuove istanze; merge privilegia i valori dell’argomento.
XfaFormData	getField, hasField, count, fieldNames; readonly fields, templateXml, datasetsXml	Risultato immutabile del parsing XFA	per metodo	—	Trasporta l’XML grezzo dei pacchetti template e datasets per il round-trip.
XfaFormField	readonly name, type, value, required, caption, options	Record immutabile di un singolo campo	—	—	type è uno tra text, numeric, date, choice, button, signature.
XfaPacket	casi enum Template, Datasets, Config, LocaleSet, ConnectionSet, Form; xmlNamespace()	Enumerazione di pacchetti basata su stringhe	string da xmlNamespace()	—	Gli URI di namespace seguono la XFA Specification 3.3.

public static function extract(array $fields): XfdfData
public static function toArray(array $fields): array
public static function toXfdf(array $fields, ?string $pdfHref = null): string
public static function extractNonEmpty(array $fields): XfdfData
public static function getEmptyFieldNames(array $fields): array

public static function fromFields(array $fields, ?string $pdfHref = null): string
public static function fromArray(array $data, ?string $pdfHref = null): string
public static function fromXfdfData(XfdfData $data, ?string $pdfHref = null): string

public static function parse(string $xfdfXml): XfdfData
public static function parseFile(string $filePath): XfdfData

public function parse(string $pdfData): XfaFormData
public function hasXfa(string $pdfData): bool
public function extractXfaXml(string $pdfData): string
public function parseXml(string $xml): XfaFormData

public static function bind(array $fields, XfdfData $data): FormDataBindResult
public static function fromXfdf(array $fields, string $xfdfXml): FormDataBindResult
public static function fromArray(array $fields, array $data): FormDataBindResult

Eccezioni

• NextPDF\Pro\Form\Exception\XfaParseException estende RuntimeException — il payload XFA non può essere analizzato in un XfaFormData. La sottoclasse è deliberata: i call site catch (RuntimeException $e) esistenti continuano a funzionare.
• InvalidArgumentException SPL — input vuoto, sovradimensionato, malformato o non-XFDF a XfdfParser; input PDF vuoto a XfaParser::parse; percorsi illeggibili in XfdfParser::parseFile.

Contratto di comportamento

Estrazione AcroForm. FormDataExtractor percorre l’elenco di campi passato e legge il nome e il valore di ciascun campo. extract restituisce un XfdfData; toArray restituisce una semplice mappa di stringhe nome→valore. extractNonEmpty scarta i campi il cui valore è la stringa vuota; getEmptyFieldNames restituisce l’elenco complementare dei nomi. L’estrazione non modifica mai i campi in input.

Scrittura XFDF. XfdfWriter produce un documento conforme alla struttura ISO 19444-1:2019. L’output inizia con la dichiarazione XML XFDF e una radice xfdf nel namespace Adobe XFDF (http://ns.adobe.com/xfdf/) con xml:space="preserve". Un pdfHref non nullo emette un riferimento <f href="..."/> al PDF di origine. I nomi di campo in notazione a punti (per esempio address.city) si annidano in un albero gerarchico di elementi <field>. I valori e gli attributi effettuano l’escape dei cinque metacaratteri XML. I nomi di campo, i valori e il pdfHref vengono inoltre normalizzati per la buona formazione: i caratteri di controllo C0 vietati da XML 1.0 vengono rimossi, mentre TAB, LF e CR vengono preservati. Questa normalizzazione è per progettazione con perdita, così lo writer emette sempre un XFDF ben formato e ri-analizzabile indipendentemente dai byte forniti dal chiamante.

Lettura XFDF. XfdfParser accetta radici xfdf sia con sia senza namespace e confronta il nome della radice senza distinzione tra maiuscole e minuscole, perché alcuni produttori emettono un elemento radice in maiuscolo. Gli alberi gerarchici <field> vengono riappiattiti in nomi in notazione a punti, così scrittura e lettura effettuano il round-trip. Tutto il caricamento XML disabilita l’accesso alla rete e la risoluzione delle entità esterne. parseFile antepone alla stessa analisi la risoluzione del percorso e i controlli di leggibilità.

Data binding. FormDataBinder::bind confronta le chiavi dei dati con i nomi dei campi. Poiché FormField è immutabile, il binding crea nuove istanze con valori aggiornati; gli originali non vengono mai modificati. Il risultato riporta tre insiemi diagnostici: i nomi dei campi associati, le chiavi di dati senza campo corrispondente e i campi che non hanno ricevuto dati. I valori delle caselle di controllo si normalizzano nel modello di stato on/off di ISO 32000-2:2020, 12.7.5.2.3: yes, true, 1 e on (senza distinzione tra maiuscole e minuscole) diventano Yes; ogni altro valore diventa Off.

Estrazione dei dati XFA. XfaParser::parse accetta byte PDF grezzi. Prima cerca il marker /XFA; in assenza del marker restituisce un XfaFormData vuoto. L’estrazione tenta poi due strategie: una scansione dei blocchi stream…endstream alla ricerca di indicatori di XML XFA, poi una ricerca diretta di un documento <xdp:xdp>. Un singolo frammento xdp:xdp viene restituito così com’è; più frammenti vengono concatenati in un envelope xdp:xdp sintetizzato. parseXml estrae i pacchetti template e datasets e analizza ciascun elemento <field> del template in un XfaFormField: l’attributo name è obbligatorio, il tipo deriva dall’elemento figlio UI del campo, il flag required deriva da un elemento validate con nullTest impostato su error e le opzioni di scelta provengono dai figli items.

Il supporto XFA è orientato ai dati. Il parser struttura i pacchetti template e datasets. Non esegue gli script di calcolo XFA, non effettua il rendering dei layout XFA dinamici e non effettua il round-trip di ogni tipo di pacchetto. Convalidare il parser sul proprio specifico insieme di documenti prima di farvi affidamento.

Casi limite e modalità di errore

• XfdfParser::parse('') solleva InvalidArgumentException. Un input superiore a 10 MiB solleva InvalidArgumentException indicando il tetto.
• L’XML malformato solleva InvalidArgumentException che trasporta i messaggi libxml raccolti. Un documento ben formato la cui radice non è xfdf solleva un’eccezione e indica l’elemento radice effettivo.
• Un documento XFDF privo di un elemento <fields> viene analizzato in un XfdfData vuoto; ciò non è un errore.
• Gli elementi di campo privi di un attributo name vengono saltati sia nel parsing XFDF sia in quello XFA. Un campo XFDF privo di un figlio <value> non contribuisce con alcuna voce.
• XfaParser::parse('') solleva InvalidArgumentException. Un PDF privo del marker /XFA, o uno il cui XML XFA non può essere individuato, restituisce un XfaFormData vuoto anziché sollevare un’eccezione.
• hasXfa è una scansione a marker di byte: corrisponde qualsiasi token /XFA nel file, incluso uno in un oggetto inutilizzato. Il successivo passo di estrazione decide se esiste XML utilizzabile.
• L’estrazione XFA esamina al più i primi 50 MiB della stringa di byte del PDF; il contenuto oltre tale limite non viene scansionato.
• Un XML XFA superiore a 10 MiB solleva XfaParseException prima che venga materializzato alcun albero DOM. Un XML XFA malformato solleva XfaParseException con i messaggi libxml.
• La normalizzazione delle caselle di controllo non lascia mai passare valori non riconosciuti; qualsiasi cosa al di fuori delle forme “on” accettate diventa Off.
• La rimozione dei caratteri di controllo da parte dello writer è con perdita: i byte C0 non ammessi da XML 1.0 nei nomi, nei valori o nel pdfHref vengono scartati affinché l’output resti ben formato. TAB, LF e CR sopravvivono.
• Tutto il parsing XML disabilita la risoluzione delle entità esterne e l’accesso alla rete (sicuro rispetto a XXE).
• Questo modulo non esegue alcuna operazione crittografica; la modalità FIPS non ne altera il comportamento.

Conformità

Comportamento	Riferimento	Stato
Modello di modulo interattivo / dizionario di campo	ISO 32000-2:2020, 12.7	Allineato (basato sul prodotto)
Normalizzazione dello stato on/off delle caselle di controllo (Yes/Off)	ISO 32000-2:2020, 12.7.5.2.3	Allineato; clausola citata nel record di citazioni di questa pagina
Struttura di scambio dati XFDF	ISO 19444-1:2019	Allineato (basato sul prodotto)
Nomi dei pacchetti XFA e URI di namespace	XFA Specification 3.3	Allineato (basato sul prodotto)

Il corpus RAG disponibile al momento della stesura non include ISO 19444-1:2019, la XFA Specification o W3C XML 1.0, perciò tali dichiarazioni di allineamento sono basate sul prodotto a partire dalle annotazioni del sorgente e dai test anziché essere citate per clausola. Queste dichiarazioni descrivono la capacità rispetto ai documenti citati. NextPDF non detiene alcuna certificazione di conformità e il supporto di una clausola non costituisce una dichiarazione di certificazione.

Note di sviluppo

• Ogni entry point tranne XfaParser è statico. XfaParser è istanziabile e senza stato; una singola istanza può essere riutilizzata in sicurezza su più documenti.
• Il round-trip previsto è: il form reader di Core produce i valori FormField; FormDataExtractor o XfdfWriter li serializza; XfdfParser rilegge i dati; FormDataBinder li applica a un elenco di campi. I nomi gerarchici sopravvivono al round-trip tramite la notazione a punti.
• Usare la diagnostica di FormDataBindResult (isFullyBound, unmatchedDataKeys, unboundFieldNames) per rilevare la divergenza tra un file di dati XFDF e un template PDF revisionato prima di accettare una compilazione.
• XfdfData è un value object: withField, withoutField e merge restituiscono nuove istanze. In caso di collisioni di chiavi, merge privilegia i valori dell’argomento.
• XfaFormData conserva l’XML grezzo dei pacchetti template e datasets (templateXml, datasetsXml) così da poter post-elaborare i pacchetti che il modello di campo non copre.
• Questo modulo non analizza da sé i dizionari AcroForm a partire dai byte del PDF; consuma i campi prodotti dal form reader di Core. Solo XfaParser opera sul contenuto PDF grezzo.

Confine di pubblicazione

Questa pagina documenta soltanto 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

• Form — panoramica della funzionalità
• Interop — Riferimento approfondito
• Modulo Core Form