Form

At a glance

NextPDF Pro reads and writes interactive form data: AcroForm field values, XFDF data files, and the data carried by XFA (XML Forms Architecture) templates. It complements the open-source Core form reader with data binding, extraction, and serialization.

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

Form is part of the Pro edition. There is no separate per-feature license flag.

Install

composer require nextpdf/pro:^3

The Form capability requires a valid NextPDF Pro license. See Availability & licensing.

Conceptual overview

A PDF interactive form — sometimes called an AcroForm — stores each field in a field dictionary, as defined in ISO 32000-2 §12.7. NextPDF Pro builds on the Core form reader to add three capabilities:

• AcroForm round-trip. FormDataExtractor reads field name/value pairs from parsed form fields and produces an XfdfData object or a plain name → value map. XfdfWriter performs the reverse, generating an XFDF document.
• XFDF read and write. XFDF is the XML data-exchange format for form values described by ISO 19444-1:2019. XfdfParser reads an XFDF file into structured data; XfdfWriter serializes field values to XFDF, with an optional reference back to the source PDF.
• XFA data extraction. XfaParser locates the XFA packets in a document, concatenates the XML fragments, and parses the template and datasets packets into structured field data.

XFA support scope

XFA support in NextPDF Pro is data-oriented, not a full XFA rendering or scripting engine. The parser extracts and structures the template and datasets packets so you can read field definitions and values. It does not execute XFA form-calculation scripts, render dynamic XFA layouts, or round-trip every XFA packet type. Test the parser against your specific documents before relying on it for a given XFA form set. All XML parsing disables external-entity loading (XXE-safe).

Why it works this way

XFA support is scoped to data, not rendering, on purpose. ISO 32000-2 marks the form dictionary’s XFA entry as deprecated in PDF 2.0 (§12.7). A full XFA layout and scripting engine would chase a legacy surface most workloads no longer need. NextPDF Pro instead extracts the template and datasets packets, where the durable field data lives, and declines the rest. The same posture drives XXE-off parsing and the scan ceiling, because form input often arrives from untrusted parties. That keeps the Pro form surface a thin, predictable extension of the Core AcroForm model.

Design background: From fillable form to frozen record: AcroForm fill and flatten.

API surface

Class	Responsibility
FormDataExtractor	Extract AcroForm field values as XfdfData or an array.
XfdfParser	Parse an XFDF document into structured data.
XfdfWriter	Serialize field values to XFDF, optional PDF reference.
XfaParser	Extract and parse XFA template and datasets packets.
FormDataBinder	Bind a data map back onto form fields.

The full method-level reference is in the Form deep reference.

Code sample — Quick start

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

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

Code sample — Production

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

Edge cases & gotchas

• XfaParser rejects PDF input larger than its scan ceiling rather than reading unbounded data.
• A document may carry both interactive and non-interactive forms; extraction targets terminal field dictionaries.
• XFDF round-trips flat field structures; deeply nested field hierarchies may need explicit handling.

Performance

Extraction and serialization are linear in the number of form fields. XFA parsing cost scales with the size of the embedded XML packets.

Security notes

All XML parsing disables external-entity resolution to prevent XXE. Treat XFDF and XFA input from untrusted sources as hostile and validate the parsed field set before binding it back into a document.

Conformance

Behavior	Reference	Status
Interactive form / field dictionary model	ISO 32000-2 §12.7	Aligned (paraphrased)
XFDF data-exchange format	ISO 19444-1:2019	Aligned

This table records the specifications NextPDF Pro is built against.

Behavior contract

• FormDataExtractor reads name/value pairs from parsed terminal field dictionaries and returns an XfdfData object or a plain name → value array.
• XfdfParser parses an XFDF document into structured data; XfdfWriter serializes field values to XFDF with an optional reference back to the source PDF.
• XfaParser locates the XFA packets, concatenates the XML fragments, and parses the template and datasets packets into structured field data. It rejects PDF input larger than its scan ceiling rather than reading unbounded data.
• XFA support is data-oriented: the parser extracts and structures template and datasets packets. It does not execute XFA form-calculation scripts, render dynamic XFA layouts, or round-trip every XFA packet type.
• All XML parsing disables external-entity resolution (XXE-safe).

Enterprise boundary note

Enterprise does not change Form behavior. Enterprise adds higher-tier compliance and archival features documented separately; they are not required for AcroForm round-trip, XFDF read/write, or XFA data extraction.

Core fallback / alternative

NextPDF Core’s open-source form reader reads form fields. XFDF read/write, XFA data extraction, and field binding are Pro additions. See /modules/form/.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

See also

• Interop — versioned form-data DTOs for external systems.
• Core Form module — open-source form reader.
• Form — Deep Reference — method-level reference for the Pro form classes.