Forms are a core part of Drupal. Almost everything interactive in the admin UI and many frontend features are built using the Form API (FAPI).
Understanding the Form API is not about memorizing syntax. It is about understanding how Drupal builds, validates, submits, and renders forms in a structured and secure way.
This article explains the Form API at a high level, from concepts to the main base classes used in real projects.
What Is the Drupal Form API
The Form API is Drupal’s framework for:
- Building forms
- Handling user input
- Validating data
- Submitting data securely
- Rendering HTML output
Instead of writing raw HTML forms, Drupal uses PHP arrays to describe forms. These arrays are processed, rendered, validated, and secured by the system.
This approach provides:
- Automatic CSRF protection
- Consistent validation
- Extensibility
- Theme-level control
Forms as Structured Arrays
In Drupal, a form is defined as a render array.
Each form element is an array with:
- A type
- Properties
- Optional callbacks
Example element types include:
- textfield
- textarea
- select
- checkbox
- radios
- submit
Drupal processes these arrays through multiple stages before rendering HTML.
The Form Lifecycle
Every Drupal form follows the same lifecycle:
- Build – The form structure is defined
- Validate – User input is checked
- Submit – Data is processed or saved
- Render – Output is themed and displayed
Understanding this lifecycle is key to debugging and extending forms.
FormBase: The Core Starting Point
Most custom forms extend FormBase.
FormBase provides the minimum structure required to define a form.
Required methods:
- getFormId()
- buildForm()
Optional but commonly used:
- validateForm()
- submitForm()
Use FormBase when:
- The form does not store configuration
- The form performs actions or processing
- Data is handled manually
Examples:
- Custom tools
- Search forms
- Action forms
ConfigFormBase: Forms That Manage Configuration
ConfigFormBase is used when a form edits Drupal configuration.
It extends FormBase and adds configuration-specific handling.
Required methods:
- getFormId()
- buildForm()
- submitForm()
- getEditableConfigNames()
Key behavior:
- Automatically loads config
- Saves config on submit
- Integrates with config management
Use ConfigFormBase when:
- Building admin settings pages
- Managing site-wide behavior
- Editing deployable configuration
ConfirmFormBase: Confirmation Workflows
ConfirmFormBase is used for confirmation dialogs.
Typical use cases:
- Delete actions
- Destructive operations
- Confirmation steps
Required methods include:
- getFormId()
- getQuestion()
- getConfirmText()
- getCancelText()
- getCancelUrl()
- submitForm()
This ensures a consistent and accessible confirmation UX.
Validation Methods
Validation ensures data integrity before submission.
Validation can happen at:
- Field level
- Form level
nvalidateForm() allows: - Checking required values
- Validating formats
- Enforcing business rules
Errors are attached to specific form elements, not the page.
Submit Methods
Submit handlers process valid form data.
Typical responsibilities:
- Saving data
- Calling services
- Redirecting users
- Triggering side effects
Form state is accessed through the form state object.
Form State
The FormStateInterface stores:
- Submitted values
- Temporary data
- Validation errors
- Redirect information
It acts as the bridge between build, validate, and submit phases.
Render API and Theming
Forms are rendered using the Render API.
Key ideas:
- Forms are render arrays
- Elements can be altered
- Theming happens late
- Twig controls output
This allows:
- Theme overrides
- Consistent markup
- Accessibility support
Why This Is a Foundation Topic
Form API is foundational because:
- Admin UI is built on it
- Security depends on it
- Configuration depends on it
- User interaction depends on it
Understanding FAPI early prevents fragile custom code later.
Foundation Best Practices
- Always use Form API, not raw HTML
- Choose the correct base class
- Separate build, validate, and submit logic
- Avoid business logic in buildForm()
- Use services for processing
What Comes Next
After understanding the Form API, natural next topics are:
- Form alters
- AJAX in forms
- Validation handlers
- Entity forms
- Custom form elements
These build directly on this foundation.