form.inc 194 KB
Newer Older
1
<?php
2

3 4 5 6 7
/**
 * @file
 * Functions for form and batch generation and processing.
 */

8
/**
9 10 11 12 13 14
 * @defgroup forms Form builder functions
 * @{
 * Functions that build an abstract representation of a HTML form.
 *
 * All modules should declare their form builder functions to be in this
 * group and each builder function should reference its validate and submit
15
 * functions using \@see. Conversely, validate and submit functions should
16
 * reference the form builder function using \@see. For examples, of this see
17
 * system_modules_uninstall() or user_pass(), the latter of which has the
18 19 20 21 22 23
 * following in its doxygen documentation:
 *
 * \@ingroup forms
 * \@see user_pass_validate().
 * \@see user_pass_submit().
 *
24
 * @} End of "defgroup forms".
25 26 27 28
 */

/**
 * @defgroup form_api Form generation
29
 * @{
30
 * Functions to enable the processing and display of HTML forms.
31
 *
32 33 34 35
 * Drupal uses these functions to achieve consistency in its form processing and
 * presentation, while simplifying code and reducing the amount of HTML that
 * must be explicitly generated by modules.
 *
36 37 38 39
 * The primary function used with forms is drupal_get_form(), which is
 * used for forms presented interactively to a user. Forms can also be built and
 * submitted programmatically without any user input using the
 * drupal_form_submit() function.
40
 *
41 42 43 44 45
 * drupal_get_form() handles retrieving, processing, and displaying a rendered
 * HTML form for modules automatically.
 *
 * Here is an example of how to use drupal_get_form() and a form builder
 * function:
46
 * @code
47 48 49 50 51 52 53
 * $form = drupal_get_form('my_module_example_form');
 * ...
 * function my_module_example_form($form, &$form_state) {
 *   $form['submit'] = array(
 *     '#type' => 'submit',
 *     '#value' => t('Submit'),
 *   );
54
 *   return $form;
55 56 57 58 59 60 61
 * }
 * function my_module_example_form_validate($form, &$form_state) {
 *   // Validation logic.
 * }
 * function my_module_example_form_submit($form, &$form_state) {
 *   // Submission logic.
 * }
62
 * @endcode
63
 *
64 65 66 67 68 69 70 71 72 73
 * Or with any number of additional arguments:
 * @code
 * $extra = "extra";
 * $form = drupal_get_form('my_module_example_form', $extra);
 * ...
 * function my_module_example_form($form, &$form_state, $extra) {
 *   $form['submit'] = array(
 *     '#type' => 'submit',
 *     '#value' => $extra,
 *   );
74
 *   return $form;
75 76
 * }
 * @endcode
77
 *
78 79 80 81 82 83
 * The $form argument to form-related functions is a structured array containing
 * the elements and properties of the form. For information on the array
 * components and format, and more detailed explanations of the Form API
 * workflow, see the
 * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API reference @endlink
 * and the
84
 * @link http://drupal.org/node/37775 Form API documentation section. @endlink
85 86 87 88 89 90 91 92 93
 * In addition, there is a set of Form API tutorials in
 * @link form_example_tutorial.inc the Form Example Tutorial @endlink which
 * provide basics all the way up through multistep forms.
 *
 * In the form builder, validation, submission, and other form functions,
 * $form_state is the primary influence on the processing of the form and is
 * passed by reference to most functions, so they use it to communicate with
 * the form system and each other.
 *
94
 * See drupal_build_form() for documentation of $form_state keys.
95 96 97
 */

/**
98 99 100 101 102
 * Returns a renderable form array for a given form ID.
 *
 * This function should be used instead of drupal_build_form() when $form_state
 * is not needed (i.e., when initially rendering the form) and is often
 * used as a menu callback.
103 104
 *
 * @param $form_id
105 106 107 108 109
 *   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(),
110
 *   and search_forms().
111
 * @param ...
112
 *   Any additional arguments are passed on to the functions called by
113 114
 *   drupal_get_form(), including the unique form constructor function. For
 *   example, the node_edit form requires that a node object is passed in here
115
 *   when it is called. These are available to implementations of
116 117
 *   hook_form_alter() and hook_form_FORM_ID_alter() as the array
 *   $form_state['build_info']['args'].
118
 *
119
 * @return
120
 *   The form array.
121 122
 *
 * @see drupal_build_form()
123 124
 */
function drupal_get_form($form_id) {
125
  $form_state = array();
126 127

  $args = func_get_args();
128 129
  // Remove $form_id from the arguments.
  array_shift($args);
130
  $form_state['build_info']['args'] = $args;
131 132 133 134 135

  return drupal_build_form($form_id, $form_state);
}

