Pro édition

Formulaires — Référence détaillée

En bref

Cette page est la référence détaillée du module Form de Pro. Elle couvre l’extraction des valeurs AcroForm, la lecture et l’écriture XFDF, la liaison de données et l’extraction des données XFA. Le module consomme les valeurs NextPDF\Form\FormField produites par le lecteur de formulaires de Core et leur ajoute la sérialisation, l’analyse et la liaison. La prise en charge de XFA est orientée données : l’analyseur structure les paquets template et datasets. Il n’exécute pas les scripts de calcul XFA et ne restitue pas les mises en page XFA dynamiques.

Disponibilité et licence

Cette fonctionnalité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la fonctionnalité. Compare les éditions et obtiens une licence.

Il n’existe aucun indicateur de licence par fonctionnalité. Il s’agit d’une fonctionnalité de l’édition Pro.

Surface d’API publique

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
`FormDataExtractor::extract`	`list<FormField> $fields`	Lit le nom et la valeur de chaque champ	`XfdfData`	—	Inclut les champs dont la valeur est vide.
`FormDataExtractor::toArray`	`list<FormField> $fields`	Construit une table de correspondance nom-valeur de chaînes	`array<string, string>`	—	Un nom en double ultérieur écrase le précédent.
`FormDataExtractor::toXfdf`	`list<FormField> $fields`, `?string $pdfHref = null`	Délègue à `XfdfWriter::fromFields`	`string` (XML XFDF)	—	Chemin de commodité pour un export en un seul appel.
`FormDataExtractor::extractNonEmpty`	`list<FormField> $fields`	Ignore les champs dont la valeur est la chaîne vide	`XfdfData`	—	—
`FormDataExtractor::getEmptyFieldNames`	`list<FormField> $fields`	Liste les noms des champs sans valeur définie	`list<string>`	—	Complément de `extractNonEmpty`.
`XfdfWriter::fromFields`	`list<FormField> $fields`, `?string $pdfHref = null`	Collecte les paires nom-valeur, délègue à `fromArray`	`string` (XML XFDF)	—	—
`XfdfWriter::fromArray`	`array<string, string> $data`, `?string $pdfHref = null`	Encapsule la table dans `XfdfData`, délègue	`string` (XML XFDF)	—	—
`XfdfWriter::fromXfdfData`	`XfdfData $data`, `?string $pdfHref = null`	Sérialise en XFDF ; les noms en notation pointée s’imbriquent en éléments `<field>` hiérarchiques	`string` (XML XFDF)	—	Supprime les caractères de contrôle interdits par XML 1.0 ; voir le contrat de comportement.
`XfdfParser::parse`	`string $xfdfXml`	Charge le XML de façon sûre contre les XXE et aplatit les champs en notation pointée	`XfdfData`	`InvalidArgumentException`	Plafond d’entrée de 10 MiB ; accepte les racines avec ou sans espace de noms.
`XfdfParser::parseFile`	`string $filePath`	Résout le chemin, lit le fichier, délègue à `parse`	`XfdfData`	`InvalidArgumentException`	Les chemins manquants, non-fichiers ou illisibles lèvent une exception.
`XfaParser::parse`	`string $pdfData`	Vérification du marqueur, extraction du XML, analyse des paquets	`XfaFormData`	`InvalidArgumentException`, `XfaParseException`	L’absence du marqueur `/XFA` renvoie un résultat vide, pas une erreur.
`XfaParser::hasXfa`	`string $pdfData`	Parcourt les octets à la recherche du marqueur `/XFA`	`bool`	—	Balayage de marqueur d’octets ; toute occurrence du jeton correspond.
`XfaParser::extractXfaXml`	`string $pdfData`	Balayage des flux à la recherche de marqueurs XFA, puis recherche directe de `<xdp:xdp>`	`string` (XML XFA ou `''`)	`RuntimeException` (déclarée)	Balaie au plus les 50 premiers MiB de l’entrée.
`XfaParser::parseXml`	`string $xml`	Extrait les paquets template et datasets, analyse les éléments `<field>`	`XfaFormData`	`XfaParseException`	Plafond XML de 10 MiB, appliqué avant le chargement du DOM.
`FormDataBinder::bind`	`list<FormField> $fields`, `XfdfData $data`	Crée de nouvelles instances `FormField` avec les valeurs liées	`FormDataBindResult`	—	Les originaux ne sont jamais modifiés ; les cases à cocher se normalisent en `Yes`/`Off`.
`FormDataBinder::fromXfdf`	`list<FormField> $fields`, `string $xfdfXml`	Analyse le XFDF, puis lie	`FormDataBindResult`	`InvalidArgumentException`	Les modes d’échec sont ceux de `XfdfParser::parse`.
`FormDataBinder::fromArray`	`list<FormField> $fields`, `array<string, string> $data`	Encapsule la table dans `XfdfData`, puis lie	`FormDataBindResult`	—	—
`FormDataBindResult`	`isFullyBound`, `hasNoUnmatchedKeys`, `boundCount`, `fieldCount`; readonly `fields`, `boundFieldNames`, `unmatchedDataKeys`, `unboundFieldNames`	Diagnostics de liaison immuables	selon la méthode	—	`isFullyBound` exige zéro clé non appariée et zéro champ non lié.
`XfdfData`	`hasField`, `getValue`, `count`, `isEmpty`, `getFieldNames`, `withField`, `withoutField`, `merge`; readonly `fields`	Conteneur nom-valeur immuable	selon la méthode	—	`with*` et `merge` renvoient de nouvelles instances ; `merge` privilégie les valeurs de l’argument.
`XfaFormData`	`getField`, `hasField`, `count`, `fieldNames`; readonly `fields`, `templateXml`, `datasetsXml`	Résultat d’analyse XFA immuable	selon la méthode	—	Transporte le XML brut des paquets template et datasets pour l’aller-retour.
`XfaFormField`	readonly `name`, `type`, `value`, `required`, `caption`, `options`	Enregistrement immuable d’un seul champ	—	—	`type` vaut l’un de `text`, `numeric`, `date`, `choice`, `button`, `signature`.
`XfaPacket`	cas d’énumération `Template`, `Datasets`, `Config`, `LocaleSet`, `ConnectionSet`, `Form`; `xmlNamespace()`	Énumération de paquets adossée à des chaînes	`string` de `xmlNamespace()`	—	Les URI d’espace de noms suivent 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

