Formular: interaktive AcroForm-Felder und Flattening

Auf einen Blick

Mit dem Form-Modul erstellen Sie interaktive PDF-Formulare. Es erzeugt Text-, Kontrollkästchen-, Optionsfeld-, Auswahl- (Liste/Kombinationsfeld), Schaltflächen- und Signaturfelder, ordnet sie in einer parent/child-Hierarchie an, schreibt sie als PDF-Objekte mit Appearance-Streams und kann das Formular in statischen Seiteninhalt flatten.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Ein interaktives PDF-Formular wird durch das AcroForm repräsentiert: eine Feldhierarchie auf Dokumentebene, deren terminale Felder mit Widget-Annotationen auf den Seiten verknüpft werden. ISO 32000-2 §12.7 definiert dieses Formular und seine Feld-Dictionaries, einschließlich der AcroForm-Wurzel und der Feldhierarchie. Dieses Modul stellt dafür den zugehörigen Encoder der Engine bereit.

Die Klasse FormFieldManager ist die primäre Schnittstelle. Sie stellt die Builder textField(), checkBox(), radioButton(), button() und signatureField() bereit, verfolgt die Felder und serialisiert sie mit writeFields(). Für jedes Widget gibt sie einen Form-XObject-Appearance-Stream aus (/Subtype /Form, /BBox), wie es §8.10 verlangt. FormField ist das Feld-Value-Object. FormFieldDictionaryBuilder wandelt ein Feld in sein PDF-Dictionary um und wendet die typspezifischen Einträge und Flag-Bits an (Text, Kontrollkästchen, Auswahl, Schaltfläche). Der Manager und FormField sind @since 1.0.0. Der Dictionary-Builder ist @since 1.1.0.

FormFieldHierarchy modelliert den parent/child-Feldbaum: addChild(), getRootFieldNames(), getChildren(), getParent() und ein walkDepthFirst()-Visitor. Ein vollständig qualifizierter Feldname ist der durch Punkte getrennte Pfad durch diese Hierarchie und entspricht damit dem Modell, das §12.7 für verschachtelte Felder vorgibt.

FormFlattener rendert das Formular in statischen Seiteninhalt — flatten() gibt ein FlattenResult zurück —, sodass ein ausgefülltes Formular für die Archivierung eingefroren werden kann. FieldMDP und FieldMdpAction modellieren die Feldsperren-Transformation. Ein signiertes Dokument kann eine benannte Menge von Feldern gegen weitere Änderungen sperren. FieldMdpAction beschreibt den Sperrumfang. Sein requiresFieldList() gibt an, wann eine explizite Feldliste zwingend erforderlich ist. FieldMDP ist @since 2.0.0.

API-Oberfläche

Klasse	Wichtige Member	Rolle
FormFieldManager	textField(), checkBox(), radioButton(), button(), signatureField(), addChildField(), getHierarchy(), writeFields()	Builder für Felder und Serialisierer (@since 1.0.0)
FormField	Feld-Value-Object	Ein AcroForm-Feld (@since 1.0.0)
FormFieldDictionaryBuilder	buildFieldDictionary(), applyTextFieldOptions(), applyCheckBoxOptions(), applyChoiceFieldOptions(), applyButtonOptions()	Builder für Feld-Dictionaries (@since 1.1.0)
FormFieldHierarchy	addChild(), getRootFieldNames(), getChildren(), getParent(), walkDepthFirst()	Parent/child-Feldbaum (@since 2.0.0)
FormFlattener	flatten(array $fields, array $pages): FlattenResult	Flattening des Formulars in statischen Inhalt (@since 1.0.0)
FieldMDP	toTransformParams()	Feldsperren-Transformation (FieldMDP) (@since 2.0.0)
FieldMdpAction (Enum)	requiresFieldList()	Feldsperrenumfang (@since 2.0.0)

Führen Sie composer docs:generate-api-php -- --module=Form aus, um die vollständige PHPDoc-Tabelle zu erhalten.

Codebeispiel — Schnellstart

Quelle: examples/30-form-fields.php.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Form\FormFieldManager;

$form = new FormFieldManager();

$form->textField(name: 'applicant_name', x: 50, y: 700, w: 200, h: 18);
$form->checkBox(name: 'agree_terms', x: 50, y: 660, size: 12);
$form->radioButton(name: 'plan', x: 50, y: 620, size: 12 /* + option set */);

// The Writer invokes $form->writeFields(...) during document serialization.

Codebeispiel — Produktion