/**
136
 * Builds and processes a form for a given form ID.
137 138 139
 *
 * 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
140
 * and submission if there is proper input.
141 142 143 144 145 146 147
 *
 * @param $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(),
148
 *   and search_forms().
149
 * @param $form_state
150
 *   An array which stores information about the form. This is passed as a
151
 *   reference so that the caller can use it to examine what in the form changed
152 153 154
 *   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.
155 156
 *   The following parameters may be set in $form_state to affect how the form
 *   is rendered:
157 158 159 160
 *   - build_info: Internal. An associative array of information stored by Form
 *     API that is necessary to build and rebuild the form from cache when the
 *     original context may no longer be available:
 *     - args: A list of arguments to pass to the form constructor.
161 162 163 164
 *     - files: An optional array defining include files that need to be loaded
 *       for building the form. Each array entry may be the path to a file or
 *       another array containing values for the parameters 'type', 'module' and
 *       'name' as needed by module_load_include(). The files listed here are
165
 *       automatically loaded by form_get_cache(). By default the current menu
166 167
 *       router item's 'file' definition is added, if any. Use
 *       form_load_include() to add include files from a form constructor.
168 169
 *     - base_form_id: Identification for a base form, as declared in a
 *       hook_forms() implementation.
170 171
 *   - rebuild_info: Internal. Similar to 'build_info', but pertaining to
 *     drupal_rebuild_form().
172
 *   - rebuild: Normally, after the entire form processing is completed and
173
 *     submit handlers have run, a form is considered to be done and
174 175 176
 *     drupal_redirect_form() will redirect the user to a new page using a GET
 *     request (so a browser refresh does not re-submit the form). However, if
 *     'rebuild' has been set to TRUE, then a new copy of the form is
177
 *     immediately built and sent to the browser, instead of a redirect. This is
178 179 180 181 182 183 184
 *     used for multi-step forms, such as wizards and confirmation forms.
 *     Normally, $form_state['rebuild'] is set by a submit handler, since it is
 *     usually logic within a submit handler that determines whether a form is
 *     done or requires another step. However, a validation handler may already
 *     set $form_state['rebuild'] to cause the form processing to bypass submit
 *     handlers and rebuild the form instead, even if there are no validation
 *     errors.
185 186 187 188 189 190
 *   - redirect: Used to redirect the form on submission. It may either be a
 *     string containing the destination URL, or an array of arguments
 *     compatible with drupal_goto(). See drupal_redirect_form() for complete
 *     information.
 *   - no_redirect: If set to TRUE the form will NOT perform a drupal_goto(),
 *     even if 'redirect' is set.
191 192 193 194
 *   - method: The HTTP form method to use for finding the input for this form.
 *     May be 'post' or 'get'. Defaults to 'post'. Note that 'get' method
 *     forms do not use form ids so are always considered to be submitted, which
 *     can have unexpected effects. The 'get' method should only be used on
195 196
 *     forms that do not change data, as that is exclusively the domain of
 *     'post.'
197
 *   - cache: If set to TRUE the original, unprocessed form structure will be
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
 *     cached, which allows the entire form to be rebuilt from cache. A typical
 *     form workflow involves two page requests; first, a form is built and
 *     rendered 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. Often, 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. 'cache' can be set
 *     to TRUE to do this. A prominent example is an Ajax-enabled form, in which
 *     ajax_process_form() enables form caching for all forms that include an
 *     element with the #ajax property. (The Ajax handler has no way to build
 *     the form itself, so must rely on the cached version.) Note that the
 *     persistence of $form and $form_state happens automatically for
 *     (multi-step) forms having the 'rebuild' flag set, regardless of the value
 *     for 'cache'.
213 214
 *   - no_cache: If set to TRUE the form will NOT be cached, even if 'cache' is
 *     set.
215 216 217 218
 *   - values: An associative array of values submitted to the form. The
 *     validation functions and submit functions use this array for nearly all
 *     their decision making. (Note that
 *     @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7#tree #tree @endlink
219 220
 *     determines whether the values are a flat array or an array whose
 *     structure parallels the $form array.)
221 222 223 224 225 226 227
 *   - input: 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'. The values correspond to $_POST or $_GET,
 *     depending on the 'method' chosen.
228 229 230 231 232
 *   - always_process: If TRUE and the method is GET, a form_id is not
 *     necessary. This should only be used on RESTful GET forms that do NOT
 *     write data, as this could lead to security issues. It is useful so that
 *     searches do not need to have a form_id in their query arguments to
 *     trigger the search.
233
 *   - must_validate: Ordinarily, a form is only validated once, but there are
234 235
 *     times when a form is resubmitted internally and should be validated
 *     again. Setting this to TRUE will force that to happen. This is most
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275
 *     likely to occur during Ajax operations.
 *   - programmed: If TRUE, the form was submitted programmatically, usually
 *     invoked via drupal_form_submit(). Defaults to FALSE.
 *   - process_input: Boolean flag. TRUE signifies correct form submission.
 *     This is always TRUE for programmed forms coming from drupal_form_submit()
 *     (see 'programmed' key), or if the form_id coming from the $_POST data is
 *     set and matches the current form_id.
 *   - submitted: If TRUE, the form has been submitted. Defaults to FALSE.
 *   - executed: If TRUE, the form was submitted and has been processed and
 *     executed. Defaults to FALSE.
 *   - triggering_element: (read-only) 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 key is
 *     often used to distinguish between various buttons in a submit handler,
 *     and is also used in Ajax handlers.
 *   - has_file_element: Internal. If TRUE, there is a file element and Form API
 *     will set the appropriate 'enctype' HTML attribute on the form.
 *   - groups: Internal. An array containing references to fieldsets to render
 *     them within vertical tabs.
 *   - storage: $form_state['storage'] is not a special key, and no specific
 *     support is provided for it in the Form API. By tradition it was
 *     the location where application-specific data was stored for communication
 *     between the submit, validation, and form builder functions, especially
 *     in a multi-step-style form. Form implementations may use any key(s)
 *     within $form_state (other than the keys listed here and other reserved
 *     ones used by Form API internals) for this kind of storage. The
 *     recommended way to ensure that the chosen key doesn't conflict with ones
 *     used by the Form API or other modules is to use the module name as the
 *     key name or a prefix for the key name. For example, the Node module uses
 *     $form_state['node'] in node editing forms to store information about the
 *     node being edited, and this information stays available across successive
 *     clicks of the "Preview" button as well as when the "Save" button is
 *     finally clicked.
 *   - buttons: A list containing copies of all submit and button elements in
 *     the form.
 *   - complete_form: A reference to the $form variable containing the complete
 *     form structure. #process, #after_build, #element_validate, and other
 *     handlers being invoked on a form element may use this reference to access
 *     other information in the form the element is contained in.
276
 *   - temporary: An array holding temporary data accessible during the current
277 278 279 280 281 282 283 284
 *     page request only. All $form_state properties that are not reserved keys
 *     (see form_state_keys_no_cache()) persist throughout a multistep form
 *     sequence. Form API provides this key for modules to communicate
 *     information across form-related functions during a single page request.
 *     It may be used to temporarily save data that does not need to or should
 *     not be cached during the whole form workflow; e.g., data that needs to be
 *     accessed during the current form build process only. There is no use-case
 *     for this functionality in Drupal core.
285 286 287 288
 *   - wrapper_callback: Modules that wish to pre-populate certain forms with
 *     common elements, such as back/next/save buttons in multi-step form
 *     wizards, may define a form builder function name that returns a form
 *     structure, which is passed on to the actual form builder function.
289 290 291 292
 *     Such implementations may either define the 'wrapper_callback' via
 *     hook_forms() or have to invoke drupal_build_form() (instead of
 *     drupal_get_form()) on their own in a custom menu callback to prepare
 *     $form_state accordingly.
293 294
 *   Information on how certain $form_state properties control redirection
 *   behavior after form submission may be found in drupal_redirect_form().
295
 *
296
 * @return
297 298
 *   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.
299 300
 *
 * @see drupal_redirect_form()
301 302 303 304 305 306 307 308 309
 */
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;
  }

