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

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

8
use Drupal\Component\Utility\NestedArray;
9
use Drupal\Core\Database\Database;
10
use Drupal\Core\Template\Attribute;
11
use Drupal\Core\Utility\Color;
12

13
/**
14 15 16 17 18 19
 * @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
20
 * functions using \@see. Conversely, validate and submit functions should
21
 * reference the form builder function using \@see. For examples, of this see
22
 * system_modules_uninstall() or user_pass(), the latter of which has the
23 24 25 26 27 28
 * following in its doxygen documentation:
 *
 * \@ingroup forms
 * \@see user_pass_validate().
 * \@see user_pass_submit().
 *
29
 * @} End of "defgroup forms".
30 31 32 33
 */

/**
 * @defgroup form_api Form generation
34
 * @{
35
 * Functions to enable the processing and display of HTML forms.
36
 *
37 38 39 40
 * 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.
 *
41 42 43 44
 * 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.
45
 *
46 47 48 49 50
 * 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:
51
 * @code
52 53 54 55 56 57 58
 * $form = drupal_get_form('my_module_example_form');
 * ...
 * function my_module_example_form($form, &$form_state) {
 *   $form['submit'] = array(
 *     '#type' => 'submit',
 *     '#value' => t('Submit'),
 *   );
59
 *   return $form;
60 61 62 63 64 65 66
 * }
 * function my_module_example_form_validate($form, &$form_state) {
 *   // Validation logic.
 * }
 * function my_module_example_form_submit($form, &$form_state) {
 *   // Submission logic.
 * }
67
 * @endcode
68
 *
69 70 71 72 73 74 75 76 77 78
 * 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,
 *   );
79
 *   return $form;
80 81
 * }
 * @endcode
82
 *
83 84 85 86
 * 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
87
 * @link forms_api_reference.html Form API reference @endlink
88
 * and the
89
 * @link http://drupal.org/node/37775 Form API documentation section. @endlink
90 91 92 93 94 95 96 97 98
 * 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.
 *
99
 * See drupal_build_form() for documentation of $form_state keys.
100 101 102
 */

/**
103 104 105 106 107
 * 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.
108 109
 *
 * @param $form_id
110 111 112 113 114
 *   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(),
115
 *   and search_forms().
116
 * @param ...
117
 *   Any additional arguments are passed on to the functions called by
118 119
 *   drupal_get_form(), including the unique form constructor function. For
 *   example, the node_edit form requires that a node object is passed in here
120
 *   when it is called. These are available to implementations of
121 122
 *   hook_form_alter() and hook_form_FORM_ID_alter() as the array
 *   $form_state['build_info']['args'].
123
 *
124
 * @return
125
 *   The form array.
126 127
 *
 * @see drupal_build_form()
128 129
 */
function drupal_get_form($form_id) {
130
  $form_state = array();
131 132

  $args = func_get_args();
133 134
  // Remove $form_id from the arguments.
  array_shift($args);
135
  $form_state['build_info']['args'] = $args;
136 137 138 139 140

  return drupal_build_form($form_id, $form_state);
}

