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

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

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

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

/**
98
99
100
101
102
 * Returns a renderable form array for a given form ID.
 *
 * This function should be used instead of drupal_build_form() when $form_state
 * is not needed (i.e., when initially rendering the form) and is often
 * used as a menu callback.
103
104
 *
 * @param $form_id
105
106
107
108
109
 *   The unique string identifying the desired form. If a function with that
 *   name exists, it is called to build the form array. Modules that need to
 *   generate the same form (or very similar forms) using different $form_ids
 *   can implement hook_forms(), which maps different $form_id values to the
 *   proper form constructor function. Examples may be found in node_forms(),
110
 *   and search_forms().
111
 * @param ...
112
 *   Any additional arguments are passed on to the functions called by
113
114
 *   drupal_get_form(), including the unique form constructor function. For
 *   example, the node_edit form requires that a node object is passed in here
115
 *   when it is called. These are available to implementations of
116
117
 *   hook_form_alter() and hook_form_FORM_ID_alter() as the array
 *   $form_state['build_info']['args'].
118
 *
119
 * @return
120
 *   The form array.
121
122
 *
 * @see drupal_build_form()
123
124
 */
function drupal_get_form($form_id) {
125
  $form_state = array();
126
127

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

  return drupal_build_form($form_id, $form_state);
}

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

  if (!isset($form_state['input'])) {
    $form_state['input'] = $form_state['method'] == 'get' ? $_GET : $_POST;
  }

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

318
319
320
321
322
323
324
325
  // If the incoming input contains a form_build_id, we'll check the cache for a
  // copy of the form in question. If it's there, we don't have to rebuild the
  // form to proceed. In addition, if there is stored form_state data from a
  // previous step, we'll retrieve it so it can be passed on to the form
  // processing code.
  $check_cache = isset($form_state['input']['form_id']) && $form_state['input']['form_id'] == $form_id && !empty($form_state['input']['form_build_id']);
  if ($check_cache) {
    $form = form_get_cache($form_state['input']['form_build_id'], $form_state);
326
327
  }

328
329
330
331
332
333
334
335
336
  // If the previous bit of code didn't result in a populated $form object, we
  // are hitting the form for the first time and we need to build it from
  // scratch.
  if (!isset($form)) {
    // If we attempted to serve the form from cache, uncacheable $form_state
    // keys need to be removed after retrieving and preparing the form, except
    // any that were already set prior to retrieving the form.
    if ($check_cache) {
      $form_state_before_retrieval = $form_state;
337
    }
338

339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
    $form = drupal_retrieve_form($form_id, $form_state);
    drupal_prepare_form($form_id, $form, $form_state);

    // form_set_cache() removes uncacheable $form_state keys defined in
    // form_state_keys_no_cache() in order for multi-step forms to work
    // properly. This means that form processing logic for single-step forms
    // using $form_state['cache'] may depend on data stored in those keys
    // during drupal_retrieve_form()/drupal_prepare_form(), but form
    // processing should not depend on whether the form is cached or not, so
    // $form_state is adjusted to match what it would be after a
    // form_set_cache()/form_get_cache() sequence. These exceptions are
    // allowed to survive here:
    // - always_process: Does not make sense in conjunction with form caching
    //   in the first place, since passing form_build_id as a GET parameter is
    //   not desired.
    // - temporary: Any assigned data is expected to survives within the same
    //   page request.
    if ($check_cache) {
      $uncacheable_keys = array_flip(array_diff(form_state_keys_no_cache(), array('always_process', 'temporary')));
      $form_state = array_diff_key($form_state, $uncacheable_keys);
      $form_state += $form_state_before_retrieval;
360
    }
361
  }
362

363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
  // Now that we have a constructed form, process it. This is where:
  // - Element #process functions get called to further refine $form.
  // - User input, if any, gets incorporated in the #value property of the
  //   corresponding elements and into $form_state['values'].
  // - Validation and submission handlers are called.
  // - If this submission is part of a multistep workflow, the form is rebuilt
  //   to contain the information of the next step.
  // - If necessary, the form and form state are cached or re-cached, so that
  //   appropriate information persists to the next page request.
  // All of the handlers in the pipeline receive $form_state by reference and
  // can use it to know or update information about the state of the form.
  drupal_process_form($form_id, $form, $form_state);

  // If this was a successful submission of a single-step form or the last step
  // of a multi-step form, then drupal_process_form() issued a redirect to
  // another page, or back to this page, but as a new request. Therefore, if
  // we're here, it means that this is either a form being viewed initially
  // before any user input, or there was a validation error requiring the form
  // to be re-displayed, or we're in a multi-step workflow and need to display
  // the form's next step. In any case, we have what we need in $form, and can
  // return it for rendering.
384
  return $form;
385
}
386

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

707
708
709
710
711
712
713
714
/**
 * Retrieves the structured array that defines a given form.
 *
 * @param $form_id
 *   The unique string identifying the desired form. If a function
 *   with that name exists, it is called to build the form array.
 *   Modules that need to generate the same form (or very similar forms)
 *   using different $form_ids can implement hook_forms(), which maps
715
 *   different $form_id values to the proper form constructor function.
716
 * @param $form_state
717
718
719
 *   A keyed array containing the current state of the form, including the
 *   additional arguments to drupal_get_form() or drupal_form_submit() in the
 *   'args' component of the array.
720
 */
721
function drupal_retrieve_form($form_id, &$form_state) {
722
  $forms = &drupal_static(__FUNCTION__);
723

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

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

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

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

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

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

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

807
  return $form;
808
809
810
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1070
1071
1072
1073
1074
1075
1076
1077
  // 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);
1078
1079
}

1080
1081

/**
1082
 * Validates user-submitted form data in the $form_state array.
1083
1084
1085
1086
1087
 *
 * @param $form_id
 *   A unique string identifying the form for validation, submission,
 *   theming, and hook_form_alter functions.
 * @param $form
1088
1089
1090
1091
1092
1093
1094
 *   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.
1095
1096
1097
1098
1099
1100
 * @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
 *   values for the sake of simplicity. Validation handlers can also
 *   $form_state to pass information on to submit handlers. For example:
1101
 *     $form_state['data_for_submission'] = $data;
1102
1103
1104
 *   This technique is useful when validation requires file parsing,
 *   web service requests, or other expensive requests that should
 *   not be repeated in the submission step.
1105
 */
1106
function drupal_validate_form($form_id, &$form, &$form_state) {
1107
  $validated_forms = &drupal_static(__FUNCTION__, array());
1108

1109
  if (isset($validated_forms[$form_id]) && empty($form_state['must_validate'])) {
1110
1111
    return;
  }
1112

1113
  // If the session token was set by drupal_prepare_form(), ensure that it
1114
  // matches the current user's session.
1115
  if (isset($form['#token'])) {
1116
    if (!drupal_valid_token($form_state['values']['form_token'], $form['#token'])) {
1117
1118
1119
1120
      $path = current_path();
      $query = drupal_get_query_parameters();
      $url = url($path, array('query' => $query));

1121
      // Setting this error will cause the form to fail validation.
1122
      form_set_error('form_token', t('The form has become outdated. Copy any unsaved work in the form below and then <a href="@link">reload this page</a>.', array('@link' => $url)));