310
  if (isset($_SESSION['batch_form_state'])) {
311 312
    // We've been redirected here after a batch processing. The form has
    // already been processed, but needs to be rebuilt. See _batch_finished().
313 314
    $form_state = $_SESSION['batch_form_state'];
    unset($_SESSION['batch_form_state']);
315
    return drupal_rebuild_form($form_id, $form_state);
316
  }
317

318 319 320 321 322 323 324 325
  // 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);
326 327
  }

328 329 330 331 332 333 334 335 336
  // 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;
337
    }
338

339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359
    $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;
360
    }
361
  }
362

363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383
  // 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.
384
  return $form;
385
}
386

387
/**
388
 * Retrieves default values for the $form_state array.
389 390 391
 */
function form_state_defaults() {
  return array(
392
    'rebuild' => FALSE,
393
    'rebuild_info' => array(),
394
    'redirect' => NULL,
395 396 397 398 399 400
    // @todo 'args' is usually set, so no other default 'build_info' keys are
    //   appended via += form_state_defaults().
    'build_info' => array(
      'args' => array(),
      'files' => array(),
    ),
401
    'temporary' => array(),
402
    'submitted' => FALSE,
403
    'executed' => FALSE,
404
    'programmed' => FALSE,
405 406
    'cache'=> FALSE,
    'method' => 'post',
407
    'groups' => array(),
408
    'buttons' => array(),
409 410 411
  );
}

412
/**
413 414 415 416 417 418 419 420 421
 * Constructs a new $form from the information in $form_state.
 *
 * This is the key function for making multi-step forms advance from step to
 * step. It is called by drupal_process_form() when all user input processing,
 * including calling validation and submission handlers, for the request is
 * finished. If a validate or submit handler set $form_state['rebuild'] to TRUE,
 * and if other conditions don't preempt a rebuild from happening, then this
 * function is called to generate a new $form, the next step in the form
 * workflow, to be returned for rendering.
422
 *
423
 * Ajax form submissions are almost always multi-step workflows, so that is one
424
 * common use-case during which form rebuilding occurs. See ajax_form_callback()
425
 * for more information about creating Ajax-enabled forms.
426 427 428 429 430 431 432
 *
 * @param $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
433
 *   may be found in node_forms() and search_forms().
434
 * @param $form_state
435
 *   A keyed array containing the current state of the form.
436 437
 * @param $old_form
 *   (optional) A previously built $form. Used to retain the #build_id and
438
 *   #action properties in Ajax callbacks and similar partial form rebuilds. The
439 440 441 442 443
 *   only properties copied from $old_form are the ones which both exist in
 *   $old_form and for which $form_state['rebuild_info']['copy'][PROPERTY] is
 *   TRUE. If $old_form is not passed, the entire $form is rebuilt freshly.
 *   'rebuild_info' needs to be a separate top-level property next to
 *   'build_info', since the contained data must not be cached.
444
 *
445 446
 * @return
 *   The newly built form.
447 448 449
 *
 * @see drupal_process_form()
 * @see ajax_form_callback()
450
 */
