Introduction to Form API

A form in Drupal is managed by a class that implements the \Drupal\Core\Form\FormInterface. The basic workflow of a form is defined by the buildForm, validateForm, and submitForm methods of the interface. When a form is requested it's defined as a renderable array often referred to as a Form API array or simply $form array. The $form array is converted to HTML by the render process and displayed to the end user. When a user submits a form the request is made to the same URL that the form was displayed on, Drupal notices the incoming HTTP POST data in the request and this time–instead of building the form and displaying it as HTML–it builds the form and then proceeds to call the applicable validation and submission handlers.

Defining forms as structured arrays, instead of as straight HTML, has many advantages including:

There are several types of forms commonly used in Drupal. Each has a base class which you can extend in your own custom module.

First, identify the type of form you need to build:

FormBase implements FormInterface, and both ConfigFormBase and ConfirmFormBase extend FormBase, therefore any forms that extend these classes must implement a few required methods.

FormBase implements FormInterface, and therefore any form that has FormBase in its hierarchy is required to implement a few methods:

public function getFormId()

This needs to return a string that is the unique ID of your form. Namespace the form ID based on your module's name.

Example:

public function buildForm(array $form, FormStateInterface $form_state)

This returns a Form API array that defines each of the elements your form is composed of.

Example:

Note that the buildForm method needs to hold the logic needed to build dynamic forms. The previous example is just a simple form that always has the same elements, but a dynamic form like a node form will most likely have different elements depending on the data of the node. The buildForm method will add the required form elements depending on the node data. This applies to regular forms and AJAX forms.

After a user fills out the form and clicks the submit button it's common to want to perform some sort of validation on the data that's being collected. To do this with Drupal's Form API we simply implement the validateForm method from \Drupal\Core\Form\FormInterface in our ExampleForm class.

Form values submitted by the user are contained in the $form_state object at $form_state->getValue('field_id'), where 'field_id' is the key used when adding the form element to the $form array in ExampleForm::buildForm(). We can perform our custom validation on this value. If you need to get all submitted values, you can do so by using $form_state->getValues().

Form validation methods can use any PHP processing necessary to validate that the field contains the desired value and raise an error in the event that it is an invalid value. In this case since we're extending the \Drupal\Core\Form\FormBase class we can use \Drupal\Core\Form\FormStateInterface::setErrorByName() to register an error on a specific form element and provide an associated message explaining the error.

When a form is submitted, Drupal runs through all validation handlers for the form, both the default validation handlers and any validation handlers added by developers. If there are errors, the form's HTML is rebuilt, error messages are shown, and fields with errors are highlighted. This allows the user to correct any errors and re-submit the form. If no errors are present, the submit handlers for the form are executed.

The following is an example of a simple validateForm() method:

If no errors are registered during form validation, Drupal continues processing the form. At this point it is assumed that values within $form_state->getValues() are valid and ready to be processed and used in whatever way our module needs to make use of the data.

Finally, we're ready to make use of the collected data and do things, like save the data to the database, send an email, or any number of other operations. To do this with Drupal's Form API we need to implement the submitForm method from \Drupal\Core\Form\FormInterface in our ExampleForm class.

As with the validation method above, the values collected when the form was submitted are in $form_state->getValues() and at this point we can assume the data have been validated and are ready for use. For example, accessing the value of our 'phone_number' field can be done by accessing $form_state->getValue('phone_number').

Here's an example of a simple submitForm method which displays the value of the 'phone_number' field on the page using the messenger service:

This is a simple example of handling submitted form data. For more complex examples, take a look at some of the classes that extend FormBase in core.

Here is a complete example of a form class:

File contents of /modules/example/src/Form/ExampleForm.php if the module is in /modules/example: