Pro Edition

Form — Detailreferenz

Auf einen Blick

Diese Seite ist die Detailreferenz für das Pro-Modul Form. Sie behandelt die Extraktion von AcroForm-Werten, das Lesen und Schreiben von XFDF, die Datenbindung sowie die Extraktion von XFA-Daten. Das Modul verarbeitet NextPDF\Form\FormField-Werte, die vom Core-Formularleser erzeugt werden, und ergänzt darauf aufbauend Serialisierung, Parsing und Bindung. Die XFA-Unterstützung ist datenorientiert: Der Parser strukturiert die Template- und Datasets-Pakete. Er führt keine XFA-Berechnungsskripte aus und rendert keine dynamischen XFA-Layouts.

Verfügbarkeit & Lizenzierung

Diese Funktion ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erwerben.

Es gibt kein funktionsspezifisches Lizenz-Flag. Dies ist eine Funktion der Pro-Edition.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`FormDataExtractor::extract`	`list<FormField> $fields`	Liest Name und Wert jedes Felds	`XfdfData`	—	Schließt Felder mit leerem Wert ein.
`FormDataExtractor::toArray`	`list<FormField> $fields`	Erstellt eine Name-zu-Wert-String-Zuordnung	`array<string, string>`	—	Ein späterer doppelter Name überschreibt einen früheren.
`FormDataExtractor::toXfdf`	`list<FormField> $fields`, `?string $pdfHref = null`	Delegiert an `XfdfWriter::fromFields`	`string` (XFDF-XML)	—	Komfortpfad für den Export in einem einzigen Aufruf.
`FormDataExtractor::extractNonEmpty`	`list<FormField> $fields`	Überspringt Felder, deren Wert die leere Zeichenkette ist	`XfdfData`	—	—
`FormDataExtractor::getEmptyFieldNames`	`list<FormField> $fields`	Listet Namen von Feldern ohne gesetzten Wert auf	`list<string>`	—	Komplement zu `extractNonEmpty`.
`XfdfWriter::fromFields`	`list<FormField> $fields`, `?string $pdfHref = null`	Sammelt Name-zu-Wert-Paare, delegiert an `fromArray`	`string` (XFDF-XML)	—	—
`XfdfWriter::fromArray`	`array<string, string> $data`, `?string $pdfHref = null`	Kapselt die Zuordnung in `XfdfData`, delegiert	`string` (XFDF-XML)	—	—
`XfdfWriter::fromXfdfData`	`XfdfData $data`, `?string $pdfHref = null`	Serialisiert zu XFDF; Namen in Punktnotation werden als hierarchische `<field>`-Elemente verschachtelt	`string` (XFDF-XML)	—	Entfernt in XML 1.0 unzulässige Steuerzeichen; siehe den Verhaltensvertrag.
`XfdfParser::parse`	`string $xfdfXml`	Lädt das XML XXE-sicher und flacht Felder in Punktnotation ab	`XfdfData`	`InvalidArgumentException`	Eingabeobergrenze 10 MiB; akzeptiert Roots mit und ohne Namespace.
`XfdfParser::parseFile`	`string $filePath`	Löst den Pfad auf, liest die Datei, delegiert an `parse`	`XfdfData`	`InvalidArgumentException`	Fehlende, nicht als Datei vorliegende oder nicht lesbare Pfade lösen aus.
`XfaParser::parse`	`string $pdfData`	Markerprüfung, XML-Extraktion, Paket-Parsing	`XfaFormData`	`InvalidArgumentException`, `XfaParseException`	Ohne `/XFA`-Marker wird ein leeres Ergebnis zurückgegeben, kein Fehler.
`XfaParser::hasXfa`	`string $pdfData`	Durchsucht die Bytes nach dem `/XFA`-Marker	`bool`	—	Byte-Marker-Scan; jedes Vorkommen des Tokens trifft zu.
`XfaParser::extractXfaXml`	`string $pdfData`	Stream-Scan nach XFA-Markern, dann direkte `<xdp:xdp>`-Suche	`string` (XFA-XML oder `''`)	`RuntimeException` (deklariert)	Scannt höchstens die ersten 50 MiB der Eingabe.
`XfaParser::parseXml`	`string $xml`	Extrahiert Template- und Datasets-Pakete, parst `<field>`-Elemente	`XfaFormData`	`XfaParseException`	XML-Obergrenze 10 MiB, vor dem DOM-Laden erzwungen.
`FormDataBinder::bind`	`list<FormField> $fields`, `XfdfData $data`	Erstellt neue `FormField`-Instanzen mit gebundenen Werten	`FormDataBindResult`	—	Originale werden nie verändert; Kontrollkästchen normalisieren auf `Yes`/`Off`.
`FormDataBinder::fromXfdf`	`list<FormField> $fields`, `string $xfdfXml`	Parst das XFDF, bindet dann	`FormDataBindResult`	`InvalidArgumentException`	Die Fehlermodi entsprechen denen von `XfdfParser::parse`.
`FormDataBinder::fromArray`	`list<FormField> $fields`, `array<string, string> $data`	Kapselt die Zuordnung in `XfdfData`, bindet dann	`FormDataBindResult`	—	—
`FormDataBindResult`	`isFullyBound`, `hasNoUnmatchedKeys`, `boundCount`, `fieldCount`; readonly `fields`, `boundFieldNames`, `unmatchedDataKeys`, `unboundFieldNames`	Unveränderliche Bindungsdiagnostik	pro Methode	—	`isFullyBound` erfordert null nicht zugeordnete Schlüssel und null ungebundene Felder.
`XfdfData`	`hasField`, `getValue`, `count`, `isEmpty`, `getFieldNames`, `withField`, `withoutField`, `merge`; readonly `fields`	Unveränderlicher Name-zu-Wert-Container	pro Methode	—	`with*` und `merge` geben neue Instanzen zurück; `merge` bevorzugt die Werte des Arguments.
`XfaFormData`	`getField`, `hasField`, `count`, `fieldNames`; readonly `fields`, `templateXml`, `datasetsXml`	Unveränderliches XFA-Parse-Ergebnis	pro Methode	—	Trägt das rohe Template- und Datasets-Paket-XML für den Roundtrip.
`XfaFormField`	readonly `name`, `type`, `value`, `required`, `caption`, `options`	Unveränderlicher Einzelfeld-Datensatz	—	—	`type` ist eines von `text`, `numeric`, `date`, `choice`, `button`, `signature`.
`XfaPacket`	Enum-Fälle `Template`, `Datasets`, `Config`, `LocaleSet`, `ConnectionSet`, `Form`; `xmlNamespace()`	String-basierte Paket-Enumeration	`string` aus `xmlNamespace()`	—	Namespace-URIs folgen der 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