451
function drupal_rebuild_form($form_id, &$form_state, $old_form = NULL) {
452
  $form = drupal_retrieve_form($form_id, $form_state);
453

454
  // If only parts of the form will be returned to the browser (e.g., Ajax or
455 456 457 458 459
  // RIA clients), re-use the old #build_id to not require client-side code to
  // manually update the hidden 'build_id' input element.
  // Otherwise, a new #build_id is generated, to not clobber the previous
  // build's data in the form cache; also allowing the user to go back to an
  // earlier build, make changes, and re-submit.
460 461 462 463 464 465 466
  // @see drupal_prepare_form()
  if (isset($old_form['#build_id']) && !empty($form_state['rebuild_info']['copy']['#build_id'])) {
    $form['#build_id'] = $old_form['#build_id'];
  }
  else {
    $form['#build_id'] = 'form-' . drupal_hash_base64(uniqid(mt_rand(), TRUE) . mt_rand());
  }
467

468
  // #action defaults to request_uri(), but in case of Ajax and other partial
469 470
  // rebuilds, the form is submitted to an alternate URL, and the original
  // #action needs to be retained.
471
  if (isset($old_form['#action']) && !empty($form_state['rebuild_info']['copy']['#action'])) {
472
    $form['#action'] = $old_form['#action'];
473
  }
474

475 476
  drupal_prepare_form($form_id, $form, $form_state);

477 478 479 480
  // Caching is normally done in drupal_process_form(), but what needs to be
  // cached is the $form structure before it passes through form_builder(),
  // so we need to do it here.
  // @todo For Drupal 8, find a way to avoid this code duplication.
481
  if (empty($form_state['no_cache'])) {
482
    form_set_cache($form['#build_id'], $form, $form_state);
483
  }
484

485 486
  // Clear out all group associations as these might be different when
  // re-rendering the form.
487 488
  $form_state['groups'] = array();

489 490
  // Return a fully built form that is ready for rendering.
  return form_builder($form_id, $form, $form_state);
491 492
}

493
/**
494
 * Fetches a form from the cache.
495 496
 */
function form_get_cache($form_build_id, &$form_state) {
497
  if ($cached = cache('form')->get('form_' . $form_build_id)) {
498
    $form = $cached->data;
499

500 501
    global $user;
    if ((isset($form['#cache_token']) && drupal_valid_token($form['#cache_token'])) || (!isset($form['#cache_token']) && !$user->uid)) {
502
      if ($cached = cache('form')->get('form_state_' . $form_build_id)) {
503
        // Re-populate $form_state for subsequent rebuilds.
504
        $form_state = $cached->data + $form_state;
505

506
        // If the original form is contained in include files, load the files.
507
        // @see form_load_include()
508 509 510 511 512 513 514 515 516
        $form_state['build_info'] += array('files' => array());
        foreach ($form_state['build_info']['files'] as $file) {
          if (is_array($file)) {
            $file += array('type' => 'inc', 'name' => $file['module']);
            module_load_include($file['type'], $file['module'], $file['name']);
          }
          elseif (file_exists($file)) {
            require_once DRUPAL_ROOT . '/' . $file;
          }
517
        }
518 519
      }
      return $form;
520 521 522 523 524
    }
  }
}

/**
525
 * Stores a form in the cache.
526 527
 */
function form_set_cache($form_build_id, $form, $form_state) {
528 529
  // 6 hours cache life time for forms should be plenty.
  $expire = 21600;
530 531 532 533 534 535

  // Cache form structure.
  if (isset($form)) {
    if ($GLOBALS['user']->uid) {
      $form['#cache_token'] = drupal_get_token();
    }
536
    cache('form')->set('form_' . $form_build_id, $form, REQUEST_TIME + $expire);
537
  }
538 539

  // Cache form state.
540
  if ($data = array_diff_key($form_state, array_flip(form_state_keys_no_cache()))) {
541
    cache('form')->set('form_state_' . $form_build_id, $data, REQUEST_TIME + $expire);
542 543 544
  }
}

545 546 547 548 549 550 551 552 553
/**
 * Returns an array of $form_state keys that shouldn't be cached.
 */
function form_state_keys_no_cache() {
  return array(
    // Public properties defined by form constructors and form handlers.
    'always_process',
    'must_validate',
    'rebuild',
554
    'rebuild_info',
555 556 557 558 559
    'redirect',
    'no_redirect',
    'temporary',
    // Internal properties defined by form processing.
    'buttons',
560
    'triggering_element',
561
    'clicked_button',
562
    'complete_form',
563 564 565 566 567
    'groups',
    'input',
    'method',
    'submit_handlers',
    'submitted',
568
    'executed',
569 570 571 572 573
    'validate_handlers',
    'values',
  );
}

574
/**
575
 * Ensures an include file is loaded loaded whenever the form is processed.
576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622
 *
 * Example:
 * @code
 *   // Load node.admin.inc from Node module.
 *   form_load_include($form_state, 'inc', 'node', 'node.admin');
 * @endcode
 *
 * Use this function instead of module_load_include() from inside a form
 * constructor or any form processing logic as it ensures that the include file
 * is loaded whenever the form is processed. In contrast to using
 * module_load_include() directly, form_load_include() makes sure the include
 * file is correctly loaded also if the form is cached.
 *
 * @param $form_state
 *   The current state of the form.
 * @param $type
 *   The include file's type (file extension).
 * @param $module
 *   The module to which the include file belongs.
 * @param $name
 *   (optional) The base file name (without the $type extension). If omitted,
 *   $module is used; i.e., resulting in "$module.$type" by default.
 *
 * @return
 *   The filepath of the loaded include file, or FALSE if the include file was
 *   not found or has been loaded already.
 *
 * @see module_load_include()
 */
