When using the Drupal 7 Form API, the
$form_state variable is used in both the submit and validate function.
It is an associative array with the following values
An associative array of values that have been submitted to the form. The validation and submit functions use this array for nearly all their decision making.
(Note that #tree determines whether the values are a flat array or an array whose structure parallels the $form array.)
If the submit handler sets
$form_state['rebuild'] to TRUE, submission is not completed and instead the form is rebuilt using any information that the submit function has made available to the form builder function via
$form_state. This is commonly used for wizard-style multi-step forms, add-more buttons, and the like. For further information see
If you are building a result based off posted values, then you need to set this to true to stop the form from reloading (its default behaviour) and resetting its values.
$form_state['rebuild'] = TRUE;
A URL that will be used to redirect the form on submission. See
drupal_redirect_form() for complete information. This should always be used instead of
drupal_goto() in a forms context.
Note that $form[‘#redirect’] went away in Drupal 7 and no longer has any effect.
$form_state['storage'] is no more! It used to be the place for application-specific values, but now it has no specific meaning. Now nearly all
$form_state keys persist in a multi-step form, so the recommended approach is to use
$form_state['storage'] still works for persistent storage, just like
The form element that triggered submission. This is the same as the deprecated
$form_state['clicked_button']. It is the element that caused submission, which may or may not be a button (in the case of AJAX forms.) This is often used to distinguish between various buttons in a submit handler, and is also used in AJAX handlers.
The typical form workflow involves two page requests. During the first page request, a form is built and returned for the user to fill in. Then the user fills the form in and submits it, triggering a second page request in which the form must be built and processed. By default, $form and
$form_state are built from scratch during each of these page requests. In some special use-cases, it is necessary or desired to persist the $form and
$form_state variables from the initial page request to the one that processes the submission. A form builder function can set ‘cache’ to TRUE to do this. One example where this is needed is to handle AJAX submissions, so
ajax_process_form() sets this for all forms that include an element with a
#ajax property. (In AJAX, the handler has no way to build the form itself, so must rely on the cached version created on each page load, so it’s a classic example of this use case.) Note that the persistence of $form and
$form_state across successive submissions of a multi-step form happens automatically regardless of the value for ‘cache’. You probably won’t need to use
$form_state['cache']. And note that $form[‘#cache’] is gone in D7 and now has no effect on anything.
The array of values as they were submitted by the user. These are raw and unvalidated, so should not be used without a thorough understanding of security implications. In almost all cases, code should use the data in the ‘values’ array exclusively. The most common use of this key is for multi-step forms that need to clear some of the user input when setting ‘rebuild’.