Pro editie

Form — Diepe referentie

In een oogopslag

Deze pagina is de diepe referentie voor de Pro Form-module. Ze behandelt AcroForm-waarde-extractie, XFDF lezen en schrijven, gegevensbinding en XFA-gegevensextractie. De module consumeert NextPDF\Form\FormField-waarden die door de Core form reader worden geproduceerd en voegt daar serialisatie, parsing en binding aan toe. XFA-ondersteuning is gegevensgericht: de parser structureert de template- en datasets-pakketten. Ze voert geen XFA-berekeningsscripts uit en rendert geen dynamische XFA-lay-outs.

Beschikbaarheid en licenties

Deze functionaliteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een Pro-tier license envelope. Een deployment zonder die entitlement laadt de klassen van de functionaliteit niet. Vergelijk edities en vraag een licentie aan.

Er bestaat geen license-flag per functie. Dit is een functionaliteit van de Pro-editie.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`FormDataExtractor::extract`	`list<FormField> $fields`	Leest de naam en waarde van elk veld	`XfdfData`	—	Bevat velden met een lege waarde.
`FormDataExtractor::toArray`	`list<FormField> $fields`	Bouwt een name-to-value stringmap	`array<string, string>`	—	Een latere dubbele naam overschrijft een eerdere.
`FormDataExtractor::toXfdf`	`list<FormField> $fields`, `?string $pdfHref = null`	Delegeert naar `XfdfWriter::fromFields`	`string` (XFDF XML)	—	Handige route voor export in één aanroep.
`FormDataExtractor::extractNonEmpty`	`list<FormField> $fields`	Slaat velden over waarvan de waarde de lege string is	`XfdfData`	—	—
`FormDataExtractor::getEmptyFieldNames`	`list<FormField> $fields`	Somt de namen op van velden zonder ingestelde waarde	`list<string>`	—	Complement van `extractNonEmpty`.
`XfdfWriter::fromFields`	`list<FormField> $fields`, `?string $pdfHref = null`	Verzamelt name-to-value-paren, delegeert naar `fromArray`	`string` (XFDF XML)	—	—
`XfdfWriter::fromArray`	`array<string, string> $data`, `?string $pdfHref = null`	Wikkelt de map in `XfdfData`, delegeert	`string` (XFDF XML)	—	—
`XfdfWriter::fromXfdfData`	`XfdfData $data`, `?string $pdfHref = null`	Serialiseert naar XFDF; dot-notatie-namen nesten als hiërarchische `<field>`-elementen	`string` (XFDF XML)	—	Verwijdert XML-1.0-ongeldige control-tekens; zie het gedragscontract.
`XfdfParser::parse`	`string $xfdfXml`	Laadt de XML XXE-veilig en vlakt velden af tot dot-notatie	`XfdfData`	`InvalidArgumentException`	Invoerplafond van 10 MiB; accepteert namespaced en niet-namespaced roots.
`XfdfParser::parseFile`	`string $filePath`	Resolvet het pad, leest het bestand, delegeert naar `parse`	`XfdfData`	`InvalidArgumentException`	Ontbrekende, niet-bestand- of onleesbare paden genereren een exception.
`XfaParser::parse`	`string $pdfData`	Markercontrole, XML-extractie, pakketparsing	`XfaFormData`	`InvalidArgumentException`, `XfaParseException`	Geen `/XFA`-marker retourneert een leeg resultaat, geen fout.
`XfaParser::hasXfa`	`string $pdfData`	Scant de bytes op de `/XFA`-marker	`bool`	—	Byte-marker-scan; elk voorkomen van de token matcht.
`XfaParser::extractXfaXml`	`string $pdfData`	Streamscan op XFA-markers, daarna directe zoektocht naar `<xdp:xdp>`	`string` (XFA XML of `''`)	`RuntimeException` (gedeclareerd)	Scant hooguit de eerste 50 MiB van de invoer.
`XfaParser::parseXml`	`string $xml`	Extraheert de template- en datasets-pakketten, parse’t `<field>`-elementen	`XfaFormData`	`XfaParseException`	XML-plafond van 10 MiB, afgedwongen vóór het laden van de DOM.
`FormDataBinder::bind`	`list<FormField> $fields`, `XfdfData $data`	Maakt nieuwe `FormField`-instanties met gebonden waarden	`FormDataBindResult`	—	Originelen worden nooit gewijzigd; checkboxes normaliseren naar `Yes`/`Off`.
`FormDataBinder::fromXfdf`	`list<FormField> $fields`, `string $xfdfXml`	Parse’t de XFDF, bindt vervolgens	`FormDataBindResult`	`InvalidArgumentException`	Faalmodi zijn die van `XfdfParser::parse`.
`FormDataBinder::fromArray`	`list<FormField> $fields`, `array<string, string> $data`	Wikkelt de map in `XfdfData`, bindt vervolgens	`FormDataBindResult`	—	—
`FormDataBindResult`	`isFullyBound`, `hasNoUnmatchedKeys`, `boundCount`, `fieldCount`; readonly `fields`, `boundFieldNames`, `unmatchedDataKeys`, `unboundFieldNames`	Onveranderlijke bind-diagnostiek	per methode	—	`isFullyBound` vereist nul niet-gematchte keys en nul ongebonden velden.
`XfdfData`	`hasField`, `getValue`, `count`, `isEmpty`, `getFieldNames`, `withField`, `withoutField`, `merge`; readonly `fields`	Onveranderlijke name-to-value-container	per methode	—	`with*` en `merge` retourneren nieuwe instanties; `merge` verkiest de waarden van het argument.
`XfaFormData`	`getField`, `hasField`, `count`, `fieldNames`; readonly `fields`, `templateXml`, `datasetsXml`	Onveranderlijk XFA-parseresultaat	per methode	—	Draagt ruwe template- en datasets-pakket-XML voor round-tripping.
`XfaFormField`	readonly `name`, `type`, `value`, `required`, `caption`, `options`	Onveranderlijk record van één veld	—	—	`type` is een van `text`, `numeric`, `date`, `choice`, `button`, `signature`.
`XfaPacket`	enum-cases `Template`, `Datasets`, `Config`, `LocaleSet`, `ConnectionSet`, `Form`; `xmlNamespace()`	String-backed pakket-enumeratie	`string` uit `xmlNamespace()`	—	Namespace-URI’s volgen de 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

