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\Form\FormInterface;
10
use Drupal\Core\Database\Database;
11
use Drupal\Core\Template\Attribute;
12
use Drupal\Core\Datetime\DrupalDateTime;
13
use Drupal\Core\Utility\Color;
14

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

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

104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
/**
 * Determines the form ID.
 *
 * @param \Drupal\Core\Form\FormInterface|string $form_arg
 *   A form object to use to build the form, or the unique string identifying
 *   the desired form. If $form_arg is a string and a function with that
 *   name exists, it is called to build the form array.
 * @param array $form_state
 *   An associative array containing the current state of the form.
 *
 * @return string
 *   The unique string identifying the desired form.
 */
function _drupal_form_id($form_arg, &$form_state) {
  // If the $form_arg implements \Drupal\Core\Form\FormInterface, add that as
  // the callback object and determine the form ID.
  if (is_object($form_arg) && $form_arg instanceof FormInterface) {
    $form_state['build_info']['callback_object'] = $form_arg;
    return $form_arg->getFormID();
  }

  // Otherwise, the $form_arg is the form ID.
  return $form_arg;
}

129
/**
130 131 132 133 134
 * 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.
135
 *
136 137 138
 * @param \Drupal\Core\Form\FormInterface|string $form_arg
 *   A form object to use to build the form, or the unique string identifying
 *   the desired form. If $form_arg is a string and a function with that
139 140 141 142
 *   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(),
143
 *   and search_forms().
144
 * @param ...
145
 *   Any additional arguments are passed on to the functions called by
146 147
 *   drupal_get_form(), including the unique form constructor function. For
 *   example, the node_edit form requires that a node object is passed in here
148
 *   when it is called. These are available to implementations of
149 150
 *   hook_form_alter() and hook_form_FORM_ID_alter() as the array
 *   $form_state['build_info']['args'].
151
 *
152
 * @return
153
 *   The form array.
154 155
 *
 * @see drupal_build_form()
156
 */
157
function drupal_get_form($form_arg) {
158
  $form_state = array();
159 160

  $args = func_get_args();
161
  // Remove $form_arg from the arguments.
162
  array_shift($args);
163
  $form_state['build_info']['args'] = $args;
164

165
  $form_id = _drupal_form_id($form_arg, $form_state);
166 167 168
  return drupal_build_form($form_id, $form_state);
}

169
/**
170
 * Builds and processes a form for a given form ID.
171 172 173
 *
 * 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
174
 * and submission if there is proper input.
175 176 177 178 179 180 181
 *
 * @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(),
182
 *   and search_forms().
183
 * @param $form_state
184
 *   An array which stores information about the form. This is passed as a
185
 *   reference so that the caller can use it to examine what in the form changed
186 187 188
 *   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.
189 190
 *   The following parameters may be set in $form_state to affect how the form
 *   is rendered:
191 192 193
 *   - 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:
194 195
 *     - 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.
196
 *     - args: A list of arguments to pass to the form constructor.
197 198 199 200
 *     - 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
201
 *       automatically loaded by form_get_cache(). By default the current menu
202 203
 *       router item's 'file' definition is added, if any. Use
 *       form_load_include() to add include files from a form constructor.
204 205
 *     - form_id: Identification of the primary form being constructed and
 *       processed.
206 207
 *     - base_form_id: Identification for a base form, as declared in a
 *       hook_forms() implementation.
208 209
 *   - rebuild_info: Internal. Similar to 'build_info', but pertaining to
 *     drupal_rebuild_form().
210
 *   - rebuild: Normally, after the entire form processing is completed and
211
 *     submit handlers have run, a form is considered to be done and
212 213 214
 *     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
215
 *     immediately built and sent to the browser, instead of a redirect. This is
216 217 218 219 220 221 222
 *     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.
223 224 225 226 227 228
 *   - 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.
229 230 231 232
 *   - 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
233 234
 *     forms that do not change data, as that is exclusively the domain of
 *     'post.'
235
 *   - cache: If set to TRUE the original, unprocessed form structure will be
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
 *     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'.
251 252
 *   - no_cache: If set to TRUE the form will NOT be cached, even if 'cache' is
 *     set.
253 254
 *   - values: An associative array of values submitted to the form. The
 *     validation functions and submit functions use this array for nearly all
255 256 257 258
 *     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.)
259 260 261 262 263 264 265
 *   - 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.
266 267 268 269 270
 *   - 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.
271
 *   - must_validate: Ordinarily, a form is only validated once, but there are
272 273
 *     times when a form is resubmitted internally and should be validated
 *     again. Setting this to TRUE will force that to happen. This is most
274 275 276 277 278 279 280 281 282 283 284
 *     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
285 286 287
 *     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.
288 289
 *   - has_file_element: Internal. If TRUE, there is a file element and Form API
 *     will set the appropriate 'enctype' HTML attribute on the form.
290 291
 *   - groups: Internal. An array containing references to details elements to
 *     render them within vertical tabs.
292 293 294 295 296 297 298 299 300
 *   - 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
301 302 303 304 305
 *     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.
306 307 308 309 310 311
 *   - 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.
312
 *   - temporary: An array holding temporary data accessible during the current
313 314 315 316 317 318 319 320
 *     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.
321 322 323 324
 *   - 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.
325 326 327 328
 *     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.
329 330
 *   Information on how certain $form_state properties control redirection
 *   behavior after form submission may be found in drupal_redirect_form().
331
 *
332
 * @return
333 334
 *   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.
335 336
 *
 * @see drupal_redirect_form()
337 338 339 340 341 342 343 344 345
 */
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;
  }

