form.inc 210 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\Crypt;
9
use Drupal\Component\Utility\NestedArray;
10
use Drupal\Core\Form\FormInterface;
11
use Drupal\Core\Form\BaseFormIdInterface;
12
use Drupal\Core\Database\Database;
13
use Drupal\Core\Language\Language;
14
use Drupal\Core\Template\Attribute;
15
use Drupal\Core\Datetime\DrupalDateTime;
16
use Drupal\Core\Utility\Color;
17 18 19 20
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
21

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

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

110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
/**
 * 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;
128 129 130
    if ($form_arg instanceof BaseFormIdInterface) {
      $form_state['build_info']['base_form_id'] = $form_arg->getBaseFormID();
    }
131 132 133 134 135 136 137
    return $form_arg->getFormID();
  }

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

138
/**
139 140 141 142 143
 * 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.
144
 *
145 146 147
 * @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
148 149 150 151
 *   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(),
152
 *   and search_forms().
153
 * @param ...
154
 *   Any additional arguments are passed on to the functions called by
155 156
 *   drupal_get_form(), including the unique form constructor function. For
 *   example, the node_edit form requires that a node object is passed in here
157
 *   when it is called. These are available to implementations of
158 159
 *   hook_form_alter() and hook_form_FORM_ID_alter() as the array
 *   $form_state['build_info']['args'].
160
 *
161
 * @return
162
 *   The form array.
163 164
 *
 * @see drupal_build_form()
165
 */
166
function drupal_get_form($form_arg) {
167
  $form_state = array();
168 169

  $args = func_get_args();
170
  // Remove $form_arg from the arguments.
171
  array_shift($args);
172
  $form_state['build_info']['args'] = $args;
173

174
  $form_id = _drupal_form_id($form_arg, $form_state);
175 176 177
  return drupal_build_form($form_id, $form_state);
}

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

355
  if (isset($_SESSION['batch_form_state'])) {
356 357
    // We've been redirected here after a batch processing. The form has
    // already been processed, but needs to be rebuilt. See _batch_finished().
358 359
    $form_state = $_SESSION['batch_form_state'];
    unset($_SESSION['batch_form_state']);
360
    return drupal_rebuild_form($form_id, $form_state);
361
  }
362

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

373 374 375 376 377 378 379 380 381
  // 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;
382
    }
383

384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404
    $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;
405
    }
406
  }
407

408 409 410 411 412 413 414 415 416 417 418
  // 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.
419 420 421 422 423 424
  $response = drupal_process_form($form_id, $form, $form_state);

  // If the form returns some kind of response, deliver it.
  if ($response instanceof Response) {
    _drupal_form_send_response($response);
  }
425 426 427 428 429 430 431 432 433

  // 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.
434
  return $form;
435
}
436

437
/**
438
 * Retrieves default values for the $form_state array.
439 440 441
 */
function form_state_defaults() {
  return array(
442
    'rebuild' => FALSE,
443
    'rebuild_info' => array(),
444
    'redirect' => NULL,
445 446 447 448 449 450
    // @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(),
    ),
451
    'temporary' => array(),
452
    'submitted' => FALSE,
453
    'executed' => FALSE,
454
    'programmed' => FALSE,
455 456
    'cache'=> FALSE,
    'method' => 'post',
457
    'groups' => array(),
458
    'buttons' => array(),
459 460 461
  );
}

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

504
  // If only parts of the form will be returned to the browser (e.g., Ajax or
505 506 507 508 509
  // 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.
510 511 512 513 514
  // @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 {
515
    $form['#build_id'] = 'form-' . Crypt::hashBase64(uniqid(mt_rand(), TRUE) . mt_rand());
516
  }
517

518
  // #action defaults to request_uri(), but in case of Ajax and other partial
519 520
  // rebuilds, the form is submitted to an alternate URL, and the original
  // #action needs to be retained.
521
  if (isset($old_form['#action']) && !empty($form_state['rebuild_info']['copy']['#action'])) {
522
    $form['#action'] = $old_form['#action'];
523
  }
524

525 526
  drupal_prepare_form($form_id, $form, $form_state);

527 528 529 530
  // 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.
531
  if (empty($form_state['no_cache'])) {
532
    form_set_cache($form['#build_id'], $form, $form_state);
533
  }
534

535 536
  // Clear out all group associations as these might be different when
  // re-rendering the form.
537 538
  $form_state['groups'] = array();

539 540
  // Return a fully built form that is ready for rendering.
  return form_builder($form_id, $form, $form_state);
541 542
}

543
/**
544
 * Fetches a form from the cache.
545 546
 */
