Formular

Auf einen Blick

NextPDF Pro liest und schreibt interaktive Formulardaten: AcroForm-Feldwerte, XFDF-Datendateien und die von XFA-Vorlagen (XML Forms Architecture) getragenen Daten. Es ergänzt den Open-Source-Core-Formular-Reader um Datenbindung, Extraktion und Serialisierung.

Verfügbarkeit & Lizenzierung

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

Form ist Teil der Pro-Edition. Es gibt kein separates Lizenz-Flag pro Funktion.

Installation

composer require nextpdf/pro:^3

Die Form-Fähigkeit erfordert eine gültige NextPDF Pro-Lizenz. Siehe Verfügbarkeit & Lizenzierung.

Konzeptioneller Überblick

Ein interaktives PDF-Formular — manchmal AcroForm genannt — speichert jedes Feld in einem Feld-Dictionary, wie in ISO 32000-2 §12.7 definiert. NextPDF Pro baut auf dem Core-Formular-Reader auf und ergänzt drei Fähigkeiten:

• AcroForm-Round-Trip. FormDataExtractor liest Feldname/Wert-Paare aus geparsten Formularfeldern und erzeugt ein XfdfData-Objekt oder eine einfache name → value-Map. XfdfWriter macht das Umgekehrte und generiert ein XFDF-Dokument.
• XFDF lesen und schreiben. XFDF ist das XML-Datenaustauschformat für Formularwerte, beschrieben durch ISO 19444-1:2019. XfdfParser liest eine XFDF-Datei in strukturierte Daten; XfdfWriter serialisiert Feldwerte zu XFDF, mit einer optionalen Referenz zurück auf das Quell-PDF.
• XFA-Datenextraktion. XfaParser lokalisiert die XFA-Pakete in einem Dokument, verkettet die XML-Fragmente und parst die Template- und Datasets-Pakete in strukturierte Felddaten.

Geltungsbereich der XFA-Unterstützung

Die XFA-Unterstützung in NextPDF Pro ist datenorientiert, keine vollständige XFA-Rendering- oder Skripting-Engine. Der Parser extrahiert und strukturiert die Template- und Datasets-Pakete, sodass Sie Felddefinitionen und -werte lesen können. Er führt keine XFA-Formularberechnungs-Skripte aus, rendert keine dynamischen XFA-Layouts und macht nicht jeden XFA-Pakettyp im Round-Trip durch. Testen Sie den Parser an Ihren spezifischen Dokumenten, bevor Sie sich für einen bestimmten XFA-Formularsatz auf ihn verlassen. Jegliches XML-Parsing deaktiviert das Laden externer Entitäten (XXE-sicher).

Warum es so funktioniert

Die XFA-Unterstützung ist absichtlich auf Daten beschränkt, nicht auf Rendering. ISO 32000-2 kennzeichnet den XFA-Eintrag des Formular-Dictionaries in PDF 2.0 als veraltet (§12.7). Eine vollständige XFA-Layout- und Skripting-Engine würde einer Legacy-Oberfläche hinterherjagen, die die meisten Workloads nicht mehr benötigen. NextPDF Pro extrahiert stattdessen die Template- und Datasets-Pakete, in denen die dauerhaften Felddaten liegen, und verzichtet auf den Rest. Dieselbe Haltung treibt das XXE-abgeschaltete Parsing und die Scan-Obergrenze an, weil Formulareingaben oft von nicht vertrauenswürdigen Parteien stammen. Das hält die Pro-Formular-Oberfläche als schlanke, vorhersehbare Erweiterung des Core-AcroForm-Modells.

Design-Hintergrund: Vom ausfüllbaren Formular zum eingefrorenen Datensatz: AcroForm ausfüllen und flach machen.

API-Oberfläche

