Builds and processes a form for a given form ID.
The form may also be retrieved from the cache if the form was built in a previous page-load. The form is then passed on for processing, validation and submission if there is proper input.
$form_id: The unique string identifying the desired form. If a function with that name exists, it is called to build the form array. Modules that need to generate the same form (or very similar forms) using different $form_ids can implement hook_forms(), which maps different $form_id values to the proper form constructor function. Examples may be found in node_forms(), and search_forms().
$form_state: An array which stores information about the form. This is passed as a reference so that the caller can use it to examine what in the form changed when the form submission process is complete. Furthermore, it may be used to store information related to the processed data in the form, which will persist across page requests when the 'cache' or 'rebuild' flag is set. The following parameters may be set in $form_state to affect how the form is rendered:
Information on how certain $form_state properties control redirection behavior after form submission may be found in drupal_redirect_form().
The rendered form. This function may also perform a redirect and hence may not return at all, depending upon the $form_state flags that were set.
function drupal_build_form($form_id, &$form_state) {
// Ensure some defaults; if already set they will not be overridden.
$form_state += form_state_defaults();
if (!isset($form_state['input'])) {
$form_state['input'] = $form_state['method'] == 'get' ? $_GET : $_POST;
}
if (isset($_SESSION['batch_form_state'])) {
// We've been redirected here after a batch processing. The form has
// already been processed, but needs to be rebuilt. See _batch_finished().
$form_state = $_SESSION['batch_form_state'];
unset($_SESSION['batch_form_state']);
return drupal_rebuild_form($form_id, $form_state);
}
// If the incoming input contains a form_build_id, we'll check the cache for a
// copy of the form in question. If it's there, we don't have to rebuild the
// form to proceed. In addition, if there is stored form_state data from a
// previous step, we'll retrieve it so it can be passed on to the form
// processing code.
$check_cache = isset($form_state['input']['form_id']) && $form_state['input']['form_id'] == $form_id && !empty($form_state['input']['form_build_id']);
if ($check_cache) {
$form = form_get_cache($form_state['input']['form_build_id'], $form_state);
}
// If the previous bit of code didn't result in a populated $form object, we
// are hitting the form for the first time and we need to build it from
// scratch.
if (!isset($form)) {
// If we attempted to serve the form from cache, uncacheable $form_state
// keys need to be removed after retrieving and preparing the form, except
// any that were already set prior to retrieving the form.
if ($check_cache) {
$form_state_before_retrieval = $form_state;
}
$form = drupal_retrieve_form($form_id, $form_state);
drupal_prepare_form($form_id, $form, $form_state);
// form_set_cache() removes uncacheable $form_state keys defined in
// form_state_keys_no_cache() in order for multi-step forms to work
// properly. This means that form processing logic for single-step forms
// using $form_state['cache'] may depend on data stored in those keys
// during drupal_retrieve_form()/drupal_prepare_form(), but form
// processing should not depend on whether the form is cached or not, so
// $form_state is adjusted to match what it would be after a
// form_set_cache()/form_get_cache() sequence. These exceptions are
// allowed to survive here:
// - always_process: Does not make sense in conjunction with form caching
// in the first place, since passing form_build_id as a GET parameter is
// not desired.
// - temporary: Any assigned data is expected to survives within the same
// page request.
if ($check_cache) {
$uncacheable_keys = array_flip(array_diff(form_state_keys_no_cache(), array(
'always_process',
'temporary',
)));
$form_state = array_diff_key($form_state, $uncacheable_keys);
$form_state += $form_state_before_retrieval;
}
}
// Now that we have a constructed form, process it. This is where:
// - Element #process functions get called to further refine $form.
// - User input, if any, gets incorporated in the #value property of the
// corresponding elements and into $form_state['values'].
// - Validation and submission handlers are called.
// - If this submission is part of a multistep workflow, the form is rebuilt
// to contain the information of the next step.
// - If necessary, the form and form state are cached or re-cached, so that
// appropriate information persists to the next page request.
// All of the handlers in the pipeline receive $form_state by reference and
// can use it to know or update information about the state of the form.
drupal_process_form($form_id, $form, $form_state);
// If this was a successful submission of a single-step form or the last step
// of a multi-step form, then drupal_process_form() issued a redirect to
// another page, or back to this page, but as a new request. Therefore, if
// we're here, it means that this is either a form being viewed initially
// before any user input, or there was a validation error requiring the form
// to be re-displayed, or we're in a multi-step workflow and need to display
// the form's next step. In any case, we have what we need in $form, and can
// return it for rendering.
return $form;
}