From fillable form to frozen record: AcroForm fill and flatten

SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7

At a glance

A PDF form has two lives. First it is fillable: a set of typed fields a person types into, ticks, or chooses from. Then, when the agreement is made, it becomes a frozen record: the values are printed into the page itself so every viewer, on every device, sees exactly what was agreed. NextPDF builds the first and produces the second, with one deliberate guarantee — it will not quietly throw the values away on the way across.

Why this matters

The gap between “what I filled in” and “what you see” is where forms go wrong.

A fillable field is, technically, a small interactive widget drawn over the page. Different viewers can render it differently. Some honour a saved value, some regenerate the look from a font you do not have, some let a reader edit it again. For a draft that you want collaborators to keep editing, that is the point. For the signed copy of what was agreed, it is a liability: the record should not depend on which application opens it, and it should not be editable after the fact.

Flattening closes the gap. It takes each field’s current value and paints it into the page as ordinary, immutable graphics — the same kind of content as a heading or a logo. After that, there is no field to edit and no appearance to regenerate. The document shows one thing, the same thing, everywhere.

The short version

• An AcroForm is the document’s interactive form: a tree of typed fields declared in the catalogue (SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7).
• Each field is made visible by a widget annotation — the on-page rectangle you click or type into (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5).
• NextPDF ships typed builders for every supported non-signature form control — text, checkbox, radio, list box and combo box (choice), and push button — plus a field manager that writes them as proper PDF objects.
• Flattening renders each field’s value into the page content stream and removes the now-redundant interactive form, leaving a frozen record.
• If you ask to flatten a document that has no pages, NextPDF does not silently destroy your field values. It preserves the form, warns you, and lets you add a page and flatten correctly.

How NextPDF approaches it

The mental model is two layers. The field is the data: a name, a type, a value, and a set of flags. The widget is the picture: a rectangle on a specific page that lets a viewer interact with the field (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5). One field can even surface through several widgets — that is exactly how a radio group works, several on-page choices wired to one underlying value.

NextPDF gives each field type its own typed builder, so you never assemble a raw dictionary by hand. The type carries the PDF-correct details for you. A checkbox, a radio button, and a push button all share the same underlying form type in the spec and are told apart by their flags; the engine sets those flags from the type you chose, rather than asking you to remember which bit means “radio”. A list box and a combo box are both choice fields; again, the builder picks the right encoding. You state the field type once, in words, and the bytes follow.

Flattening is the second half. The flattener groups widget annotations by their owning page, using each widget’s rectangle for placement on that page, then renders each value as a small run of content-stream operators — set a colour, set a text position, draw the glyphs — appended to that page’s existing content (SpecSpec: ISO 32000-2, §8.4ISO 32000-2 §8.4). The value stops being a live field and becomes painted ink. Because the form no longer carries any interactive fields, the engine then removes the AcroForm entry: there is nothing left to be interactive about.

1. Declare typed fieldsAdd text, checkbox, radio, choice, and button fields through their typed builders; the engine sets the spec-correct PDF type and flags.
2. Place the widgetsEach field is drawn as a widget annotation — a rectangle on a chosen page that a viewer can type into, tick, or pick from.
3. Collect inputShip it fillable: a reader supplies values, or your code sets them, leaving a filled but still-editable document.
4. Flatten the valuesRender each field's value into the page content stream as graphics; the painted value is now immutable.
5. Drop the interactive formWith every value baked in, remove the AcroForm so nothing remains editable — a frozen record of what was agreed.

From a fillable form to a frozen record: declare typed fields, draw their on-page widgets, fill in values, then flatten those values into immutable page graphics and drop the now-empty interactive form.

Practical example

A small, representative form: build a few typed fields, then flatten it into a frozen record.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();

// Typed builders, called straight on the document. You pick the field
// type by choosing its builder method — textField, checkBox, comboBox —
// and you pass the value to freeze at creation time. The engine writes
// the spec-correct PDF type and flags for you.
$document->textField('full_name', x: 40, y: 700, w: 220, h: 18, default: 'Ada Lovelace');
$document->checkBox('agree_terms', x: 40, y: 660, size: 14, checked: true);
$document->comboBox(
    'plan',
    x: 40,
    y: 620,
    w: 160,
    h: 18,
    items: ['Starter', 'Team', 'Enterprise'],
    selected: 'Team',
);