Erstellen Sie eine Feldmenge für ein signiertes Dokument und sperren Sie die signierten Felder per FieldMDP.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Form\FieldMDP;
use NextPDF\Form\FieldMdpAction;
use NextPDF\Form\FormFieldManager;

$form = new FormFieldManager();
$form->textField(name: 'contract_value', x: 50, y: 700, w: 160, h: 18);
$form->signatureField(name: 'approver_sig', x: 50, y: 600, w: 200, h: 60);

// Lock only the named fields after signing.
$lock = new FieldMDP(
    action: FieldMdpAction::Include,
    fields: ['contract_value'],
);

$transformParams = $lock->toTransformParams();
// $transformParams is attached to the signature's transform method by the signing layer.

Sonderfälle & Fallstricke

• Ein Feldname ist ein vollständig qualifizierter, durch Punkte getrennter Pfad durch FormFieldHierarchy. Zwei terminale Felder mit demselben vollständig qualifizierten Namen sind in einem Viewer dasselbe logische Feld — für die Eindeutigkeit ist der Aufrufer verantwortlich.
• FieldMdpAction::requiresFieldList() gibt an, wann eine Feldliste zwingend erforderlich ist. Eine Include-/Exclude-Aktion ohne die erforderliche Liste ist eine fehlerhafte Sperre; prüfen Sie das Flag.
• FormFlattener::flatten() zerstört die Interaktivität bewusst — das Ergebnis ist statischer Inhalt. Bewahren Sie die interaktive Quelle auf, falls Sie sie später benötigen.
• Appearance-Streams werden pro Widget ausgegeben. Ein Feld ohne Appearance kann je nach Viewer unterschiedlich dargestellt werden; lassen Sie die Appearance vom Manager generieren, anstatt sie wegzulassen.
• signatureField() erstellt nur den Feldplatzhalter. Die eigentliche Signatur zu erzeugen, ist Aufgabe der Security-/Signing-Schicht, nicht dieses Moduls.

Performance

Felderstellung und Serialisierung sind O(n) in der Feldanzahl, zuzüglich eines Form-XObject-Appearance-Streams pro Widget. Die Kosten des Flattenings skalieren mit dem gerenderten Inhalt, nicht mit der Feldanzahl. Die standardmäßige Referenzlast bleibt innerhalb des Budgets von 1500 ms Wall-Time / 64 MB Peak. Das Reproduzierbarkeitsprofil ist structural: Objektnummern und das Trailer-/ID variieren zwischen den Durchläufen. Zwei Dokumente mit demselben Formular sind strukturell gleich, aber nicht byte-identisch.

Sicherheitshinweise

Formularfeldwerte sind Benutzereingaben. Das Modul versieht Stringwerte für die PDF-Serialisierung mit Escape-Sequenzen (PdfStringEscaper), sodass ein Feldwert nicht aus seinem PDF-String ausbrechen und Struktur injizieren kann. Wenn ein Formular verschlüsselt ist, wird der Feldinhalt von der AES-256-Verschlüsselung des Dokuments abgedeckt. FieldMDP ist eine Sicherheitskontrolle: Es sperrt benannte Felder gegen Änderungen nach der Signatur. Eine Feldsperre, die nicht mit der signierten Feldmenge übereinstimmt, untergräbt diese Kontrolle — legen Sie den Sperrumfang bewusst fest. Behandeln Sie jeden aus einem ausgefüllten Formular extrahierten Wert als nicht vertrauenswürdige Eingabe. Siehe das Sicherheitsmodell der Engine unter /modules/core/security/.

Konformität

Die Formularstrukturen, die dieses Modul ausgibt, folgen dem Modell für interaktive Formulare in ISO 32000-2 §12.7 — mit AcroForm-Wurzel, Feld-Dictionaries und Dokument-Feldhierarchie. Appearances pro Widget werden gemäß §8.10 als Form-XObjects ausgegeben; dies ist inline in src/Form/ dokumentiert. Dies sind Implementierungsfakten, die durch tests/Unit/Form/ abgedeckt werden. Sie sind keine Aussage über eine durchgängige PDF-2.0-Konformität. Die Konformität des gesamten Dokuments wird durch die Oracle- und Golden-Suites in /modules/core/conformance/ validiert.

Siehe auch

• Navigation-Modul — die Widget-Annotationen, mit denen die Felder verknüpft werden.
• Security-Modul — Signieren und das FieldMDP-Vertrauensmodell.
• Accessibility-Modul — das Taggen von Formularfeldern für PDF/UA.
• Konformitätsübersicht