Laminas Forms

When to use

• The user wants to hydrate a form from an entity and bind validated data back onto the object.
• The user needs to build a laminas-form with elements, or compose reusable fieldsets, to render and capture user input.
• The user wants to validate and filter submitted request data against rules before using it, using an input filter.

When NOT to use

• Do not reach for the full Form object when a JSON API only needs to validate a payload; a standalone input filter is lighter and sufficient.
• Do not use this skill for Symfony Form, Laravel form requests, or client-side-only form markup; the Form/Fieldset/InputFilter API is Laminas specific.

Core guidance

• Read getData only after isValid returns true — Call setData($request->getPost()) then isValid(), and only read getData() (filtered, validated values) once isValid() has returned true.
• Keep validation in an input filter, not in the elements — Define validators and filters in an InputFilter (via getInputFilterSpecification() on the fieldset or a dedicated input-filter class), not ad hoc in the controller after submission.

Quick recipe

1. Extend Laminas\Form\Form, add each element in init() with its name and type, and include a Csrf element for state-changing forms. (verify: The form renders every declared element plus the CSRF token)
2. Implement getInputFilterSpecification() returning per-field required, filters, and validators entries so submitted data is filtered and checked. (verify: Invalid submissions fail isValid() with per-field messages)
3. In the controller, bind the entity, call setData($request->getPost()), and on isValid() read getData(); on failure, re-render the form with its messages. (verify: Valid input updates the entity; invalid input re-renders with errors and no 500)

Best practices

• Include a Csrf element on any form that mutates state so submission fails validation unless the request carries a valid, unexpired token
• Model a cohesive group of fields (an address, a contact) as a Fieldset and compose it into forms, rather than repeating the same elements in each form
• Set a hydrator on the fieldset and call $form->bind($entity) before validation so that, on success, filtered values are written straight onto the domain object

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Csrf validation fails after the token TTL or a new session — A Csrf element rejects a submission when its token has expired (default short TTL) or the session was regenerated between render and submit. Fix: Tune the Csrf element timeout, re-render the form (with a fresh token) on failure, and preserve the session across the render-submit cycle.
2. Reading getData before isValid runs the filter — Calling getData() before isValid() returns unfiltered, unvalidated values (or throws in strict mode). Fix: Always order the calls as setData -> isValid -> getData, and branch on the boolean result.
3. Required-by-default inputs reject legitimately empty fields — An input is required by default, so an optional field with no value fails validation until you mark it required false with allow_empty true. Fix: In the input filter spec, set required to false and allow_empty to true for genuinely optional inputs.

Version notes

• laminas-form 3 adds elements in init, not the constructor — In laminas-form 3, build form elements inside init() (called by the form element manager after construction) so factory-created forms have their dependencies ready, rather than adding elements in __construct().

Security

• Treat form input as untrusted until isValid passes — Feed the raw request into the form with setData(), run isValid(), and consume only getData() afterwards; never trust $request->getPost() values directly, and attach a Csrf element plus escaping in the view layer.

Testing

• Activation and decision behavior are verified in eval/scenarios/laminas/forms.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: laminas/mvc, php/typed-properties