Exceptions

NextPDF\Pro\Form\Exception\XfaParseException étend RuntimeException — la charge utile XFA ne peut pas être analysée en un XfaFormData. Le sous-classement est délibéré : les sites d’appel catch (RuntimeException $e) existants continuent de fonctionner.
SPL InvalidArgumentException — entrée vide, surdimensionnée, malformée ou non-XFDF vers XfdfParser ; entrée PDF vide vers XfaParser::parse ; chemins illisibles dans XfdfParser::parseFile.

Contrat de comportement

Extraction AcroForm. FormDataExtractor parcourt la liste de champs que tu lui passes et lit le nom et la valeur de chaque champ. extract renvoie un XfdfData ; toArray renvoie une simple table de correspondance nom-valeur de chaînes. extractNonEmpty écarte les champs dont la valeur est la chaîne vide ; getEmptyFieldNames renvoie la liste de noms complémentaire. L’extraction ne modifie jamais les champs d’entrée.

Écriture XFDF. XfdfWriter produit un document conforme à la structure ISO 19444-1:2019. La sortie commence par la déclaration XML XFDF et une racine xfdf dans l’espace de noms Adobe XFDF (http://ns.adobe.com/xfdf/) avec xml:space="preserve". Un pdfHref non nul émet une référence <f href="..."/> vers le PDF source. Les noms de champ en notation pointée (par exemple address.city) s’imbriquent dans une arborescence hiérarchique d’éléments <field>. Les valeurs et les attributs échappent les cinq métacaractères XML. Les noms de champ, les valeurs et le pdfHref sont en outre normalisés pour garantir la bonne formation : les caractères de contrôle C0 que XML 1.0 interdit sont supprimés, tandis que TAB, LF et CR sont préservés. Cette normalisation est à perte par conception, de sorte que l’écrivain émet toujours du XFDF bien formé et ré-analysable, quels que soient les octets fournis par l’appelant.

Lecture XFDF. XfdfParser accepte les racines xfdf avec ou sans espace de noms et compare le nom de la racine sans tenir compte de la casse, car certains producteurs émettent un élément racine en majuscules. Les arborescences hiérarchiques <field> s’aplatissent de nouveau en noms en notation pointée, de sorte que l’écriture et la lecture forment un aller-retour. Tout chargement de XML désactive l’accès réseau et la résolution d’entités externes. parseFile ajoute la résolution du chemin et des vérifications de lisibilité en amont de la même analyse.

Liaison de données. FormDataBinder::bind apparie les clés de données aux noms de champ. Comme FormField est immuable, la liaison crée de nouvelles instances avec des valeurs mises à jour ; les originaux ne sont jamais modifiés. Le résultat rapporte trois ensembles de diagnostics : les noms des champs liés, les clés de données sans champ correspondant et les champs n’ayant reçu aucune donnée. Les valeurs des cases à cocher se normalisent selon le modèle d’état activé/désactivé d’ISO 32000-2:2020, 12.7.5.2.3 : sans tenir compte de la casse, yes, true, 1 et on correspondent à Yes ; toute autre valeur correspond à Off.

Extraction des données XFA. XfaParser::parse accepte des octets PDF bruts. Il commence par rechercher le marqueur /XFA ; en son absence, il renvoie un XfaFormData vide. L’extraction essaie ensuite deux stratégies : un balayage des blocs stream…endstream à la recherche d’indicateurs de XML XFA, puis une recherche directe d’un document <xdp:xdp>. Un fragment xdp:xdp unique est renvoyé tel quel ; plusieurs fragments sont concaténés dans une enveloppe xdp:xdp synthétisée. parseXml extrait les paquets template et datasets et analyse chaque élément <field> du template en un XfaFormField : l’attribut name est requis, le type dérive de l’élément enfant UI du champ, l’indicateur required dérive d’un élément validate dont nullTest vaut error, et les options de choix proviennent des enfants items.

La prise en charge de XFA est orientée données. L’analyseur structure les paquets template et datasets. Il n’exécute pas les scripts de calcul XFA, ne restitue pas les mises en page XFA dynamiques et ne réalise pas l’aller-retour de tous les types de paquets. Valide l’analyseur sur ton propre ensemble de documents avant de t’y fier.

Cas limites et modes d’échec

XfdfParser::parse('') lève InvalidArgumentException. Une entrée supérieure à 10 MiB lève InvalidArgumentException en nommant le plafond.
Un XML malformé lève InvalidArgumentException porteuse des messages libxml collectés. Un document bien formé dont la racine n’est pas xfdf lève une exception et nomme l’élément racine réel.
Un document XFDF sans élément <fields> s’analyse en un XfdfData vide ; ce n’est pas une erreur.
Les éléments de champ sans attribut name sont ignorés dans l’analyse XFDF comme XFA. Un champ XFDF sans enfant <value> ne contribue aucune entrée.
XfaParser::parse('') lève InvalidArgumentException. Un PDF dépourvu du marqueur /XFA, ou dont le XML XFA est introuvable, renvoie un XfaFormData vide au lieu de lever une exception.
hasXfa est un balayage de marqueur d’octets : tout jeton /XFA dans le fichier correspond, y compris un jeton dans un objet inutilisé. L’étape d’extraction suivante décide s’il existe un XML exploitable.
L’extraction XFA examine au plus les 50 premiers MiB de la chaîne d’octets du PDF ; le contenu au-delà de cette limite n’est pas balayé.
Un XML XFA supérieur à 10 MiB lève XfaParseException avant qu’aucune arborescence DOM ne soit matérialisée. Un XML XFA malformé lève XfaParseException avec les messages libxml.
La normalisation des cases à cocher ne laisse jamais passer de valeurs non reconnues ; tout ce qui sort des formes « activé » acceptées correspond à Off.
La suppression des caractères de contrôle par l’écrivain est à perte : les octets C0 interdits par XML 1.0 dans les noms, les valeurs ou le pdfHref sont supprimés afin que la sortie reste bien formée. TAB, LF et CR survivent.
Toute analyse XML désactive la résolution d’entités externes et l’accès réseau (sûr contre les XXE).
Ce module n’effectue aucune opération cryptographique ; le mode FIPS ne change pas son comportement.

Conformité

Comportement	Référence	Statut
Modèle de formulaire interactif / dictionnaire de champ	ISO 32000-2:2020, 12.7	Aligné (fondé sur le produit)
Normalisation de l’état activé/désactivé des cases à cocher (`Yes`/`Off`)	ISO 32000-2:2020, 12.7.5.2.3	Aligné ; clause citée dans le registre de citations de cette page
Structure d’échange de données XFDF	ISO 19444-1:2019	Aligné (fondé sur le produit)
Noms de paquets XFA et URI d’espace de noms	XFA Specification 3.3	Aligné (fondé sur le produit)

Le corpus RAG disponible au moment de la rédaction n’inclut pas ISO 19444-1:2019, la XFA Specification ni W3C XML 1.0, de sorte que ces déclarations d’alignement sont fondées sur le produit à partir des annotations de source et des tests plutôt que citées par clause. Ces déclarations décrivent la capacité au regard des documents référencés. NextPDF ne détient aucune certification de conformité, et la prise en charge d’une clause n’est pas une revendication de certification.

Notes de développement

Chaque point d’entrée sauf XfaParser est statique. XfaParser est instanciable et sans état ; une même instance peut être réutilisée sans risque sur plusieurs documents.
L’aller-retour prévu est le suivant : le lecteur de formulaires de Core produit des valeurs FormField ; FormDataExtractor ou XfdfWriter les sérialise ; XfdfParser relit les données ; FormDataBinder les applique à une liste de champs. Les noms hiérarchiques survivent à l’aller-retour grâce à la notation pointée.
Utilise les diagnostics FormDataBindResult (isFullyBound, unmatchedDataKeys, unboundFieldNames) pour détecter un écart entre un fichier de données XFDF et un modèle PDF révisé avant d’accepter un remplissage.
XfdfData est un objet-valeur : withField, withoutField et merge renvoient de nouvelles instances. En cas de collision de clés, merge privilégie les valeurs de l’argument.
XfaFormData conserve le XML brut des paquets template et datasets (templateXml, datasetsXml) afin que tu puisses post-traiter les paquets que le modèle de champ ne couvre pas.
Ce module n’analyse pas lui-même les dictionnaires AcroForm à partir des octets PDF ; il consomme les champs produits par le lecteur de formulaires de Core. Seul XfaParser opère sur du contenu PDF brut.

Limite de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.