function form_get_cache($form_build_id, &$form_state) {
547
  if ($form = Drupal::keyValueExpirable('form')->get($form_build_id)) {
548
    global $user;
549
    if ((isset($form['#cache_token']) && drupal_valid_token($form['#cache_token'])) || (!isset($form['#cache_token']) && $user->isAnonymous())) {
550
      if ($stored_form_state = Drupal::keyValueExpirable('form_state')->get($form_build_id)) {
551
        // Re-populate $form_state for subsequent rebuilds.
552
        $form_state = $stored_form_state + $form_state;
553

554
        // If the original form is contained in include files, load the files.
555
        // @see form_load_include()
556 557 558 559 560 561 562 563 564
        $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;
          }
565
        }
566 567
      }
      return $form;
568 569 570 571 572
    }
  }
}

/**
573
 * Stores a form in the cache.
574 575
 */
function form_set_cache($form_build_id, $form, $form_state) {
576 577
  // 6 hours cache life time for forms should be plenty.
  $expire = 21600;
578 579 580

  // Cache form structure.
  if (isset($form)) {
581
    if ($GLOBALS['user']->isAuthenticated()) {
582 583
      $form['#cache_token'] = drupal_get_token();
    }
584
    Drupal::keyValueExpirable('form')->setWithExpire($form_build_id, $form, $expire);
585
  }
586 587

  // Cache form state.
588
  if ($data = array_diff_key($form_state, array_flip(form_state_keys_no_cache()))) {
589
    Drupal::keyValueExpirable('form_state')->setWithExpire($form_build_id, $data, $expire);
590 591 592
  }
}

593 594 595 596 597 598 599 600 601
/**
 * 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',
602
    'rebuild_info',
603 604 605 606 607
    'redirect',
    'no_redirect',
    'temporary',
    // Internal properties defined by form processing.
    'buttons',
608
    'triggering_element',
609
    'complete_form',
610 611 612 613 614
    'groups',
    'input',
    'method',
    'submit_handlers',
    'submitted',
615
    'executed',
616 617 618 619 620
    'validate_handlers',
    'values',
  );
}

621
/**
622
 * Ensures an include file is loaded whenever the form is processed.
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 658 659 660 661 662 663 664 665 666 667 668 669
 *
 * 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;
}

670
/**
671 672 673 674 675 676 677 678
 * 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().
679
 *
680 681 682 683 684 685 686 687
 * @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().
688
 * @param $form_state
689 690 691 692 693 694 695
 *   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.
696
 * @param ...
697
 *   Any additional arguments are passed on to the functions called by
698
 *   drupal_form_submit(), including the unique form constructor function.
699
 *   For example, the node_edit form requires that a node object be passed
700 701 702 703 704 705 706 707 708 709 710 711 712 713
 *   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
714
 * For example:
715
 * @code
716
 * // register a new user
717 718 719
 * $form_state = array();
 * $form_state['values']['name'] = 'robo-user';
 * $form_state['values']['mail'] = 'robouser@example.com';
720 721
 * $form_state['values']['pass']['pass1'] = 'password';
 * $form_state['values']['pass']['pass2'] = 'password';
722
 * $form_state['values']['op'] = t('Create new account');
723
 * drupal_form_submit('user_register_form', $form_state);
724
 * @endcode
725
 */
726
function drupal_form_submit($form_arg, &$form_state) {
727
  if (!isset($form_state['build_info']['args'])) {
728 729 730
    $args = func_get_args();
    array_shift($args);
    array_shift($args);
731
    $form_state['build_info']['args'] = $args;
732
  }
733 734
  // Merge in default values.
  $form_state += form_state_defaults();
Dries's avatar
Dries committed
735

736 737 738 739
  // 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).
740
  $form_state['input'] = $form_state['values'];
741

742
  $form_state['programmed'] = TRUE;
743 744

  $form_id = _drupal_form_id($form_arg, $form_state);
745
  $form = drupal_retrieve_form($form_id, $form_state);
746 747
  // Programmed forms are always submitted.
  $form_state['submitted'] = TRUE;
748

749 750 751 752
  // Reset form validation.
  $form_state['must_validate'] = TRUE;
  form_clear_error();

753 754
  drupal_prepare_form($form_id, $form, $form_state);
  drupal_process_form($form_id, $form, $form_state);
755 756
}

757 758 759 760 761 762 763 764
/**
 * 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
765
 *   different $form_id values to the proper form constructor function.
766
 * @param $form_state
767 768 769
 *   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.
770
 */