function form_load_include(&$form_state, $type, $module, $name = NULL) {
  if (!isset($name)) {
    $name = $module;
  }
  if (!isset($form_state['build_info']['files']["$module:$name.$type"])) {
    // Only add successfully included files to the form state.
    if ($result = module_load_include($type, $module, $name)) {
      $form_state['build_info']['files']["$module:$name.$type"] = array(
        'type' => $type,
        'module' => $module,
        'name' => $name,
      );
      return $result;
    }
  }
  return FALSE;
}

623
/**
624 625 626 627 628 629 630 631
 * Retrieves, populates, and processes a form.
 *
 * This function allows you to supply values for form elements and submit a
 * form for processing. Compare to drupal_get_form(), which also builds and
 * processes a form, but does not allow you to supply values.
 *
 * There is no return value, but you can check to see if there are errors
 * by calling form_get_errors().
632 633 634 635 636 637
 *
 * @param $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
638
 *   different $form_id values to the proper form constructor function. Examples
639
 *   may be found in node_forms() and search_forms().
640
 * @param $form_state
641 642 643 644 645 646 647
 *   A keyed array containing the current state of the form. Most important is
 *   the $form_state['values'] collection, a tree of data used to simulate the
 *   incoming $_POST information from a user's form submission. If a key is not
 *   filled in $form_state['values'], then the default value of the respective
 *   element is used. To submit an unchecked checkbox or other control that
 *   browsers submit by not having a $_POST entry, include the key, but set the
 *   value to NULL.
648
 * @param ...
649
 *   Any additional arguments are passed on to the functions called by
650
 *   drupal_form_submit(), including the unique form constructor function.
651
 *   For example, the node_edit form requires that a node object be passed
652 653 654 655 656 657 658 659 660 661 662 663 664 665
 *   in here when it is called. Arguments that need to be passed by reference
 *   should not be included here, but rather placed directly in the $form_state
 *   build info array so that the reference can be preserved. For example, a
 *   form builder function with the following signature:
 *   @code
 *   function mymodule_form($form, &$form_state, &$object) {
 *   }
 *   @endcode
 *   would be called via drupal_form_submit() as follows:
 *   @code
 *   $form_state['values'] = $my_form_values;
 *   $form_state['build_info']['args'] = array(&$object);
 *   drupal_form_submit('mymodule_form', $form_state);
 *   @endcode
666
 * For example:
667
 * @code
668
 * // register a new user
669 670 671
 * $form_state = array();
 * $form_state['values']['name'] = 'robo-user';
 * $form_state['values']['mail'] = 'robouser@example.com';
672 673
 * $form_state['values']['pass']['pass1'] = 'password';
 * $form_state['values']['pass']['pass2'] = 'password';
674
 * $form_state['values']['op'] = t('Create new account');
675
 * drupal_form_submit('user_register_form', $form_state);
676
 * @endcode
677
 */
678
function drupal_form_submit($form_id, &$form_state) {
679
  if (!isset($form_state['build_info']['args'])) {
680 681 682
    $args = func_get_args();
    array_shift($args);
    array_shift($args);
683
    $form_state['build_info']['args'] = $args;
684
  }
685 686
  // Merge in default values.
  $form_state += form_state_defaults();
Dries's avatar
Dries committed
687

688 689 690 691
  // Populate $form_state['input'] with the submitted values before retrieving
  // the form, to be consistent with what drupal_build_form() does for
  // non-programmatic submissions (form builder functions may expect it to be
  // there).
692
  $form_state['input'] = $form_state['values'];
693

694
  $form_state['programmed'] = TRUE;
695
  $form = drupal_retrieve_form($form_id, $form_state);
696 697
  // Programmed forms are always submitted.
  $form_state['submitted'] = TRUE;
698

699 700 701 702
  // Reset form validation.
  $form_state['must_validate'] = TRUE;
  form_clear_error();

703 704
  drupal_prepare_form($form_id, $form, $form_state);
  drupal_process_form($form_id, $form, $form_state);
705 706
}

707 708 709 710 711 712 713 714
/**
 * Retrieves the structured array that defines a given form.
 *
 * @param $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
715
 *   different $form_id values to the proper form constructor function.
716
 * @param $form_state
717 718 719
 *   A keyed array containing the current state of the form, including the
 *   additional arguments to drupal_get_form() or drupal_form_submit() in the
 *   'args' component of the array.
720
 */