/**
141
 * Builds and processes a form for a given form ID.
142 143 144
 *
 * 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
145
 * and submission if there is proper input.
146 147 148 149 150 151 152
 *
 * @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(),
153
 *   and search_forms().
154
 * @param $form_state
155
 *   An array which stores information about the form. This is passed as a
156
 *   reference so that the caller can use it to examine what in the form changed
157 158 159
 *   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.
160 161
 *   The following parameters may be set in $form_state to affect how the form
 *   is rendered:
162 163 164
 *   - 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:
165 166
 *     - callback: The actual callback to be used to retrieve the form array. If
 *       none is provided $form_id is used instead. Can be any callable type.
167
 *     - args: A list of arguments to pass to the form constructor.
168 169 170 171
 *     - 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
172
 *       automatically loaded by form_get_cache(). By default the current menu
173 174
 *       router item's 'file' definition is added, if any. Use
 *       form_load_include() to add include files from a form constructor.
175 176
 *     - form_id: Identification of the primary form being constructed and
 *       processed.
177 178
 *     - base_form_id: Identification for a base form, as declared in a
 *       hook_forms() implementation.
179 180
 *   - rebuild_info: Internal. Similar to 'build_info', but pertaining to
 *     drupal_rebuild_form().
181
 *   - rebuild: Normally, after the entire form processing is completed and
182
 *     submit handlers have run, a form is considered to be done and
183 184 185
 *     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
186
 *     immediately built and sent to the browser, instead of a redirect. This is
187 188 189 190 191 192 193
 *     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.
194 195 196 197 198 199
 *   - 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.
200 201 202 203
 *   - 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
204 205
 *     forms that do not change data, as that is exclusively the domain of
 *     'post.'
206
 *   - cache: If set to TRUE the original, unprocessed form structure will be
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
 *     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'.
222 223
 *   - no_cache: If set to TRUE the form will NOT be cached, even if 'cache' is
 *     set.
224 225
 *   - values: An associative array of values submitted to the form. The
 *     validation functions and submit functions use this array for nearly all
226 227 228 229
 *     their decision making. (Note that #tree determines whether the values
 *     are a flat array or an array whose structure parallels the $form array.
 *     See the @link forms_api_reference.html Form API reference @endlink for
 *     more information.)
230 231 232 233 234 235 236
 *   - 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.
237 238 239 240 241
 *   - 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.
242
 *   - must_validate: Ordinarily, a form is only validated once, but there are
243 244
 *     times when a form is resubmitted internally and should be validated
 *     again. Setting this to TRUE will force that to happen. This is most
245 246 247 248 249 250 251 252 253 254 255
 *     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
256 257 258
 *     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.
259 260
 *   - has_file_element: Internal. If TRUE, there is a file element and Form API
 *     will set the appropriate 'enctype' HTML attribute on the form.
261 262
 *   - groups: Internal. An array containing references to details elements to
 *     render them within vertical tabs.
263 264 265 266 267 268 269 270 271
 *   - 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
272 273 274 275 276
 *     key name or a prefix for the key name. For example, the entity form
 *     controller classes use $form_state['entity'] in entity forms to store
 *     information about the entity being edited, and this information stays
 *     available across successive clicks of the "Preview" button (if available)
 *     as well as when the "Save" button is finally clicked.
277 278 279 280 281 282
 *   - 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.
283
 *   - temporary: An array holding temporary data accessible during the current
284 285 286 287 288 289 290 291
 *     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.
292 293 294 295
 *   - 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.
296 297 298 299
 *     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.
300 301
 *   Information on how certain $form_state properties control redirection
 *   behavior after form submission may be found in drupal_redirect_form().
302
 *
303
 * @return
304 305
 *   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.
306 307
 *
 * @see drupal_redirect_form()
308 309 310 311 312 313 314 315 316
 */
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;
  }

317
  if (isset($_SESSION['batch_form_state'])) {
318 319
    // We've been redirected here after a batch processing. The form has
    // already been processed, but needs to be rebuilt. See _batch_finished().
320 321
    $form_state = $_SESSION['batch_form_state'];
    unset($_SESSION['batch_form_state']);
322
    return drupal_rebuild_form($form_id, $form_state);
323
  }
324

325 326 327 328 329 330 331 332
  // 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);
333 334
  }

335 336 337 338 339 340 341 342 343
  // 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;
344
    }
345

346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
    $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;
367
    }
368
  }
369

370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390
  // 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.
391
  return $form;
392
}
393

394
/**
395
 * Retrieves default values for the $form_state array.
396 397 398
 */
function form_state_defaults() {
  return array(
399
    'rebuild' => FALSE,
400
    'rebuild_info' => array(),
401
    'redirect' => NULL,
402 403 404 405 406 407
    // @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(),
    ),
408
    'temporary' => array(),
409
    'submitted' => FALSE,
410
    'executed' => FALSE,
411
    'programmed' => FALSE,
412 413
    'cache'=> FALSE,
    'method' => 'post',
414
    'groups' => array(),
415
    'buttons' => array(),
416 417 418
  );
}

419
/**
420 421 422 423 424 425 426 427 428
 * 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.
429
 *
430
 * Ajax form submissions are almost always multi-step workflows, so that is one
431
 * common use-case during which form rebuilding occurs. See ajax_form_callback()
432
 * for more information about creating Ajax-enabled forms.
433 434 435 436 437 438 439
 *
 * @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
440
 *   may be found in node_forms() and search_forms().
441
 * @param $form_state
442
 *   A keyed array containing the current state of the form.
443 444
 * @param $old_form
 *   (optional) A previously built $form. Used to retain the #build_id and
445
 *   #action properties in Ajax callbacks and similar partial form rebuilds. The
446 447 448 449 450
 *   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.
451
 *
452 453
 * @return
 *   The newly built form.
454 455 456
 *
 * @see drupal_process_form()
 * @see ajax_form_callback()
457
 */