346
  if (isset($_SESSION['batch_form_state'])) {
347 348
    // We've been redirected here after a batch processing. The form has
    // already been processed, but needs to be rebuilt. See _batch_finished().
349 350
    $form_state = $_SESSION['batch_form_state'];
    unset($_SESSION['batch_form_state']);
351
    return drupal_rebuild_form($form_id, $form_state);
352
  }
353

354 355 356 357 358 359 360 361
  // 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);
362 363
  }

364 365 366 367 368 369 370 371 372
  // 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;
373
    }
374

375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395
    $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;
396
    }
397
  }
398

399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419
  // 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.
420
  return $form;
421
}
422

423
/**
424
 * Retrieves default values for the $form_state array.
425 426 427
 */
function form_state_defaults() {
  return array(
428
    'rebuild' => FALSE,
429
    'rebuild_info' => array(),
430
    'redirect' => NULL,
431 432 433 434 435 436
    // @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(),
    ),
437
    'temporary' => array(),
438
    'submitted' => FALSE,
439
    'executed' => FALSE,
440
    'programmed' => FALSE,
441 442
    'cache'=> FALSE,
    'method' => 'post',
443
    'groups' => array(),
444
    'buttons' => array(),
445 446 447
  );
}

448
/**
449 450 451 452 453 454 455 456 457
 * 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.
458
 *
459
 * Ajax form submissions are almost always multi-step workflows, so that is one
460
 * common use-case during which form rebuilding occurs. See ajax_form_callback()
461
 * for more information about creating Ajax-enabled forms.
462 463 464 465 466 467 468
 *
 * @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
469
 *   may be found in node_forms() and search_forms().
470
 * @param $form_state
471
 *   A keyed array containing the current state of the form.
472 473
 * @param $old_form
 *   (optional) A previously built $form. Used to retain the #build_id and
474
 *   #action properties in Ajax callbacks and similar partial form rebuilds. The
475 476 477 478 479
 *   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.
480
 *
481 482
 * @return
 *   The newly built form.
483 484 485
 *
 * @see drupal_process_form()
 * @see ajax_form_callback()
486
 */
487
function drupal_rebuild_form($form_id, &$form_state, $old_form = NULL) {
488
  $form = drupal_retrieve_form($form_id, $form_state);
489

490
  // If only parts of the form will be returned to the browser (e.g., Ajax or
491 492 493 494 495
  // 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.
496 497 498 499 500 501 502
  // @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());
  }
503

504
  // #action defaults to request_uri(), but in case of Ajax and other partial
505 506
  // rebuilds, the form is submitted to an alternate URL, and the original
  // #action needs to be retained.
507
  if (isset($old_form['#action']) && !empty($form_state['rebuild_info']['copy']['#action'])) {
508
    $form['#action'] = $old_form['#action'];
509
  }
510

511 512
  drupal_prepare_form($form_id, $form, $form_state);

513 514 515 516
  // 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.
517
  if (empty($form_state['no_cache'])) {
518
    form_set_cache($form['#build_id'], $form, $form_state);
519
  }
520

521 522
  // Clear out all group associations as these might be different when
  // re-rendering the form.
523 524
  $form_state['groups'] = array();

525 526
  // Return a fully built form that is ready for rendering.
  return form_builder($form_id, $form, $form_state);
527 528
}

529
/**
530
 * Fetches a form from the cache.
531 532
 */
function form_get_cache($form_build_id, &$form_state) {
533
  if ($cached = cache('form')->get('form_' . $form_build_id)) {
534
    $form = $cached->data;
535

536 537
    global $user;
    if ((isset($form['#cache_token']) && drupal_valid_token($form['#cache_token'])) || (!isset($form['#cache_token']) && !$user->uid)) {
538
      if ($cached = cache('form')->get('form_state_' . $form_build_id)) {
539
        // Re-populate $form_state for subsequent rebuilds.
540
        $form_state = $cached->data + $form_state;
541

542
        // If the original form is contained in include files, load the files.
543
        // @see form_load_include()
544 545 546 547 548 549 550 551 552
        $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;
          }
553
        }
554 555
      }
      return $form;
556 557 558 559 560
    }
  }
}

/**
561
 * Stores a form in the cache.
562 563
 */
function form_set_cache($form_build_id, $form, $form_state) {
564 565
  // 6 hours cache life time for forms should be plenty.
  $expire = 21600;
566 567 568 569 570 571

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

  // Cache form state.
576
  if ($data = array_diff_key($form_state, array_flip(form_state_keys_no_cache()))) {
577
    cache('form')->set('form_state_' . $form_build_id, $data, REQUEST_TIME + $expire);
578 579 580
  }
}

581 582 583 584 585 586 587 588 589
/**
 * 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',
590
    'rebuild_info',
591 592 593 594 595
    'redirect',
    'no_redirect',
    'temporary',
    // Internal properties defined by form processing.
    'buttons',
596
    'triggering_element',
597
    'complete_form',
598 599 600 601 602
    'groups',
    'input',
    'method',
    'submit_handlers',
    'submitted',
603
    'executed',
604 605 606 607 608
    'validate_handlers',
    'values',
  );
}

609
/**
610
 * Ensures an include file is loaded whenever the form is processed.
611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657
 *
 * 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;
}

658
/**
659 660 661 662 663 664 665 666
 * 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().
667
 *
668 669 670 671 672 673 674 675
 * @param \Drupal\Core\Form\FormInterface|string $form_arg
 *   A form object to use to build the form, or the unique string identifying
 *   the desired form. If $form_arg is a string and a function with that
 *   name exists, it is called to build the form array. Modules that need to
 *   generate the same form (or very similar forms) using different $form_ids
 *   can implement hook_forms(), which maps different $form_id values to the
 *   proper form constructor function. Examples may be found in node_forms()
 *   and search_forms().
676
 * @param $form_state
677 678 679 680 681 682 683
 *   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.
684
 * @param ...
685
 *   Any additional arguments are passed on to the functions called by
686
 *   drupal_form_submit(), including the unique form constructor function.
687
 *   For example, the node_edit form requires that a node object be passed
688 689 690 691 692 693 694 695 696 697 698 699 700 701
 *   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
702
 * For example:
703
 * @code
704
 * // register a new user
705 706 707
 * $form_state = array();
 * $form_state['values']['name'] = 'robo-user';
 * $form_state['values']['mail'] = 'robouser@example.com';
708 709
 * $form_state['values']['pass']['pass1'] = 'password';
 * $form_state['values']['pass']['pass2'] = 'password';
710
 * $form_state['values']['op'] = t('Create new account');
711
 * drupal_form_submit('user_register_form', $form_state);
712
 * @endcode
713
 */