771
function drupal_retrieve_form($form_id, &$form_state) {
772
  $forms = &drupal_static(__FUNCTION__);
773

774 775 776
  // Record the $form_id.
  $form_state['build_info']['form_id'] = $form_id;

777 778 779
  // 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
780 781 782
  // form_get_cache(). Don't do this in maintenance mode as Drupal may not be
  // fully bootstrapped (i.e. during installation) in which case
  // menu_get_item() is not available.
783 784 785
  if (!isset($form_state['build_info']['files']['menu']) && !defined('MAINTENANCE_MODE')) {
    $item = menu_get_item();
    if (!empty($item['include_file'])) {
786 787
      // Do not use form_load_include() here, as the file is already loaded.
      // Anyway, form_get_cache() is able to handle filepaths too.
788 789 790 791
      $form_state['build_info']['files']['menu'] = $item['include_file'];
    }
  }

792
  // We save two copies of the incoming arguments: one for modules to use
793
  // when mapping form ids to constructor functions, and another to pass to
794
  // the constructor function itself.
795
  $args = $form_state['build_info']['args'];
796

797 798
  // If an explicit form builder callback is defined we just use it, otherwise
  // we look for a function named after the $form_id.
799 800 801 802 803
  $callback = $form_id;
  if (!empty($form_state['build_info']['callback'])) {
    $callback = $form_state['build_info']['callback'];
  }
  elseif (!empty($form_state['build_info']['callback_object'])) {
804
    $callback = array($form_state['build_info']['callback_object'], 'buildForm');
805
  }
806 807

  // We first check to see if there is a valid form builder callback defined.
808
  // If there is, we simply pass the arguments on to it to get the form.
809
  if (!is_callable($callback)) {
810
    // In cases where many form_ids need to share a central constructor function,
811
    // such as the node editing form, modules can implement hook_forms(). It
812
    // maps one or more form_ids to the correct constructor functions.
813 814 815 816 817 818 819 820 821
    //
    // 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])) {
822
      $forms = module_invoke_all('forms', $form_id, $args);
823 824 825 826 827 828 829
    }
    $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'];
830
      $form_state['build_info']['base_form_id'] = $callback;
831
    }
832 833 834 835 836
    // 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'];
    }
837
  }
838

839
  $form = array();
840 841 842 843 844 845 846 847 848
  // 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']);
  }

849 850 851 852 853
  // 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);

854 855 856 857 858
  // 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
859
  // back/next/save buttons in multi-step form wizards. See drupal_build_form().
860
  if (isset($form_state['wrapper_callback'])) {
861 862 863
    $form = call_user_func_array($form_state['wrapper_callback'], $args);
    // Put the prepopulated $form into $args.
    $args[0] = $form;
864
  }
865

866 867
  // If $callback was returned by a hook_forms() implementation, call it.
  // Otherwise, call the function named after the form id.
868
  $form = call_user_func_array($callback, $args);
869 870 871 872
  // If the form returns some kind of response, deliver it.
  if ($form instanceof Response) {
    _drupal_form_send_response($form);
  }
873
  $form['#form_id'] = $form_id;
874

875
  return $form;
876 877 878
}

/**
879 880
 * Processes a form submission.
 *
881
 * This function is the heart of form API. The form gets built, validated and in
882
 * appropriate cases, submitted and rebuilt.
883 884 885
 *
 * @param $form_id
 *   The unique string identifying the current form.
886 887
 * @param $form
 *   An associative array containing the structure of the form.
888 889
 * @param $form_state
 *   A keyed array containing the current state of the form. This
Dries's avatar
Dries committed
890
 *   includes the current persistent storage data for the form, and
891 892 893
 *   any data passed along by earlier steps when displaying a
 *   multi-step form. Additional information, like the sanitized $_POST
 *   data, is also accumulated here.
894
 */
895 896 897
function drupal_process_form($form_id, &$form, &$form_state) {
  $form_state['values'] = array();

898 899 900 901 902 903 904 905 906 907 908 909 910
  // 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']);
    }
  }

911 912 913 914 915
  // 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;
916
  $form = form_builder($form_id, $form, $form_state);
917 918 919

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

922
    // drupal_html_id() maintains a cache of element IDs it has seen,
923
    // so it can prevent duplicates. We want to be sure we reset that
924
    // cache when a form is processed, so scenarios that result in
925 926
    // the form being built behind the scenes and again for the
    // browser don't increment all the element IDs needlessly.
927 928 929 930
    if (!form_get_errors()) {
      // In case of errors, do not break HTML IDs of other forms.
      drupal_static_reset('drupal_html_id');
    }
931