458
function drupal_rebuild_form($form_id, &$form_state, $old_form = NULL) {
459
  $form = drupal_retrieve_form($form_id, $form_state);
460

461
  // If only parts of the form will be returned to the browser (e.g., Ajax or
462 463 464 465 466
  // 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.
467 468 469 470 471 472 473
  // @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());
  }
474

475
  // #action defaults to request_uri(), but in case of Ajax and other partial
476 477
  // rebuilds, the form is submitted to an alternate URL, and the original
  // #action needs to be retained.
478
  if (isset($old_form['#action']) && !empty($form_state['rebuild_info']['copy']['#action'])) {
479
    $form['#action'] = $old_form['#action'];
480
  }
481

482 483
  drupal_prepare_form($form_id, $form, $form_state);

484 485 486 487
  // 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.
488
  if (empty($form_state['no_cache'])) {
489
    form_set_cache($form['#build_id'], $form, $form_state);
490
  }
491

492 493
  // Clear out all group associations as these might be different when
  // re-rendering the form.
494 495
  $form_state['groups'] = array();

496 497
  // Return a fully built form that is ready for rendering.
  return form_builder($form_id, $form, $form_state);
498 499
}

500
/**
501
 * Fetches a form from the cache.
502 503
 */
function form_get_cache($form_build_id, &$form_state) {
504
  if ($cached = cache('form')->get('form_' . $form_build_id)) {
505
    $form = $cached->data;
506

507 508
    global $user;
    if ((isset($form['#cache_token']) && drupal_valid_token($form['#cache_token'])) || (!isset($form['#cache_token']) && !$user->uid)) {
509
      if ($cached = cache('form')->get('form_state_' . $form_build_id)) {
510
        // Re-populate $form_state for subsequent rebuilds.
511
        $form_state = $cached->data + $form_state;
512

513
        // If the original form is contained in include files, load the files.
514
        // @see form_load_include()
515 516 517 518 519 520 521 522 523
        $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;
          }
524
        }
525 526
      }
      return $form;
527 528 529 530 531
    }
  }
}

/**
532
 * Stores a form in the cache.
533 534
 */
function form_set_cache($form_build_id, $form, $form_state) {
535 536
  // 6 hours cache life time for forms should be plenty.
  $expire = 21600;
537 538 539 540 541 542

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

  // Cache form state.
547
  if ($data = array_diff_key($form_state, array_flip(form_state_keys_no_cache()))) {
548
    cache('form')->set('form_state_' . $form_build_id, $data, REQUEST_TIME + $expire);
549 550 551
  }
}

552 553 554 555 556 557 558 559 560
/**
 * 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',
561
    'rebuild_info',
562 563 564 565 566
    'redirect',
    'no_redirect',
    'temporary',
    // Internal properties defined by form processing.
    'buttons',
567
    'triggering_element',
568
    'complete_form',
569 570 571 572 573
    'groups',
    'input',
    'method',
    'submit_handlers',
    'submitted',
574
    'executed',
575 576 577 578 579
    'validate_handlers',
    'values',
  );
}

580
/**
581
 * Ensures an include file is loaded whenever the form is processed.
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 623 624 625 626 627 628
 *
 * 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;
}

629
/**
630 631 632 633 634 635 636 637
 * 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().
638 639 640 641 642 643
 *
 * @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
644
 *   different $form_id values to the proper form constructor function. Examples
645
 *   may be found in node_forms() and search_forms().
646
 * @param $form_state
647 648 649 650 651 652 653
 *   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.
654
 * @param ...
655
 *   Any additional arguments are passed on to the functions called by
656
 *   drupal_form_submit(), including the unique form constructor function.
657
 *   For example, the node_edit form requires that a node object be passed
658 659 660 661 662 663 664 665 666 667 668 669 670 671
 *   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
672
 * For example:
673
 * @code
674
 * // register a new user
675 676 677
 * $form_state = array();
 * $form_state['values']['name'] = 'robo-user';
 * $form_state['values']['mail'] = 'robouser@example.com';
678 679
 * $form_state['values']['pass']['pass1'] = 'password';
 * $form_state['values']['pass']['pass2'] = 'password';
680
 * $form_state['values']['op'] = t('Create new account');
681
 * drupal_form_submit('user_register_form', $form_state);
682
 * @endcode
683
 */