714
function drupal_form_submit($form_arg, &$form_state) {
715
  if (!isset($form_state['build_info']['args'])) {
716 717 718
    $args = func_get_args();
    array_shift($args);
    array_shift($args);
719
    $form_state['build_info']['args'] = $args;
720
  }
721 722
  // Merge in default values.
  $form_state += form_state_defaults();
Dries's avatar
Dries committed
723

724 725 726 727
  // 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).
728
  $form_state['input'] = $form_state['values'];
729

730
  $form_state['programmed'] = TRUE;
731 732

  $form_id = _drupal_form_id($form_arg, $form_state);
733
  $form = drupal_retrieve_form($form_id, $form_state);
734 735
  // Programmed forms are always submitted.
  $form_state['submitted'] = TRUE;
736

737 738 739 740
  // Reset form validation.
  $form_state['must_validate'] = TRUE;
  form_clear_error();

741 742
  drupal_prepare_form($form_id, $form, $form_state);
  drupal_process_form($form_id, $form, $form_state);
743 744
}

745 746 747 748 749 750 751 752
/**
 * 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
753
 *   different $form_id values to the proper form constructor function.
754
 * @param $form_state
755 756 757
 *   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.
758
 */
759
function drupal_retrieve_form($form_id, &$form_state) {
760
  $forms = &drupal_static(__FUNCTION__);
761

762 763 764
  // Record the $form_id.
  $form_state['build_info']['form_id'] = $form_id;

765 766 767 768 769 770 771 772
  // 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'])) {
773 774
      // Do not use form_load_include() here, as the file is already loaded.
      // Anyway, form_get_cache() is able to handle filepaths too.
775 776 777 778
      $form_state['build_info']['files']['menu'] = $item['include_file'];
    }
  }

779
  // We save two copies of the incoming arguments: one for modules to use
780
  // when mapping form ids to constructor functions, and another to pass to
781
  // the constructor function itself.
782
  $args = $form_state['build_info']['args'];
783

784 785
  // If an explicit form builder callback is defined we just use it, otherwise
  // we look for a function named after the $form_id.
786 787 788 789 790
  $callback = $form_id;
  if (!empty($form_state['build_info']['callback'])) {
    $callback = $form_state['build_info']['callback'];
  }
  elseif (!empty($form_state['build_info']['callback_object'])) {
791
    $callback = array($form_state['build_info']['callback_object'], 'buildForm');
792
  }
793 794

  // We first check to see if there is a valid form builder callback defined.
795
  // If there is, we simply pass the arguments on to it to get the form.
796
  if (!is_callable($callback)) {
797
    // In cases where many form_ids need to share a central constructor function,
798
    // such as the node editing form, modules can implement hook_forms(). It
799
    // maps one or more form_ids to the correct constructor functions.
800 801 802 803 804 805 806 807 808
    //
    // 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])) {
809
      $forms = module_invoke_all('forms', $form_id, $args);
810 811 812 813 814 815 816
    }
    $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'];
817
      $form_state['build_info']['base_form_id'] = $callback;
818
    }
819 820 821 822 823
    // 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'];
    }
824
  }
825

826
  $form = array();
827 828 829 830 831 832 833 834 835
  // 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']);
  }

836 837 838 839 840
  // 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);

841 842 843 844 845
  // 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
846
  // back/next/save buttons in multi-step form wizards. See drupal_build_form().
847
  if (isset($form_state['wrapper_callback'])) {
848 849 850
    $form = call_user_func_array($form_state['wrapper_callback'], $args);
    // Put the prepopulated $form into $args.
    $args[0] = $form;
851
  }
852

853 854
  // If $callback was returned by a hook_forms() implementation, call it.
  // Otherwise, call the function named after the form id.
855
  $form = call_user_func_array($callback, $args);
856
  $form['#form_id'] = $form_id;
857

858
  return $form;
859 860 861
}