Ausnahmen

NextPDF\Pro\Form\Exception\XfaParseException erweitert RuntimeException — die XFA-Nutzlast kann nicht in ein XfaFormData geparst werden. Die Ableitung ist bewusst gewählt: Bestehende catch (RuntimeException $e)-Aufrufstellen funktionieren weiterhin.
SPL InvalidArgumentException — leere, überdimensionierte, fehlerhafte oder nicht als XFDF vorliegende Eingabe an XfdfParser; leere PDF-Eingabe an XfaParser::parse; nicht lesbare Pfade in XfdfParser::parseFile.

Verhaltensvertrag

AcroForm-Extraktion. FormDataExtractor durchläuft die von Ihnen übergebene Feldliste und liest Name und Wert jedes Felds. extract gibt ein XfdfData zurück; toArray gibt eine einfache Name-zu-Wert-String-Zuordnung zurück. extractNonEmpty verwirft Felder, deren Wert die leere Zeichenkette ist; getEmptyFieldNames gibt die komplementäre Namensliste zurück. Die Extraktion verändert die Eingabefelder niemals.

XFDF-Schreiben. XfdfWriter erzeugt ein Dokument, das der Struktur von ISO 19444-1:2019 entspricht. Die Ausgabe beginnt mit der XFDF-XML-Deklaration und einem xfdf-Root im Adobe-XFDF-Namespace (http://ns.adobe.com/xfdf/) mit xml:space="preserve". Ein nicht-null pdfHref gibt eine <f href="..."/>-Referenz zurück auf die Quell-PDF aus. Feldnamen in Punktnotation (zum Beispiel address.city) werden in einen hierarchischen <field>-Elementbaum verschachtelt. Werte und Attribute maskieren die fünf XML-Metazeichen. Feldnamen, Werte und der pdfHref werden zusätzlich auf Wohlgeformtheit normalisiert: Die von XML 1.0 verbotenen C0-Steuerzeichen werden entfernt, während TAB, LF und CR erhalten bleiben. Diese Normalisierung ist bewusst verlustbehaftet, sodass der Writer unabhängig von den vom Aufrufer gelieferten Bytes stets wohlgeformtes, wieder-parsbares XFDF ausgibt.

XFDF-Lesen. XfdfParser akzeptiert sowohl xfdf-Roots mit als auch ohne Namespace und gleicht den Root-Namen ohne Beachtung der Groß-/Kleinschreibung ab, da einige Erzeuger ein Root-Element in Großbuchstaben ausgeben. Hierarchische <field>-Bäume werden wieder zu Namen in Punktnotation abgeflacht, sodass Schreiben und Lesen einen Roundtrip bilden. Jedes XML-Laden deaktiviert Netzwerkzugriff und die Auflösung externer Entitäten. parseFile stellt dem gleichen Parse-Vorgang eine Pfadauflösung und Lesbarkeitsprüfung voran.

Datenbindung. FormDataBinder::bind gleicht Datenschlüssel mit Feldnamen ab. Da FormField unveränderlich ist, erzeugt die Bindung neue Instanzen mit aktualisierten Werten; die Originale werden nie verändert. Das Ergebnis meldet drei Diagnosemengen: gebundene Feldnamen, Datenschlüssel ohne zugehöriges Feld und Felder, die keine Daten erhalten haben. Kontrollkästchenwerte normalisieren auf das Ein/Aus-Zustandsmodell von ISO 32000-2:2020, 12.7.5.2.3: yes, true, 1 und on (ohne Beachtung der Groß-/Kleinschreibung) werden auf Yes abgebildet; jeder andere Wert wird auf Off abgebildet.

XFA-Datenextraktion. XfaParser::parse akzeptiert rohe PDF-Bytes. Es sucht zunächst nach dem /XFA-Marker; ohne den Marker gibt es ein leeres XfaFormData zurück. Die Extraktion versucht dann zwei Strategien: einen Scan von stream…endstream-Blöcken nach XFA-XML-Indikatoren, dann eine direkte Suche nach einem <xdp:xdp>-Dokument. Ein einzelnes xdp:xdp-Fragment wird unverändert zurückgegeben; mehrere Fragmente werden in einer synthetisierten xdp:xdp-Hülle zusammengefügt. parseXml extrahiert die Template- und Datasets-Pakete und parst jedes Template-<field>-Element in ein XfaFormField: Das Namensattribut ist erforderlich, der Typ leitet sich vom UI-Kindelement des Felds ab, das Erforderlich-Flag leitet sich von einem validate-Element mit nullTest auf error ab, und Auswahloptionen stammen aus items-Kindelementen.

Die XFA-Unterstützung ist datenorientiert. Der Parser strukturiert die Template- und Datasets-Pakete. Er führt keine XFA-Berechnungsskripte aus, rendert keine dynamischen XFA-Layouts und bildet nicht jeden Pakettyp im Roundtrip ab. Validieren Sie den Parser anhand Ihres spezifischen Dokumentsatzes, bevor Sie sich darauf verlassen.

Randfälle & Fehlermodi

XfdfParser::parse('') wirft InvalidArgumentException. Eine Eingabe über 10 MiB wirft InvalidArgumentException unter Nennung der Obergrenze.
Fehlerhaftes XML wirft InvalidArgumentException mit den gesammelten libxml-Meldungen. Ein wohlgeformtes Dokument, dessen Root nicht xfdf ist, wirft und nennt das tatsächliche Root-Element.
Ein XFDF-Dokument ohne <fields>-Element parst zu einem leeren XfdfData; das ist kein Fehler.
Feldelemente ohne name-Attribut werden sowohl beim XFDF- als auch beim XFA-Parsing übersprungen. Ein XFDF-Feld ohne <value>-Kindelement trägt keinen Eintrag bei.
XfaParser::parse('') wirft InvalidArgumentException. Eine PDF ohne den /XFA-Marker oder eine, deren XFA-XML nicht auffindbar ist, gibt ein leeres XfaFormData zurück, statt zu werfen.
hasXfa ist ein Byte-Marker-Scan: Jedes /XFA-Token in der Datei trifft zu, auch eines in einem ungenutzten Objekt. Der nachfolgende Extraktionsschritt entscheidet, ob brauchbares XML vorhanden ist.
Die XFA-Extraktion untersucht höchstens die ersten 50 MiB der PDF-Byte-Zeichenkette; Inhalt jenseits dieser Grenze wird nicht gescannt.
XFA-XML über 10 MiB wirft XfaParseException, bevor irgendein DOM-Baum materialisiert wird. Fehlerhaftes XFA-XML wirft XfaParseException mit den libxml-Meldungen.
Die Kontrollkästchen-Normalisierung reicht unerkannte Werte niemals durch; alles außerhalb der akzeptierten Ein-Formen wird auf Off abgebildet.
Das Entfernen von Steuerzeichen durch den Writer ist verlustbehaftet: In XML 1.0 unzulässige C0-Bytes in Namen, Werten oder dem pdfHref werden verworfen, damit die Ausgabe wohlgeformt bleibt. TAB, LF und CR bleiben erhalten.
Jedes XML-Parsing deaktiviert die Auflösung externer Entitäten und den Netzwerkzugriff (XXE-sicher).
Dieses Modul führt keine kryptografischen Operationen aus; der FIPS-Modus ändert sein Verhalten nicht.

Konformität

Verhalten	Referenz	Status
Modell für interaktive Formulare / Feld-Dictionaries	ISO 32000-2:2020, 12.7	Konform (produktbasiert)
Kontrollkästchen-Ein/Aus-Zustandsnormalisierung (`Yes`/`Off`)	ISO 32000-2:2020, 12.7.5.2.3	Konform; Klausel im Zitationsdatensatz dieser Seite zitiert
XFDF-Datenaustauschstruktur	ISO 19444-1:2019	Konform (produktbasiert)
XFA-Paketnamen und Namespace-URIs	XFA Specification 3.3	Konform (produktbasiert)

Das zum Zeitpunkt der Erstellung verfügbare RAG-Korpus enthält weder ISO 19444-1:2019 noch die XFA Specification oder W3C XML 1.0, sodass diese Konformitätsaussagen produktbasiert aus Quellannotationen und Tests abgeleitet und nicht klauselzitiert sind. Diese Aussagen beschreiben die Fähigkeit gegenüber den referenzierten Dokumenten. NextPDF hält keine Konformitätszertifizierung, und die Unterstützung einer Klausel ist keine Zertifizierungsaussage.

Entwicklungshinweise

Jeder Einstiegspunkt außer XfaParser ist statisch. XfaParser ist instanziierbar und zustandslos; eine Instanz kann sicher über Dokumente hinweg wiederverwendet werden.
Der vorgesehene Roundtrip lautet: Der Core-Formularleser erzeugt FormField-Werte; FormDataExtractor oder XfdfWriter serialisiert sie; XfdfParser liest die Daten zurück; FormDataBinder wendet sie auf eine Feldliste an. Hierarchische Namen überstehen den Roundtrip über die Punktnotation.
Nutzen Sie die FormDataBindResult-Diagnostik (isFullyBound, unmatchedDataKeys, unboundFieldNames), um vor dem Akzeptieren einer Befüllung eine Abweichung zwischen einer XFDF-Datendatei und einem überarbeiteten PDF-Template zu erkennen.
XfdfData ist ein Wertobjekt: withField, withoutField und merge geben neue Instanzen zurück. Bei Schlüsselkollisionen bevorzugt merge die Werte des Arguments.
XfaFormData behält das rohe Template- und Datasets-Paket-XML (templateXml, datasetsXml), sodass Sie Pakete nachbearbeiten können, die das Feldmodell nicht abdeckt.
Dieses Modul parst AcroForm-Dictionaries nicht selbst aus PDF-Bytes; es verarbeitet vom Core-Formularleser erzeugte Felder. Nur XfaParser operiert auf rohem PDF-Inhalt.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe sind nicht Teil des Umfangs.