684
function drupal_form_submit($form_id, &$form_state) {
685
  if (!isset($form_state['build_info']['args'])) {
686 687 688
    $args = func_get_args();
    array_shift($args);
    array_shift($args);
689
    $form_state['build_info']['args'] = $args;
690
  }
691 692
  // Merge in default values.
  $form_state += form_state_defaults();
Dries's avatar
Dries committed
693

694 695 696 697
  // 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).
698
  $form_state['input'] = $form_state['values'];
699

700
  $form_state['programmed'] = TRUE;
701
  $form = drupal_retrieve_form($form_id, $form_state);
702 703
  // Programmed forms are always submitted.
  $form_state['submitted'] = TRUE;
704

705 706 707 708
  // Reset form validation.
  $form_state['must_validate'] = TRUE;
  form_clear_error();

709 710
  drupal_prepare_form($form_id, $form, $form_state);
  drupal_process_form($form_id, $form, $form_state);
711 712
}

713 714 715 716 717 718 719 720
/**
 * 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
721
 *   different $form_id values to the proper form constructor function.
722
 * @param $form_state
723 724 725
 *   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.
726
 */
727
function drupal_retrieve_form($form_id, &$form_state) {
728
  $forms = &drupal_static(__FUNCTION__);
729

730 731 732
  // Record the $form_id.
  $form_state['build_info']['form_id'] = $form_id;

733 734 735 736 737 738 739 740
  // 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'])) {
741 742
      // Do not use form_load_include() here, as the file is already loaded.
      // Anyway, form_get_cache() is able to handle filepaths too.
743 744 745 746
      $form_state['build_info']['files']['menu'] = $item['include_file'];
    }
  }

747
  // We save two copies of the incoming arguments: one for modules to use
748
  // when mapping form ids to constructor functions, and another to pass to
749
  // the constructor function itself.
750
  $args = $form_state['build_info']['args'];
751

752 753 754 755 756
  // If an explicit form builder callback is defined we just use it, otherwise
  // we look for a function named after the $form_id.
  $callback = !empty($form_state['build_info']['callback']) ? $form_state['build_info']['callback'] : $form_id;

  // We first check to see if there is a valid form builder callback defined.
757
  // If there is, we simply pass the arguments on to it to get the form.
758
  if (!is_callable($callback)) {
759
    // In cases where many form_ids need to share a central constructor function,
760
    // such as the node editing form, modules can implement hook_forms(). It
761
    // maps one or more form_ids to the correct constructor functions.
762 763 764 765 766 767 768 769 770
    //
    // 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])) {
771
      $forms = module_invoke_all('forms', $form_id, $args);
772 773 774 775 776 777 778
    }
    $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'];
779
      $form_state['build_info']['base_form_id'] = $callback;
780
    }
781 782 783 784 785
    // 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'];
    }
786
  }
787

788
  $form = array();
789 790 791 792 793 794 795 796 797
  // 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']);
  }

798 799 800 801 802
  // 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);

803 804 805 806 807
  // 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
808
  // back/next/save buttons in multi-step form wizards. See drupal_build_form().
809
  if (isset($form_state['wrapper_callback'])) {
810 811 812
    $form = call_user_func_array($form_state['wrapper_callback'], $args);
    // Put the prepopulated $form into $args.
    $args[0] = $form;
813
  }
814

815 816
  // If $callback was returned by a hook_forms() implementation, call it.
  // Otherwise, call the function named after the form id.
817
  $form = call_user_func_array($callback, $args);
818
  $form['#form_id'] = $form_id;
819

820
  return $form;
821 822 823
}

/**
824 825
 * Processes a form submission.
 *
826
 * This function is the heart of form API. The form gets built, validated and in
827
 * appropriate cases, submitted and rebuilt.
828 829 830
 *
 * @param $form_id
 *   The unique string identifying the current form.
831 832
 * @param $form
 *   An associative array containing the structure of the form.
833 834
 * @param $form_state
 *   A keyed array containing the current state of the form. This
Dries's avatar
Dries committed
835
 *   includes the current persistent storage data for the form, and
836 837 838
 *   any data passed along by earlier steps when displaying a
 *   multi-step form. Additional information, like the sanitized $_POST
 *   data, is also accumulated here.
839
 */