/**
862 863
 * Processes a form submission.
 *
864
 * This function is the heart of form API. The form gets built, validated and in
865
 * appropriate cases, submitted and rebuilt.
866 867 868
 *
 * @param $form_id
 *   The unique string identifying the current form.
869 870
 * @param $form
 *   An associative array containing the structure of the form.
871 872
 * @param $form_state
 *   A keyed array containing the current state of the form. This
Dries's avatar
Dries committed
873
 *   includes the current persistent storage data for the form, and
874 875 876
 *   any data passed along by earlier steps when displaying a
 *   multi-step form. Additional information, like the sanitized $_POST
 *   data, is also accumulated here.
877
 */
878 879 880
function drupal_process_form($form_id, &$form, &$form_state) {
  $form_state['values'] = array();

881 882 883 884 885 886 887 888 889 890 891 892 893
  // 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']);
    }
  }

894 895 896 897 898
  // 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;
899
  $form = form_builder($form_id, $form, $form_state);
900 901 902

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

905
    // drupal_html_id() maintains a cache of element IDs it has seen,
906
    // so it can prevent duplicates. We want to be sure we reset that
907
    // cache when a form is processed, so scenarios that result in
908 909
    // the form being built behind the scenes and again for the
    // browser don't increment all the element IDs needlessly.
910 911 912 913
    if (!form_get_errors()) {
      // In case of errors, do not break HTML IDs of other forms.
      drupal_static_reset('drupal_html_id');
    }
914

915 916
    if ($form_state['submitted'] && !form_get_errors() && !$form_state['rebuild']) {
      // Execute form submit handlers.
917 918 919 920 921
      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
922
      $config = config('system.performance');
923
      if (!$config->get('cache.page.use_internal') && !empty($form_state['values']['form_build_id'])) {
924 925
        cache('form')->delete('form_' . $form_state['values']['form_build_id']);
        cache('form')->delete('form_state_' . $form_state['values']['form_build_id']);
926 927 928
      }

      // If batches were set in the submit handlers, we process them now,
929 930
      // possibly ending execution. We make sure we do not react to the batch
      // that is already being processed (if a batch operation performs a
931
      // drupal_form_submit).
932
      if ($batch =& batch_get() && !isset($batch['current_set'])) {
933 934 935 936 937 938 939
        // 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().
940
        if ($batch['has_form_submits'] || !empty($form_state['rebuild'])) {
941 942 943 944 945 946
          $batch['form_state'] = $form_state;
        }
        else {
          $batch['form_state'] = array_intersect_key($form_state, array_flip(array('programmed', 'rebuild', 'storage', 'no_redirect', 'redirect')));
        }

947
        $batch['progressive'] = !$form_state['programmed'];
948
        batch_process();
949

950 951 952 953
        // 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.
954
      }
955

956 957 958
      // Set a flag to indicate the the form has been processed and executed.
      $form_state['executed'] = TRUE;

959 960
      // Redirect the form based on values in $form_state.
      drupal_redirect_form($form_state);
961
    }
962 963 964 965 966 967

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

968 969 970 971 972
    // 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.
973
    // However, for forms that have not been fully executed (e.g., Ajax
974 975 976 977 978
    // 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'].
979
    // @todo D8: Simplify this logic; considering Ajax and non-HTML front-ends,
980 981 982 983 984 985 986 987 988 989
    //   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);
    }
990
  }
991

992 993 994 995
  // 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(),
996
  // because form_builder() must run for each request to accommodate new user
997 998 999
  // 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'])) {
1000
    form_set_cache($form['#build_id'], $unprocessed_form, $form_state);
1001 1002 1003 1004
  }
}

/**
1005 1006 1007 1008
 * Prepares a structured form array.
 *
 * Adds required elements, executes any hook_form_alter functions, and
 * optionally inserts a validation token to prevent tampering.
1009 1010 1011 1012 1013 1014
 *
 * @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.
1015 1016 1017
 * @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.
1018
 */
1019
function drupal_prepare_form($form_id, &$form, &$form_state) {
1020 1021
  global $user;

1022
  $form['#type'] = 'form';
1023
  $form_state['programmed'] = isset($form_state['programmed']) ? $form_state['programmed'] : FALSE;
1024

1025 1026 1027
  // 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';
1028 1029
  }

1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043
  // 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',
1044 1045 1046 1047
    // 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'),
1048 1049
  );