932 933
    if ($form_state['submitted'] && !form_get_errors() && !$form_state['rebuild']) {
      // Execute form submit handlers.
934 935 936
      form_execute_handlers('submit', $form, $form_state);

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

955
        $batch['progressive'] = !$form_state['programmed'];
956 957 958 959
        $response = batch_process();
        if ($batch['progressive']) {
          return $response;
        }
960

961 962 963 964
        // 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.
965
      }
966

967 968 969
      // Set a flag to indicate the the form has been processed and executed.
      $form_state['executed'] = TRUE;

970
      // Redirect the form based on values in $form_state.
971 972 973 974
      $redirect = drupal_redirect_form($form_state);
      if (is_object($redirect)) {
        return $redirect;
      }
975
    }
976 977 978 979 980 981

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

982 983 984 985 986
    // 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.
987
    // However, for forms that have not been fully executed (e.g., Ajax
988 989 990 991 992
    // 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'].
993
    // @todo D8: Simplify this logic; considering Ajax and non-HTML front-ends,
994 995 996 997 998 999 1000 1001 1002 1003
    //   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);
    }
1004
  }
1005

1006 1007 1008 1009
  // 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(),
1010
  // because form_builder() must run for each request to accommodate new user
1011 1012 1013
  // 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'])) {
1014
    form_set_cache($form['#build_id'], $unprocessed_form, $form_state);
1015 1016 1017 1018
  }
}

/**
1019 1020 1021 1022
 * Prepares a structured form array.
 *
 * Adds required elements, executes any hook_form_alter functions, and
 * optionally inserts a validation token to prevent tampering.
1023 1024 1025 1026 1027 1028
 *
 * @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.
1029 1030 1031
 * @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.
1032
 */
1033
function drupal_prepare_form($form_id, &$form, &$form_state) {
1034 1035
  global $user;

1036
  $form['#type'] = 'form';
1037
  $form_state['programmed'] = isset($form_state['programmed']) ? $form_state['programmed'] : FALSE;
1038

1039 1040 1041
  // 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';
1042 1043
  }

1044 1045 1046 1047 1048 1049 1050
  // 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'])) {
1051
    $form['#build_id'] = 'form-' . Crypt::hashBase64(uniqid(mt_rand(), TRUE) . mt_rand());
1052 1053 1054 1055 1056 1057
  }
  $form['form_build_id'] = array(
    '#type' => 'hidden',
    '#value' => $form['#build_id'],
    '#id' => $form['#build_id'],
    '#name' => 'form_build_id',
1058 1059 1060 1061
    // 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'),
1062 1063
  );

1064 1065 1066 1067
  // 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.
1068 1069 1070 1071
  // 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.
1072
  if ($user && $user->isAuthenticated() && !$form_state['programmed']) {
1073 1074 1075
    // 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) {
1076
      unset($form['#token']);
1077
    }
1078
    // Otherwise, generate a public token based on the form id.
1079
    else {
1080 1081 1082 1083 1084
      $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']),
1085 1086 1087 1088
        // 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'),
1089
      );
1090
    }
1091
  }
1092

1093
  if (isset($form_id)) {
1094 1095 1096
    $form['form_id'] = array(
      '#type' => 'hidden',
      '#value' => $form_id,
1097
      '#id' => drupal_html_id("edit-$form_id"),
1098 1099 1100 1101
      // 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'),
1102
    );
1103
  }
1104
  if (!isset($form['#id'])) {
1105
    $form['#id'] = drupal_html_id($form_id);
1106
  }
1107

1108
  $form += element_info('form');
1109
  $form += array('#tree' => FALSE, '#parents' => array());
1110

Dries's avatar
Dries committed
1111
  if (!isset($form['#validate'])) {
1112 1113
    // Ensure that modules can rely on #validate being set.
    $form['#validate'] = array();
1114
    if (isset($form_state['build_info']['callback_object'])) {
1115
      $form['#validate'][] = array($form_state['build_info']['callback_object'], 'validateForm');
1116
    }
1117
    // Check for a handler specific to $form_id.
1118
    elseif (function_exists($form_id . '_validate')) {
1119 1120 1121 1122 1123 1124
      $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
1125 1126 1127
    }
  }

1128
  if (!isset($form['#submit'])) {
1129 1130
    // Ensure that modules can rely on #submit being set.
    $form['#submit'] = array();
1131
    if (isset($form_state['build_info']['callback_object'])) {
1132
      $form['#submit'][] = array($form_state['build_info']['callback_object'], 'submitForm');
1133
    }
1134
    // Check for a handler specific to $form_id.
1135
    elseif (function_exists($form_id . '_submit')) {
1136 1137 1138 1139 1140 1141
      $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
1142 1143 1144
    }
  }