Klasse	Verantwortung
FormDataExtractor	AcroForm-Feldwerte als XfdfData oder Array extrahieren.
XfdfParser	Ein XFDF-Dokument in strukturierte Daten parsen.
XfdfWriter	Feldwerte zu XFDF serialisieren, optionale PDF-Referenz.
XfaParser	XFA-Template- und Datasets-Pakete extrahieren und parsen.
FormDataBinder	Eine Daten-Map zurück auf Formularfelder binden.

Die vollständige Referenz auf Methodenebene finden Sie in der Form Deep Reference.

Codebeispiel — Schnellstart

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

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

Codebeispiel — Produktion

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()]);
}

Randfälle & Fallstricke

• XfaParser weist PDF-Eingaben größer als seine Scan-Obergrenze ab, statt unbegrenzte Daten zu lesen.
• Ein Dokument kann sowohl interaktive als auch nicht-interaktive Formulare tragen; die Extraktion zielt auf terminale Feld-Dictionaries.
• XFDF macht flache Feldstrukturen im Round-Trip durch; tief verschachtelte Feldhierarchien benötigen möglicherweise explizite Behandlung.

Performance

Extraktion und Serialisierung sind linear in der Anzahl der Formularfelder. Die XFA-Parsing-Kosten skalieren mit der Größe der eingebetteten XML-Pakete.

Sicherheitshinweise

Jegliches XML-Parsing deaktiviert die Auflösung externer Entitäten, um XXE zu verhindern. Behandeln Sie XFDF- und XFA-Eingaben aus nicht vertrauenswürdigen Quellen als feindlich und validieren Sie den geparsten Feldsatz, bevor Sie ihn zurück in ein Dokument binden.

Konformität

Verhalten	Referenz	Status
Interaktives Formular / Feld-Dictionary-Modell	ISO 32000-2 §12.7	Abgestimmt (paraphrasiert)
XFDF-Datenaustauschformat	ISO 19444-1:2019	Abgestimmt

Diese Tabelle hält die Spezifikationen fest, gegen die NextPDF Pro gebaut ist. Sie ist keine Aussage über eine formelle Zertifizierung.

Verhaltensvertrag

• FormDataExtractor liest Name/Wert-Paare aus geparsten terminalen Feld-Dictionaries und gibt ein XfdfData-Objekt oder ein einfaches name → value-Array zurück.
• XfdfParser parst ein XFDF-Dokument in strukturierte Daten; XfdfWriter serialisiert Feldwerte zu XFDF mit einer optionalen Referenz zurück auf das Quell-PDF.
• XfaParser lokalisiert die XFA-Pakete, verkettet die XML-Fragmente und parst die Template- und Datasets-Pakete in strukturierte Felddaten. Es weist PDF-Eingaben größer als seine Scan-Obergrenze ab, statt unbegrenzte Daten zu lesen.
• Die XFA-Unterstützung ist datenorientiert: Der Parser extrahiert und strukturiert Template- und Datasets-Pakete. Er führt keine XFA-Formularberechnungs-Skripte aus, rendert keine dynamischen XFA-Layouts und macht nicht jeden XFA-Pakettyp im Round-Trip durch.
• Jegliches XML-Parsing deaktiviert die Auflösung externer Entitäten (XXE-sicher).

Hinweis zur Enterprise-Abgrenzung

Enterprise ändert das Form-Verhalten nicht. Enterprise ergänzt Compliance- und Archivfunktionen höherer Stufe, die separat dokumentiert sind; sie sind für AcroForm-Round-Trip, XFDF lesen/schreiben oder XFA-Datenextraktion nicht erforderlich.

Core-Rückfalloption / Alternative

Der Open-Source-Formular-Reader von NextPDF Core liest Formularfelder. XFDF lesen/schreiben, XFA-Datenextraktion und Feldbindung sind Pro-Ergänzungen. Siehe /modules/form/.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Helferklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe sind nicht Gegenstand.

Siehe auch

• Interop — versionierte Formulardaten-DTOs für externe Systeme.
• Core Form-Modul — Open-Source-Formular-Reader.
• Form — Deep Reference — Referenz auf Methodenebene für die Pro-Formularklassen.