1050 1051 1052 1053
  // 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.
1054 1055 1056 1057 1058 1059 1060 1061
  // 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) {
1062
      unset($form['#token']);
1063
    }
1064
    // Otherwise, generate a public token based on the form id.
1065
    else {
1066 1067 1068 1069 1070
      $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']),
1071 1072 1073 1074
        // 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_token'),
1075
      );
1076
    }
1077
  }
1078

1079
  if (isset($form_id)) {
1080 1081 1082
    $form['form_id'] = array(
      '#type' => 'hidden',
      '#value' => $form_id,
1083
      '#id' => drupal_html_id("edit-$form_id"),
1084 1085 1086 1087
      // 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_id'),
1088
    );
1089
  }
1090
  if (!isset($form['#id'])) {
1091
    $form['#id'] = drupal_html_id($form_id);
1092
  }
Steven Wittens's avatar
Steven Wittens committed
1093

1094
  $form += element_info('form');
1095
  $form += array('#tree' => FALSE, '#parents' => array());
1096

Dries's avatar
Dries committed
1097
  if (!isset($form['#validate'])) {
1098 1099
    // Ensure that modules can rely on #validate being set.
    $form['#validate'] = array();
1100
    if (isset($form_state['build_info']['callback_object'])) {
1101
      $form['#validate'][] = array($form_state['build_info']['callback_object'], 'validateForm');
1102
    }
1103
    // Check for a handler specific to $form_id.
1104
    elseif (function_exists($form_id . '_validate')) {
1105 1106 1107 1108 1109 1110
      $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
1111 1112 1113
    }
  }

1114
  if (!isset($form['#submit'])) {
1115 1116
    // Ensure that modules can rely on #submit being set.
    $form['#submit'] = array();
1117
    if (isset($form_state['build_info']['callback_object'])) {
1118
      $form['#submit'][] = array($form_state['build_info']['callback_object'], 'submitForm');
1119
    }
1120
    // Check for a handler specific to $form_id.
1121
    elseif (function_exists($form_id . '_submit')) {
1122 1123 1124 1125 1126 1127
      $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
1128 1129 1130
    }
  }

1131
  // If no #theme has been set, automatically apply theme suggestions.
1132 1133 1134
  // 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.
1135 1136 1137 1138
  if (!isset($form['#theme'])) {
    $form['#theme'] = array($form_id);
    if (isset($form_state['build_info']['base_form_id'])) {
      $form['#theme'][] = $form_state['build_info']['base_form_id'];
1139 1140 1141
    }
  }

1142 1143 1144 1145 1146 1147 1148 1149
  // Invoke hook_form_alter(), hook_form_BASE_FORM_ID_alter(), and
  // hook_form_FORM_ID_alter() implementations.
  $hooks = array('form');
  if (isset($form_state['build_info']['base_form_id'])) {
    $hooks[] = 'form_' . $form_state['build_info']['base_form_id'];
  }
  $hooks[] = 'form_' . $form_id;
  drupal_alter($hooks, $form, $form_state, $form_id);
1150 1151
}

1152 1153

/**
1154
 * Validates user-submitted form data in the $form_state array.
1155 1156 1157 1158 1159
 *
 * @param $form_id
 *   A unique string identifying the form for validation, submission,
 *   theming, and hook_form_alter functions.
 * @param $form
1160 1161 1162 1163 1164 1165 1166
 *   An associative array containing the structure of the form, which is passed
 *   by reference. Form validation handlers are able to alter the form structure
 *   (like #process and #after_build callbacks during form building) in case of
 *   a validation error. If a validation handler alters the form structure, it
 *   is responsible for validating the values of changed form elements in
 *   $form_state['values'] to prevent form submit handlers from receiving
 *   unvalidated values.
1167 1168 1169 1170
 * @param $form_state
 *   A keyed array containing the current state of the form. The current
 *   user-submitted data is stored in $form_state['values'], though
 *   form validation functions are passed an explicit copy of the
1171
 *   values for the sake of simplicity. Validation handlers can also use
1172
 *   $form_state to pass information on to submit handlers. For example:
1173
 *     $form_state['data_for_submission'] = $data;