721
function drupal_retrieve_form($form_id, &$form_state) {
722
  $forms = &drupal_static(__FUNCTION__);
723

724 725 726 727 728 729 730 731
  // Record the filepath of the include file containing the original form, so
  // the form builder callbacks can be loaded when the form is being rebuilt
  // from cache on a different path (such as 'system/ajax'). See
  // form_get_cache().
  // $menu_get_item() is not available at installation time.
  if (!isset($form_state['build_info']['files']['menu']) && !defined('MAINTENANCE_MODE')) {
    $item = menu_get_item();
    if (!empty($item['include_file'])) {
732 733
      // Do not use form_load_include() here, as the file is already loaded.
      // Anyway, form_get_cache() is able to handle filepaths too.
734 735 736 737
      $form_state['build_info']['files']['menu'] = $item['include_file'];
    }
  }

738
  // We save two copies of the incoming arguments: one for modules to use
739
  // when mapping form ids to constructor functions, and another to pass to
740
  // the constructor function itself.
741
  $args = $form_state['build_info']['args'];
742 743 744

  // We first check to see if there's a function named after the $form_id.
  // If there is, we simply pass the arguments on to it to get the form.
745
  if (!function_exists($form_id)) {
746
    // In cases where many form_ids need to share a central constructor function,
747
    // such as the node editing form, modules can implement hook_forms(). It
748
    // maps one or more form_ids to the correct constructor functions.
749 750 751 752 753 754 755 756 757
    //
    // We cache the results of that hook to save time, but that only works
    // for modules that know all their form_ids in advance. (A module that
    // adds a small 'rate this comment' form to each comment in a list
    // would need a unique form_id for each one, for example.)
    //
    // So, we call the hook if $forms isn't yet populated, OR if it doesn't
    // yet have an entry for the requested form_id.
    if (!isset($forms) || !isset($forms[$form_id])) {
758
      $forms = module_invoke_all('forms', $form_id, $args);
759 760 761 762 763 764 765
    }
    $form_definition = $forms[$form_id];
    if (isset($form_definition['callback arguments'])) {
      $args = array_merge($form_definition['callback arguments'], $args);
    }
    if (isset($form_definition['callback'])) {
      $callback = $form_definition['callback'];
766
      $form_state['build_info']['base_form_id'] = $callback;
767
    }
768 769 770 771 772
    // In case $form_state['wrapper_callback'] is not defined already, we also
    // allow hook_forms() to define one.
    if (!isset($form_state['wrapper_callback']) && isset($form_definition['wrapper_callback'])) {
      $form_state['wrapper_callback'] = $form_definition['wrapper_callback'];
    }
773
  }
774

775
  $form = array();
776 777 778 779 780 781 782 783 784
  // Assign a default CSS class name based on $form_id.
  // This happens here and not in drupal_prepare_form() in order to allow the
  // form constructor function to override or remove the default class.
  $form['#attributes']['class'][] = drupal_html_class($form_id);
  // Same for the base form ID, if any.
  if (isset($form_state['build_info']['base_form_id'])) {
    $form['#attributes']['class'][] = drupal_html_class($form_state['build_info']['base_form_id']);
  }

785 786 787 788 789
  // We need to pass $form_state by reference in order for forms to modify it,
  // since call_user_func_array() requires that referenced variables are passed
  // explicitly.
  $args = array_merge(array($form, &$form_state), $args);

790 791 792 793 794
  // When the passed $form_state (not using drupal_get_form()) defines a
  // 'wrapper_callback', then it requests to invoke a separate (wrapping) form
  // builder function to pre-populate the $form array with form elements, which
  // the actual form builder function ($callback) expects. This allows for
  // pre-populating a form with common elements for certain forms, such as
795
  // back/next/save buttons in multi-step form wizards. See drupal_build_form().
796
  if (isset($form_state['wrapper_callback'])) {
797 798 799
    $form = call_user_func_array($form_state['wrapper_callback'], $args);
    // Put the prepopulated $form into $args.
    $args[0] = $form;
800
  }
801

802 803
  // If $callback was returned by a hook_forms() implementation, call it.
  // Otherwise, call the function named after the form id.
804
  $form = call_user_func_array(isset($callback) ? $callback : $form_id, $args);
805
  $form['#form_id'] = $form_id;
806

807
  return $form;
808 809 810
}

/**
811 812
 * Processes a form submission.
 *
813
 * This function is the heart of form API. The form gets built, validated and in
814
 * appropriate cases, submitted and rebuilt.
815 816 817
 *
 * @param $form_id
 *   The unique string identifying the current form.
818 819
 * @param $form
 *   An associative array containing the structure of the form.
820 821
 * @param $form_state
 *   A keyed array containing the current state of the form. This
Dries's avatar
Dries committed
822
 *   includes the current persistent storage data for the form, and
823 824 825
 *   any data passed along by earlier steps when displaying a
 *   multi-step form. Additional information, like the sanitized $_POST
 *   data, is also accumulated here.
826
 */