840 841 842
function drupal_process_form($form_id, &$form, &$form_state) {
  $form_state['values'] = array();

843 844 845 846 847 848 849 850 851 852 853 854 855
  // 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']);
    }
  }

856 857 858 859 860
  // 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;
861
  $form = form_builder($form_id, $form, $form_state);
862 863 864

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

867
    // drupal_html_id() maintains a cache of element IDs it has seen,
868
    // so it can prevent duplicates. We want to be sure we reset that
869
    // cache when a form is processed, so scenarios that result in
870 871
    // the form being built behind the scenes and again for the
    // browser don't increment all the element IDs needlessly.
872 873 874 875
    if (!form_get_errors()) {
      // In case of errors, do not break HTML IDs of other forms.
      drupal_static_reset('drupal_html_id');
    }
876

877 878
    if ($form_state['submitted'] && !form_get_errors() && !$form_state['rebuild']) {
      // Execute form submit handlers.
879 880 881 882 883
      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
884
      $config = config('system.performance');
885
      if (!$config->get('cache.page.enabled') && !empty($form_state['values']['form_build_id'])) {
886 887
        cache('form')->delete('form_' . $form_state['values']['form_build_id']);
        cache('form')->delete('form_state_' . $form_state['values']['form_build_id']);
888 889 890
      }

      // If batches were set in the submit handlers, we process them now,
891 892
      // possibly ending execution. We make sure we do not react to the batch
      // that is already being processed (if a batch operation performs a
893
      // drupal_form_submit).
894
      if ($batch =& batch_get() && !isset($batch['current_set'])) {
895 896 897 898 899 900 901
        // 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().
902
        if ($batch['has_form_submits'] || !empty($form_state['rebuild'])) {
903 904 905 906 907 908
          $batch['form_state'] = $form_state;
        }
        else {
          $batch['form_state'] = array_intersect_key($form_state, array_flip(array('programmed', 'rebuild', 'storage', 'no_redirect', 'redirect')));
        }

909
        $batch['progressive'] = !$form_state['programmed'];
910
        batch_process();
911

912 913 914 915
        // 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.
916
      }
917

918 919 920
      // Set a flag to indicate the the form has been processed and executed.
      $form_state['executed'] = TRUE;

921 922
      // Redirect the form based on values in $form_state.
      drupal_redirect_form($form_state);
923
    }
924 925 926 927 928 929

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

930 931 932 933 934
    // 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.
935
    // However, for forms that have not been fully executed (e.g., Ajax
936 937 938 939 940
    // 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'].
941
    // @todo D8: Simplify this logic; considering Ajax and non-HTML front-ends,
942 943 944 945 946 947 948 949 950 951
    //   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);
    }
952
  }
953

954 955 956 957
  // 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(),
958
  // because form_builder() must run for each request to accommodate new user
959 960 961
  // 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'])) {
962
    form_set_cache($form['#build_id'], $unprocessed_form, $form_state);
963 964 965 966
  }
}

/**
967 968 969 970
 * Prepares a structured form array.
 *
 * Adds required elements, executes any hook_form_alter functions, and
 * optionally inserts a validation token to prevent tampering.
971 972 973 974 975 976
 *
 * @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.
977 978 979
 * @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.
980
 */
981
function drupal_prepare_form($form_id, &$form, &$form_state) {
982 983
  global $user;

984
  $form['#type'] = 'form';
985
  $form_state['programmed'] = isset($form_state['programmed']) ? $form_state['programmed'] : FALSE;
986

987 988 989
  // 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';
990 991
  }

992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005
  // 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',
1006 1007 1008 1009
    // Form processing and validation requires this value, so ensure the
    // submitted form value appears literally, regardless of custom #tree
    // and #parents being set elsewhere.
    '#parents' => array('form_build_id'),
1010 1011
  );

1012 1013 1014 1015
  // 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.
1016 1017 1018 1019 1020 1021 1022 1023
  // 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) {
1024
      unset($form['#token']);
1025
    }