Form API Workflow

Introduction

The complete Form API workflow is complex and has many different cases. That's why we'll start small.

When Drupal serves a page that includes a form, first the form is created according the build function of the form. Once the user submits the form, Drupal builds again the form on the submit request. This is because Drupal needs to check the submitted form and values match the actual form.

Then, the form it is validated. If validation is correct form submission is processed. If validation fails, the form is sent back to the user with the errors detected. From this, the cycle repeats: user submits the form and either is returned with errors or is accepted and processed.

What about dynamic forms? During validation or submission/form processing Drupal can decide to rebuild the form. This happens, for example, when user clicks on a button that adds a new element to a field. Let's forget about AJAX for now. When rebuild is enabled, Drupal goes back to the build function to rebuild the form, often modifying first some value so the build function builds the new version of the form with the desired change.

For example, when user clicks on the button to add a new element to a field, Drupal first builds the form, validates it, enables rebuild and sets the $form_state so it reflects that there should one more element. Then, the rebuild process starts calling the form's build function. The build function, when adding elements for that field, will add a new element as $form_state says. Once the form is rebuilt, it is send to the user.

Example of a form being rebuilt to add new items.

This rebuilding loop allows forms to be dynamic. Because the rebuilding is done in the Drupal side, in the backend, Drupal still keeps track of the form elements. This way, Drupal is able to check that the form submission sent by the user matches the form Drupal is expecting.

The four stages of a form

The form traverses four stages during its life cycle. Depending on what is happening (the form is being built for the first time, the user submitted the form, the request is an AJAX request, etc), the workflow through the stages is different. 

The four stages are:

• The retrieve and preparation stage: the form is built using the form's build function and all the alter form hooks are called. The output of this stage is a Form API array, an array with all the elements the form should have, but not the final render array.
• Recursive building stage: a recursive process traversing the $form array calling auxiliary functions like #process and #after_build callbacks. The goal is to obtain a Drupal render array with the final shape of the form, with all the required elements. 
• Validation stage: if the form has been submitted, the validation stage runs all the requires validations to make sure the submission is valid.
• The submit stage: if form has been submitted and the validation is correct the right submit is run.

The rebuild form action

The form rebuild can be enabled during validation or submit stages. After enabling the form rebuilding, the form goes again trough the two first stages: retrieve and preparation, and recursive building. After this, the form is returned to the user via standard response or via an AJAX callback function.

As said above, this allows to manage complex and dynamic forms.

Complete workflow diagram

Here is a detailed Form API workflow diagram with all the stages and many other details, including the workflow for AJAX requests and the points where the form can be altered (hooks and callbacks).

Although it is very complete there are several things that are not in the diagram. Use this diagram to better understand the Form API, specially when dealing with complex forms.

See the full resolution image.