827 828 829
function drupal_process_form($form_id, &$form, &$form_state) {
  $form_state['values'] = array();

830 831 832 833 834 835 836 837 838 839 840 841 842
  // With $_GET, these forms are always submitted if requested.
  if ($form_state['method'] == 'get' && !empty($form_state['always_process'])) {
    if (!isset($form_state['input']['form_build_id'])) {
      $form_state['input']['form_build_id'] = $form['#build_id'];
    }
    if (!isset($form_state['input']['form_id'])) {
      $form_state['input']['form_id'] = $form_id;
    }
    if (!isset($form_state['input']['form_token']) && isset($form['#token'])) {
      $form_state['input']['form_token'] = drupal_get_token($form['#token']);
    }
  }

843 844 845 846 847
  // form_builder() finishes building the form by calling element #process
  // functions and mapping user input, if any, to #value properties, and also
  // storing the values in $form_state['values']. We need to retain the
  // unprocessed $form in case it needs to be cached.
  $unprocessed_form = $form;
848
  $form = form_builder($form_id, $form, $form_state);
849 850 851

  // Only process the input if we have a correct form submission.
  if ($form_state['process_input']) {
852 853
    drupal_validate_form($form_id, $form, $form_state);

854
    // drupal_html_id() maintains a cache of element IDs it has seen,
855
    // so it can prevent duplicates. We want to be sure we reset that
856
    // cache when a form is processed, so scenarios that result in
857 858
    // the form being built behind the scenes and again for the
    // browser don't increment all the element IDs needlessly.
859
    drupal_static_reset('drupal_html_id');
860

861 862
    if ($form_state['submitted'] && !form_get_errors() && !$form_state['rebuild']) {
      // Execute form submit handlers.
863 864 865 866 867
      form_execute_handlers('submit', $form, $form_state);

      // We'll clear out the cached copies of the form and its stored data
      // here, as we've finished with them. The in-memory copies are still
      // here, though.
gdd's avatar
gdd committed
868 869
      $config = config('system.performance');
      if (!$config->get('cache') && !empty($form_state['values']['form_build_id'])) {
870 871
        cache('form')->delete('form_' . $form_state['values']['form_build_id']);
        cache('form')->delete('form_state_' . $form_state['values']['form_build_id']);
872 873 874
      }

      // If batches were set in the submit handlers, we process them now,
875 876
      // possibly ending execution. We make sure we do not react to the batch
      // that is already being processed (if a batch operation performs a
877
      // drupal_form_submit).
878
      if ($batch =& batch_get() && !isset($batch['current_set'])) {
879 880 881 882 883 884 885
        // Store $form_state information in the batch definition.
        // We need the full $form_state when either:
        // - Some submit handlers were saved to be called during batch
        //   processing. See form_execute_handlers().
        // - The form is multistep.
        // In other cases, we only need the information expected by
        // drupal_redirect_form().
886
        if ($batch['has_form_submits'] || !empty($form_state['rebuild'])) {
887 888 889 890 891 892
          $batch['form_state'] = $form_state;
        }
        else {
          $batch['form_state'] = array_intersect_key($form_state, array_flip(array('programmed', 'rebuild', 'storage', 'no_redirect', 'redirect')));
        }

893
        $batch['progressive'] = !$form_state['programmed'];
894
        batch_process();
895

896 897 898 899
        // Execution continues only for programmatic forms.
        // For 'regular' forms, we get redirected to the batch processing
        // page. Form redirection will be handled in _batch_finished(),
        // after the batch is processed.
900
      }
901

902 903 904
      // Set a flag to indicate the the form has been processed and executed.
      $form_state['executed'] = TRUE;

905 906
      // Redirect the form based on values in $form_state.
      drupal_redirect_form($form_state);
907
    }
908 909 910 911 912 913

    // Don't rebuild or cache form submissions invoked via drupal_form_submit().
    if (!empty($form_state['programmed'])) {
      return;
    }

914 915 916 917 918
    // If $form_state['rebuild'] has been set and input has been processed
    // without validation errors, we are in a multi-step workflow that is not
    // yet complete. A new $form needs to be constructed based on the changes
    // made to $form_state during this request. Normally, a submit handler sets
    // $form_state['rebuild'] if a fully executed form requires another step.
919
    // However, for forms that have not been fully executed (e.g., Ajax
920 921 922 923 924
    // submissions triggered by non-buttons), there is no submit handler to set
    // $form_state['rebuild']. It would not make sense to redisplay the
    // identical form without an error for the user to correct, so we also
    // rebuild error-free non-executed forms, regardless of
    // $form_state['rebuild'].
925
    // @todo D8: Simplify this logic; considering Ajax and non-HTML front-ends,
926 927 928 929 930 931 932 933 934 935
    //   along with element-level #submit properties, it makes no sense to have
    //   divergent form execution based on whether the triggering element has
    //   #executes_submit_callback set to TRUE.
    if (($form_state['rebuild'] || !$form_state['executed']) && !form_get_errors()) {
      // Form building functions (e.g., _form_builder_handle_input_element())
      // may use $form_state['rebuild'] to determine if they are running in the
      // context of a rebuild, so ensure it is set.
      $form_state['rebuild'] = TRUE;
      $form = drupal_rebuild_form($form_id, $form_state, $form);
    }
936
  }
937

938 939 940 941
  // After processing the form, the form builder or a #process callback may
  // have set $form_state['cache'] to indicate that the form and form state
  // shall be cached. But the form may only be cached if the 'no_cache' property
  // is not set to TRUE. Only cache $form as it was prior to form_builder(),
942
  // because form_builder() must run for each request to accommodate new user
943 944 945
  // input. Rebuilt forms are not cached here, because drupal_rebuild_form()
  // already takes care of that.
  if (!$form_state['rebuild'] && $form_state['cache'] && empty($form_state['no_cache'])) {
946
    form_set_cache($form['#build_id'], $unprocessed_form, $form_state);
947 948 949 950
  }
}