Uitzonderingen

NextPDF\Pro\Form\Exception\XfaParseException breidt RuntimeException uit — de XFA-payload kan niet tot een XfaFormData worden geparset. De subclassing is bewust: bestaande catch (RuntimeException $e)-call sites blijven werken.
SPL InvalidArgumentException — lege, te grote, misvormde of niet-XFDF-invoer voor XfdfParser; lege PDF-invoer voor XfaParser::parse; onleesbare paden in XfdfParser::parseFile.

Gedragscontract

AcroForm-extractie. FormDataExtractor doorloopt de veldlijst die je doorgeeft en leest de naam en waarde van elk veld. extract retourneert een XfdfData; toArray retourneert een gewone name-to-value stringmap. extractNonEmpty laat velden vallen waarvan de waarde de lege string is; getEmptyFieldNames retourneert de complementaire namenlijst. Extractie muteert de invoervelden nooit.

XFDF-schrijven. XfdfWriter produceert een document dat voldoet aan de structuur van ISO 19444-1:2019. De uitvoer begint met de XFDF-XML-declaratie en een xfdf-root in de Adobe XFDF-namespace (http://ns.adobe.com/xfdf/) met xml:space="preserve". Een niet-null pdfHref genereert een <f href="..."/>-referentie terug naar de bron-PDF. Dot-notatie-veldnamen (bijvoorbeeld address.city) nesten in een hiërarchische <field>-elementenboom. Waarden en attributen escapen de vijf XML-metatekens. Veldnamen, waarden en de pdfHref worden bovendien genormaliseerd voor welgevormdheid: de C0-control-tekens die XML 1.0 verbiedt worden verwijderd, terwijl TAB, LF en CR behouden blijven. Deze normalisatie is bewust lossy, dus de writer produceert altijd welgevormde, opnieuw parsebare XFDF, ongeacht de door de aanroeper aangeleverde bytes.

XFDF-lezen. XfdfParser accepteert zowel namespaced als niet-namespaced xfdf-roots en matcht de rootnaam hoofdletterongevoelig, omdat sommige producenten een root-element in hoofdletters genereren. Hiërarchische <field>-bomen worden weer platgevlakt tot dot-notatie-namen, zodat schrijven en lezen round-trippen. Alle XML-loading schakelt netwerktoegang en externe-entiteitresolutie uit. parseFile voegt padresolutie en leesbaarheidscontroles toe vóór dezelfde parse.

Gegevensbinding. FormDataBinder::bind matcht gegevens-keys tegen veldnamen. Omdat FormField onveranderlijk is, maakt binding nieuwe instanties met bijgewerkte waarden; de originelen worden nooit gewijzigd. Het resultaat rapporteert drie diagnostische sets: gebonden veldnamen, gegevens-keys zonder overeenkomend veld, en velden die geen gegevens ontvingen. Checkbox-waarden normaliseren naar het aan/uit-toestandsmodel van ISO 32000-2:2020, 12.7.5.2.3: hoofdletterongevoelig yes, true, 1 en on mappen naar Yes; elke andere waarde mapt naar Off.

XFA-gegevensextractie. XfaParser::parse accepteert ruwe PDF-bytes. Het scant eerst op de /XFA-marker; ontbreekt de marker, dan retourneert het een lege XfaFormData. De extractie probeert vervolgens twee strategieën: een scan van stream…endstream-blokken op XFA-XML-indicatoren, daarna een directe zoektocht naar een <xdp:xdp>-document. Een enkel xdp:xdp-fragment wordt ongewijzigd geretourneerd; meerdere fragmenten worden samengevoegd tot een gesynthetiseerde xdp:xdp-envelop. parseXml extraheert de template- en datasets-pakketten en parse’t elk template-<field>-element tot een XfaFormField: het name-attribuut is verplicht, het type wordt afgeleid uit het UI-kindelement van het veld, de required-flag wordt afgeleid uit een validate-element met nullTest op error, en keuze-opties komen uit items-kinderen.

XFA-ondersteuning is gegevensgericht. De parser structureert de template- en datasets-pakketten. Het voert geen XFA-berekeningsscripts uit, rendert geen dynamische XFA-lay-outs en round-trippt niet elk pakkettype. Valideer de parser tegen je specifieke documentset voordat je erop vertrouwt.

Randgevallen en faalmodi

XfdfParser::parse('') gooit InvalidArgumentException. Invoer boven 10 MiB gooit InvalidArgumentException met vermelding van het plafond.
Misvormde XML gooit InvalidArgumentException met de verzamelde libxml-meldingen. Een welgevormd document waarvan de root niet xfdf is, gooit en noemt het werkelijke root-element.
Een XFDF-document zonder <fields>-element parse’t tot een lege XfdfData; dat is geen fout.
Veldelementen zonder name-attribuut worden zowel bij XFDF- als XFA-parsing overgeslagen. Een XFDF-veld zonder <value>-kind draagt geen entry bij.
XfaParser::parse('') gooit InvalidArgumentException. Een PDF zonder de /XFA-marker, of een waarvan de XFA-XML niet kan worden gelokaliseerd, retourneert een lege XfaFormData in plaats van te gooien.
hasXfa is een byte-marker-scan: elke /XFA-token in het bestand matcht, ook een in een ongebruikt object. De daaropvolgende extractiestap bepaalt of er bruikbare XML bestaat.
XFA-extractie onderzoekt hooguit de eerste 50 MiB van de PDF-bytestring; inhoud voorbij die grens wordt niet gescand.
XFA-XML boven 10 MiB gooit XfaParseException voordat er een DOM-boom wordt gematerialiseerd. Misvormde XFA-XML gooit XfaParseException met de libxml-meldingen.
Checkbox-normalisatie laat nooit onherkende waarden door; alles buiten de geaccepteerde aan-vormen mapt naar Off.
Het verwijderen van control-tekens door de writer is lossy: XML-1.0-ongeldige C0-bytes in namen, waarden of de pdfHref worden weggelaten zodat de uitvoer welgevormd blijft. TAB, LF en CR overleven.
Alle XML-parsing schakelt externe-entiteitresolutie en netwerktoegang uit (XXE-veilig).
Deze module voert geen cryptografische bewerkingen uit; de FIPS-modus verandert het gedrag niet.

Conformiteit

Gedrag	Referentie	Status
Model voor interactief formulier / velddictionary	ISO 32000-2:2020, 12.7	Afgestemd (productgefundeerd)
Checkbox aan/uit-toestandnormalisatie (`Yes`/`Off`)	ISO 32000-2:2020, 12.7.5.2.3	Afgestemd; clausule geciteerd in het citatierecord van deze pagina
XFDF-gegevensuitwisselingsstructuur	ISO 19444-1:2019	Afgestemd (productgefundeerd)
XFA-pakketnamen en namespace-URI’s	XFA Specification 3.3	Afgestemd (productgefundeerd)

Het RAG-corpus dat beschikbaar was tijdens het schrijven bevat ISO 19444-1:2019, de XFA Specification of W3C XML 1.0 niet, dus die afstemmingsverklaringen zijn productgefundeerd op basis van bronannotaties en tests in plaats van clausule-geciteerd. Deze verklaringen beschrijven functionaliteit ten opzichte van de genoemde documenten. NextPDF bezit geen conformiteitscertificering, en ondersteuning voor een clausule is geen certificeringsclaim.

Ontwikkelnotities

Elk entry point behalve XfaParser is statisch. XfaParser is instantieerbaar en stateless; één instantie kan veilig over documenten heen worden hergebruikt.
De bedoelde round-trip is: de Core form reader produceert FormField-waarden; FormDataExtractor of XfdfWriter serialiseert ze; XfdfParser leest de gegevens weer in; FormDataBinder past ze toe op een veldlijst. Hiërarchische namen overleven de round-trip via dot-notatie.
Gebruik de FormDataBindResult-diagnostiek (isFullyBound, unmatchedDataKeys, unboundFieldNames) om drift tussen een XFDF-gegevensbestand en een herzien PDF-template te detecteren voordat je een invulling accepteert.
XfdfData is een waardeobject: withField, withoutField en merge retourneren nieuwe instanties. Bij key-botsingen verkiest merge de waarden van het argument.
XfaFormData behoudt de ruwe template- en datasets-pakket-XML (templateXml, datasetsXml) zodat je pakketten kunt nabewerken die het veldmodel niet dekt.
Deze module parse’t zelf geen AcroForm-dictionaries uit PDF-bytes; ze consumeert velden die door de Core form reader worden geproduceerd. Alleen XfaParser werkt op ruwe PDF-inhoud.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.