// Flatten: the values become immutable page graphics and the
// interactive AcroForm is dropped. The result is a frozen record.
$document->flattenForms();

$bytes = $document->getPdfData();

Before flattenForms(), this is a fillable form. After it, the same values are painted into the page and there is no field left to change. You pick the field type by choosing its builder method — textField, checkBox, comboBox — so a wrong type cannot be encoded as a loose string: a typo is a call to a method that does not exist, caught before any field is written, not a silently wrong field. That is the same refuse-to-guess stance the rest of the engine takes; see an API that refuses to guess.

Common misconception

The trap is believing that filling a field freezes it. It does not. A filled field still carries a live value that a capable viewer can edit, and an appearance some viewers will regenerate. “I set the value” and “the document is now a fixed record” are two different states. Only flattening crosses from one to the other, because only flattening turns the value into page graphics that no longer behave like a field.

The mirror-image mistake is flattening a draft you still need to collect input on. Once flattened, the fields are gone — that is the whole point — so flatten the copy you intend to be final, not the one you are still circulating.

Human-factors note:Human-factors note

There is one operability nuance worth knowing. If you ask the engine to flatten a document that has no pages, it does not silently bin your field values. There is no page surface to paint them onto, so instead of stripping the interactive form and nulling its values — a total, invisible data loss — NextPDF preserves the form, keeps every value intact and still interactive, and surfaces a warning telling you what happened. You add a page and flatten again. This is a deliberate no-data-loss design: the engine would rather hand back a still-fillable document and a clear warning than a quietly emptied one. The values you were trusted with are the one thing a flatten must never throw away.

Limits and boundaries

NextPDF’s form support is full core: typed builders for the common interactive field controls, a form flattener, and a field manager that writes the fields as proper PDF objects. This page describes that core surface.

AcroForm fields and flattening — edition availability

Edition	Availability
Core	○ Typed builders for text, checkbox, radio, choice (list box and combo box), and push-button fields; widget placement; a field manager; and a form flattener that bakes values into page graphics. Available in every edition.
Pro	○Not in this edition
Enterprise	○Not in this edition

Flattening is one-way by design. It removes the interactive form so the record is fixed; it is not a “lock temporarily” toggle, and there is no un-flatten that re-derives editable fields from painted graphics. If you need a copy people can keep editing, keep the unflattened form and flatten a duplicate.

Flattening also is not a signature. It makes a document non-editable in the ordinary-viewer sense, but it does not cryptographically prove who produced it or that it has not changed since. When the record must be provably the one that was agreed, flatten and then sign; see how signatures sit in a PDF.

Finally, a tagged, accessible form is a separate concern from a flattened one. If the fillable version must be usable with assistive technology, the fields need accessible names and structure while they are still interactive; see what makes a PDF accessible.

Related docs

• What makes a PDF accessible — tagged form fields and accessible names, for the fillable stage.
• An API that refuses to guess — why the field type is a typed enum, not a string the engine has to interpret.
• The anatomy of a PDF file — where the catalogue, pages, and annotations a form is built from actually live.
• How signatures sit in a PDF — how to make a frozen record provably the one that was agreed.

Glossary

• AcroForm — a PDF’s interactive form: the tree of typed fields declared in the document catalogue that makes the file fillable (SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7).
• Field — the data side of a form control: a name, a type, a value, and flags. Independent of how it looks on the page.
• Widget annotation — the visible, clickable rectangle on a page through which a viewer interacts with a field (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5). One field may have several.
• Choice field — a field offering a set of options: a list box shows them open, a combo box shows a drop-down. Both are the same PDF field type.
• Flatten — to render each field’s current value into the page as immutable graphics and remove the interactive form, producing a frozen record.
• Frozen record — a flattened document: it shows one fixed thing in every viewer and has no fields left to edit.