/**
951 952 953 954
 * Prepares a structured form array.
 *
 * Adds required elements, executes any hook_form_alter functions, and
 * optionally inserts a validation token to prevent tampering.
955 956 957 958 959 960
 *
 * @param $form_id
 *   A unique string identifying the form for validation, submission,
 *   theming, and hook_form_alter functions.
 * @param $form
 *   An associative array containing the structure of the form.
961 962 963
 * @param $form_state
 *   A keyed array containing the current state of the form. Passed
 *   in here so that hook_form_alter() calls can use it, as well.
964
 */
965
function drupal_prepare_form($form_id, &$form, &$form_state) {
966 967
  global $user;

968
  $form['#type'] = 'form';
969
  $form_state['programmed'] = isset($form_state['programmed']) ? $form_state['programmed'] : FALSE;
970

971 972 973
  // Fix the form method, if it is 'get' in $form_state, but not in $form.
  if ($form_state['method'] == 'get' && !isset($form['#method'])) {
    $form['#method'] = 'get';
974 975
  }

976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991
  // Generate a new #build_id for this form, if none has been set already. The
  // form_build_id is used as key to cache a particular build of the form. For
  // multi-step forms, this allows the user to go back to an earlier build, make
  // changes, and re-submit.
  // @see drupal_build_form()
  // @see drupal_rebuild_form()
  if (!isset($form['#build_id'])) {
    $form['#build_id'] = 'form-' . drupal_hash_base64(uniqid(mt_rand(), TRUE) . mt_rand());
  }
  $form['form_build_id'] = array(
    '#type' => 'hidden',
    '#value' => $form['#build_id'],
    '#id' => $form['#build_id'],
    '#name' => 'form_build_id',
  );

992 993 994 995
  // Add a token, based on either #token or form_id, to any form displayed to
  // authenticated users. This ensures that any submitted form was actually
  // requested previously by the user and protects against cross site request
  // forgeries.
996 997 998 999 1000 1001 1002 1003
  // This does not apply to programmatically submitted forms. Furthermore, since
  // tokens are session-bound and forms displayed to anonymous users are very
  // likely cached, we cannot assign a token for them.
  // During installation, there is no $user yet.
  if (!empty($user->uid) && !$form_state['programmed']) {
    // Form constructors may explicitly set #token to FALSE when cross site
    // request forgery is irrelevant to the form, such as search forms.
    if (isset($form['#token']) && $form['#token'] === FALSE) {
1004
      unset($form['#token']);
1005
    }
1006
    // Otherwise, generate a public token based on the form id.
1007
    else {
1008 1009 1010 1011 1012 1013
      $form['#token'] = $form_id;
      $form['form_token'] = array(
        '#id' => drupal_html_id('edit-' . $form_id . '-form-token'),
        '#type' => 'token',
        '#default_value' => drupal_get_token($form['#token']),
      );
1014
    }
1015
  }
1016

1017
  if (isset($form_id)) {
1018 1019 1020
    $form['form_id'] = array(
      '#type' => 'hidden',
      '#value' => $form_id,
1021
      '#id' => drupal_html_id("edit-$form_id"),
1022
    );
1023
  }
1024
  if (!isset($form['#id'])) {
1025
    $form['#id'] = drupal_html_id($form_id);
1026
  }
Steven Wittens's avatar
Steven Wittens committed
1027

1028
  $form += element_info('form');
1029
  $form += array('#tree' => FALSE, '#parents' => array());
1030

Dries's avatar
Dries committed
1031
  if (!isset($form['#validate'])) {
1032 1033
    // Ensure that modules can rely on #validate being set.
    $form['#validate'] = array();
1034
    // Check for a handler specific to $form_id.
1035
    if (function_exists($form_id . '_validate')) {
1036 1037 1038 1039 1040 1041
      $form['#validate'][] = $form_id . '_validate';
    }
    // Otherwise check whether this is a shared form and whether there is a
    // handler for the shared $form_id.
    elseif (isset($form_state['build_info']['base_form_id']) && function_exists($form_state['build_info']['base_form_id'] . '_validate')) {
      $form['#validate'][] = $form_state['build_info']['base_form_id'] . '_validate';
Dries's avatar
Dries committed
1042 1043 1044
    }
  }

1045
  if (!isset($form['#submit'])) {
1046 1047
    // Ensure that modules can rely on #submit being set.
    $form['#submit'] = array();
1048
    // Check for a handler specific to $form_id.
1049
    if (function_exists($form_id . '_submit')) {
1050 1051 1052 1053 1054 1055
      $form['#submit'][] = $form_id . '_submit';
    }
    // Otherwise check whether this is a shared form and whether there is a
    // handler for the shared $form_id.
    elseif (isset($form_state['build_info']['base_form_id']) && function_exists($form_state['build_info']['base_form_id'] . '_submit')) {
      $form['#submit'][] = $form_state['build_info']['base_form_id'] . '_submit';
Dries's avatar
Dries committed
1056 1057 1058
    }
  }

1059
  // If no #theme has been set, automatically apply theme suggestions.
1060 1061 1062
  // theme_form() itself is in #theme_wrappers and not #theme. Therefore, the
  // #theme function only has to care for rendering the inner form elements,
  // not the form itself.
1063 1064 1065 1066
  if (!isset($form['#theme'])) {
    $form['#theme'] = array($form_id);
    if (isset($form_state['build_info']['base_form_id'])) {
      $form['#theme'][] = $form_state['