www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Form/FormStateInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Form;
   4
   5 use Drupal\Core\Url;
   6 use Symfony\Component\HttpFoundation\Response;
   7
   8 /**
   9  * Provides an interface for an object containing the current state of a form.
  10  *
  11  * This is passed to all form related code so that the caller can use it to
  12  * examine what in the form changed when the form submission process is
  13  * complete. Furthermore, it may be used to store information related to the
  14  * processed data in the form, which will persist across page requests when the
  15  * 'cache' or 'rebuild' flag is set. See \Drupal\Core\Form\FormState for
  16  * documentation of the available flags.
  17  *
  18  * @see \Drupal\Core\Form\FormBuilderInterface
  19  * @see \Drupal\Core\Form\FormValidatorInterface
  20  * @see \Drupal\Core\Form\FormSubmitterInterface
  21  * @ingroup form_api
  22  */
  23 interface FormStateInterface {
  24
  25   /**
  26    * Returns a reference to the complete form array.
  27    *
  28    * @return array
  29    *   The complete form array.
  30    */
  31   public function &getCompleteForm();
  32
  33   /**
  34    * Stores the complete form array.
  35    *
  36    * @param array $complete_form
  37    *   The complete form array.
  38    *
  39    * @return $this
  40    */
  41   public function setCompleteForm(array &$complete_form);
  42
  43   /**
  44    * Ensures an include file is loaded whenever the form is processed.
  45    *
  46    * Example:
  47    * @code
  48    *   // Load node.admin.inc from Node module.
  49    *   $form_state->loadInclude('node', 'inc', 'node.admin');
  50    * @endcode
  51    *
  52    * Use this function instead of module_load_include() from inside a form
  53    * constructor or any form processing logic as it ensures that the include file
  54    * is loaded whenever the form is processed. In contrast to using
  55    * module_load_include() directly, this method makes sure the include file is
  56    * correctly loaded also if the form is cached.
  57    *
  58    * @param string $module
  59    *   The module to which the include file belongs.
  60    * @param string $type
  61    *   The include file's type (file extension).
  62    * @param string|null $name
  63    *   (optional) The base file name (without the $type extension). If omitted,
  64    *   $module is used; i.e., resulting in "$module.$type" by default.
  65    *
  66    * @return string|false
  67    *   The filepath of the loaded include file, or FALSE if the include file was
  68    *   not found or has been loaded already.
  69    *
  70    * @see module_load_include()
  71    */
  72   public function loadInclude($module, $type, $name = NULL);
  73
  74   /**
  75    * Returns an array representation of the cacheable portion of the form state.
  76    *
  77    * @return array
  78    *   The cacheable portion of the form state.
  79    */
  80   public function getCacheableArray();
  81
  82   /**
  83    * Sets the value of the form state.
  84    *
  85    * @param array $form_state_additions
  86    *   An array of values to add to the form state.
  87    *
  88    * @return $this
  89    */
  90   public function setFormState(array $form_state_additions);
  91
  92   /**
  93    * Sets a response for this form.
  94    *
  95    * If a response is set, it will be used during processing and returned
  96    * directly. The form will not be rebuilt or redirected.
  97    *
  98    * @param \Symfony\Component\HttpFoundation\Response $response
  99    *   The response to return.
 100    *
 101    * @return $this
 102    */
 103   public function setResponse(Response $response);
 104
 105   /**
 106    * Gets a response for this form.
 107    *
 108    * If a response is set, it will be used during processing and returned
 109    * directly. The form will not be rebuilt or redirected.
 110    *
 111    * @return \Symfony\Component\HttpFoundation\Response|null
 112    *   The response to return, or NULL.
 113    */
 114   public function getResponse();
 115
 116   /**
 117    * Sets the redirect for the form.
 118    *
 119    * @param string $route_name
 120    *   The name of the route
 121    * @param array $route_parameters
 122    *   (optional) An associative array of parameter names and values.
 123    * @param array $options
 124    *   (optional) An associative array of additional options. See
 125    *   \Drupal\Core\Url for the available keys.
 126    *
 127    * @return $this
 128    *
 129    * @see \Drupal\Core\Form\FormSubmitterInterface::redirectForm()
 130    */
 131   public function setRedirect($route_name, array $route_parameters = [], array $options = []);
 132
 133   /**
 134    * Sets the redirect URL for the form.
 135    *
 136    * @param \Drupal\Core\Url $url
 137    *   The URL to redirect to.
 138    *
 139    * @return $this
 140    *
 141    * @see \Drupal\Core\Form\FormSubmitterInterface::redirectForm()
 142    */
 143   public function setRedirectUrl(Url $url);
 144
 145   /**
 146    * Gets the value to use for redirecting after the form has been executed.
 147    *
 148    * @see \Drupal\Core\Form\FormSubmitterInterface::redirectForm()
 149    *
 150    * @return mixed
 151    *   The value will be one of the following:
 152    *   - A fully prepared \Symfony\Component\HttpFoundation\RedirectResponse.
 153    *   - An instance of \Drupal\Core\Url to use for the redirect.
 154    *   - NULL, to signify that no redirect was specified and that the current
 155    *     path should be used for the redirect.
 156    *   - FALSE, to signify that no redirect should take place.
 157    */
 158   public function getRedirect();
 159
 160   /**
 161    * Sets the entire set of arbitrary data.
 162    *
 163    * @param array $storage
 164    *   The entire set of arbitrary data to store for this form.
 165    *
 166    * @return $this
 167    */
 168   public function setStorage(array $storage);
 169
 170   /**
 171    * Returns the entire set of arbitrary data.
 172    *
 173    * @return array
 174    *   The entire set of arbitrary data to store for this form.
 175    */
 176   public function &getStorage();
 177
 178   /**
 179    * Gets any arbitrary property.
 180    *
 181    * @param string|array $property
 182    *   Properties are often stored as multi-dimensional associative arrays. If
 183    *   $property is a string, it will return $storage[$property]. If $property
 184    *   is an array, each element of the array will be used as a nested key. If
 185    *   $property = ['foo', 'bar'] it will return $storage['foo']['bar'].
 186    *
 187    * @return mixed
 188    *   A reference to the value for that property, or NULL if the property does
 189    *   not exist.
 190    */
 191   public function &get($property);
 192
 193   /**
 194    * Sets a value to an arbitrary property.
 195    *
 196    * @param string|array $property
 197    *   Properties are often stored as multi-dimensional associative arrays. If
 198    *   $property is a string, it will use $storage[$property] = $value. If
 199    *   $property is an array, each element of the array will be used as a nested
 200    *   key. If $property = ['foo', 'bar'] it will use
 201    *   $storage['foo']['bar'] = $value.
 202    * @param mixed $value
 203    *   The value to set.
 204    *
 205    * @return $this
 206    */
 207   public function set($property, $value);
 208
 209   /**
 210    * Determines if an arbitrary property is present.
 211    *
 212    * @param string $property
 213    *   Properties are often stored as multi-dimensional associative arrays. If
 214    *   $property is a string, it will return isset($storage[$property]). If
 215    *   $property is an array, each element of the array will be used as a nested
 216    *   key. If $property = ['foo', 'bar'] it will return
 217    *   isset($storage['foo']['bar']).
 218    */
 219   public function has($property);
 220
 221   /**
 222    * Sets the build info for the form.
 223    *
 224    * @param array $build_info
 225    *   An array of build info.
 226    *
 227    * @return $this
 228    *
 229    * @see \Drupal\Core\Form\FormState::$build_info
 230    */
 231   public function setBuildInfo(array $build_info);
 232
 233   /**
 234    * Returns the build info for the form.
 235    *
 236    * @return array
 237    *   An array of build info.
 238    *
 239    * @see \Drupal\Core\Form\FormState::$build_info
 240    */
 241   public function getBuildInfo();
 242
 243   /**
 244    * Adds a value to the build info.
 245    *
 246    * @param string $property
 247    *   The property to use for the value.
 248    * @param mixed $value
 249    *   The value to set.
 250    *
 251    * @return $this
 252    */
 253   public function addBuildInfo($property, $value);
 254
 255   /**
 256    * Returns the form values as they were submitted by the user.
 257    *
 258    * These are raw and unvalidated, so should not be used without a thorough
 259    * understanding of security implications. In almost all cases, code should
 260    * use self::getValues() and self::getValue() exclusively.
 261    *
 262    * @return array
 263    *   An associative array of values submitted to the form.
 264    */
 265   public function &getUserInput();
 266
 267   /**
 268    * Sets the form values as though they were submitted by a user.
 269    *
 270    * @param array $user_input
 271    *   An associative array of raw and unvalidated values.
 272    *
 273    * @return $this
 274    */
 275   public function setUserInput(array $user_input);
 276
 277   /**
 278    * Returns the submitted and sanitized form values.
 279    *
 280    * @return array
 281    *   An associative array of values submitted to the form.
 282    */
 283   public function &getValues();
 284
 285   /**
 286    * Returns the submitted form value for a specific key.
 287    *
 288    * @param string|array $key
 289    *   Values are stored as a multi-dimensional associative array. If $key is a
 290    *   string, it will return $values[$key]. If $key is an array, each element
 291    *   of the array will be used as a nested key. If $key = array('foo', 'bar')
 292    *   it will return $values['foo']['bar'].
 293    * @param mixed $default
 294    *   (optional) The default value if the specified key does not exist.
 295    *
 296    * @return mixed
 297    *   The value for the given key, or NULL.
 298    */
 299   public function &getValue($key, $default = NULL);
 300
 301   /**
 302    * Sets the submitted form values.
 303    *
 304    * This should be avoided, since these values have been validated already. Use
 305    * self::setUserInput() instead.
 306    *
 307    * @param array $values
 308    *   The multi-dimensional associative array of form values.
 309    *
 310    * @return $this
 311    */
 312   public function setValues(array $values);
 313
 314   /**
 315    * Sets the submitted form value for a specific key.
 316    *
 317    * @param string|array $key
 318    *   Values are stored as a multi-dimensional associative array. If $key is a
 319    *   string, it will use $values[$key] = $value. If $key is an array, each
 320    *   element of the array will be used as a nested key. If
 321    *   $key = array('foo', 'bar') it will use $values['foo']['bar'] = $value.
 322    * @param mixed $value
 323    *   The value to set.
 324    *
 325    * @return $this
 326    */
 327   public function setValue($key, $value);
 328
 329   /**
 330    * Removes a specific key from the submitted form values.
 331    *
 332    * @param string|array $key
 333    *   Values are stored as a multi-dimensional associative array. If $key is a
 334    *   string, it will use unset($values[$key]). If $key is an array, each
 335    *   element of the array will be used as a nested key. If
 336    *   $key = array('foo', 'bar') it will use unset($values['foo']['bar']).
 337    *
 338    * @return $this
 339    */
 340   public function unsetValue($key);
 341
 342   /**
 343    * Determines if a specific key is present in the submitted form values.
 344    *
 345    * @param string|array $key
 346    *   Values are stored as a multi-dimensional associative array. If $key is a
 347    *   string, it will return isset($values[$key]). If $key is an array, each
 348    *   element of the array will be used as a nested key. If
 349    *   $key = array('foo', 'bar') it will return isset($values['foo']['bar']).
 350    *
 351    * @return bool
 352    *   TRUE if the $key is set, FALSE otherwise.
 353    */
 354   public function hasValue($key);
 355
 356   /**
 357    * Determines if a specific key has a value in the submitted form values.
 358    *
 359    * @param string|array $key
 360    *   Values are stored as a multi-dimensional associative array. If $key is a
 361    *   string, it will return empty($values[$key]). If $key is an array, each
 362    *   element of the array will be used as a nested key. If
 363    *   $key = array('foo', 'bar') it will return empty($values['foo']['bar']).
 364    *
 365    * @return bool
 366    *   TRUE if the $key has no value, FALSE otherwise.
 367    */
 368   public function isValueEmpty($key);
 369
 370   /**
 371    * Changes submitted form values during form validation.
 372    *
 373    * Use this function to change the submitted value of a form element in a form
 374    * validation function, so that the changed value persists in $form_state
 375    * through to the submission handlers.
 376    *
 377    * Note that form validation functions are specified in the '#validate'
 378    * component of the form array (the value of $form['#validate'] is an array of
 379    * validation function names). If the form does not originate in your module,
 380    * you can implement hook_form_FORM_ID_alter() to add a validation function
 381    * to $form['#validate'].
 382    *
 383    * @param array $element
 384    *   The form element that should have its value updated; in most cases you
 385    *   can just pass in the element from the $form array, although the only
 386    *   component that is actually used is '#parents'. If constructing yourself,
 387    *   set $element['#parents'] to be an array giving the path through the form
 388    *   array's keys to the element whose value you want to update. For instance,
 389    *   if you want to update the value of $form['elem1']['elem2'], which should
 390    *   be stored in $form_state->getValue(array('elem1', 'elem2')), you would
 391    *   set $element['#parents'] = array('elem1','elem2').
 392    * @param mixed $value
 393    *   The new value for the form element.
 394    *
 395    * @return $this
 396    */
 397   public function setValueForElement(array $element, $value);
 398
 399   /**
 400    * Determines if any forms have any errors.
 401    *
 402    * @return bool
 403    *   TRUE if any form has any errors, FALSE otherwise.
 404    */
 405   public static function hasAnyErrors();
 406
 407   /**
 408    * Files an error against a form element.
 409    *
 410    * When a validation error is detected, the validator calls this method to
 411    * indicate which element needs to be changed and provide an error message.
 412    * This causes the Form API to not execute the form submit handlers, and
 413    * instead to re-display the form to the user with the corresponding elements
 414    * rendered with an 'error' CSS class (shown as red by default).
 415    *
 416    * The standard behavior of this method can be changed if a button provides
 417    * the #limit_validation_errors property. Multistep forms not wanting to
 418    * validate the whole form can set #limit_validation_errors on buttons to
 419    * limit validation errors to only certain elements. For example, pressing the
 420    * "Previous" button in a multistep form should not fire validation errors
 421    * just because the current step has invalid values. If
 422    * #limit_validation_errors is set on a clicked button, the button must also
 423    * define a #submit property (may be set to an empty array). Any #submit
 424    * handlers will be executed even if there is invalid input, so extreme care
 425    * should be taken with respect to any actions taken by them. This is
 426    * typically not a problem with buttons like "Previous" or "Add more" that do
 427    * not invoke persistent storage of the submitted form values. Do not use the
 428    * #limit_validation_errors property on buttons that trigger saving of form
 429    * values to the database.
 430    *
 431    * The #limit_validation_errors property is a list of "sections" within
 432    * $form_state->getValues() that must contain valid values. Each "section" is
 433    * an array with the ordered set of keys needed to reach that part of
 434    * $form_state->getValues() (i.e., the #parents property of the element).
 435    *
 436    * Example 1: Allow the "Previous" button to function, regardless of whether
 437    * any user input is valid.
 438    *
 439    * @code
 440    *   $form['actions']['previous'] = array(
 441    *     '#type' => 'submit',
 442    *     '#value' => t('Previous'),
 443    *     '#limit_validation_errors' => array(),       // No validation.
 444    *     '#submit' => array('some_submit_function'),  // #submit required.
 445    *   );
 446    * @endcode
 447    *
 448    * Example 2: Require some, but not all, user input to be valid to process the
 449    * submission of a "Previous" button.
 450    *
 451    * @code
 452    *   $form['actions']['previous'] = array(
 453    *     '#type' => 'submit',
 454    *     '#value' => t('Previous'),
 455    *     '#limit_validation_errors' => array(
 456    *       // Validate $form_state->getValue('step1').
 457    *       array('step1'),
 458    *       // Validate $form_state->getValue(array('foo', 'bar')).
 459    *       array('foo', 'bar'),
 460    *     ),
 461    *     '#submit' => array('some_submit_function'), // #submit required.
 462    *   );
 463    * @endcode
 464    *
 465    * This will require $form_state->getValue('step1') and everything within it
 466    * (for example, $form_state->getValue(array('step1', 'choice'))) to be valid,
 467    * so calls to self::setErrorByName('step1', $message) or
 468    * self::setErrorByName('step1][choice', $message) will prevent the submit
 469    * handlers from running, and result in the error message being displayed to
 470    * the user. However, calls to self::setErrorByName('step2', $message) and
 471    * self::setErrorByName('step2][groupX][choiceY', $message) will be
 472    * suppressed, resulting in the message not being displayed to the user, and
 473    * the submit handlers will run despite $form_state->getValue('step2') and
 474    * $form_state->getValue(array('step2', 'groupX', 'choiceY')) containing
 475    * invalid values. Errors for an invalid $form_state->getValue('foo') will be
 476    * suppressed, but errors flagging invalid values for
 477    * $form_state->getValue(array('foo', 'bar')) and everything within it will
 478    * be flagged and submission prevented.
 479    *
 480    * Partial form validation is implemented by suppressing errors rather than by
 481    * skipping the input processing and validation steps entirely, because some
 482    * forms have button-level submit handlers that call Drupal API functions that
 483    * assume that certain data exists within $form_state->getValues(), and while
 484    * not doing anything with that data that requires it to be valid, PHP errors
 485    * would be triggered if the input processing and validation steps were fully
 486    * skipped.
 487    *
 488    * @param string $name
 489    *   The name of the form element. If the #parents property of your form
 490    *   element is array('foo', 'bar', 'baz') then you may set an error on 'foo'
 491    *   or 'foo][bar][baz'. Setting an error on 'foo' sets an error for every
 492    *   element where the #parents array starts with 'foo'.
 493    * @param string $message
 494    *   (optional) The error message to present to the user.
 495    *
 496    * @return $this
 497    */
 498   public function setErrorByName($name, $message = '');
 499
 500   /**
 501    * Flags an element as having an error.
 502    *
 503    * @param array $element
 504    *   The form element.
 505    * @param string $message
 506    *   (optional) The error message to present to the user.
 507    *
 508    * @return $this
 509    */
 510   public function setError(array &$element, $message = '');
 511
 512   /**
 513    * Clears all errors against all form elements made by self::setErrorByName().
 514    */
 515   public function clearErrors();
 516
 517   /**
 518    * Returns an associative array of all errors.
 519    *
 520    * @return array
 521    *   An array of all errors, keyed by the name of the form element.
 522    */
 523   public function getErrors();
 524
 525   /**
 526    * Returns the error message filed against the given form element.
 527    *
 528    * Form errors higher up in the form structure override deeper errors as well
 529    * as errors on the element itself.
 530    *
 531    * @param array $element
 532    *   The form element to check for errors.
 533    *
 534    * @return string|null
 535    *   Either the error message for this element or NULL if there are no errors.
 536    */
 537   public function getError(array $element);
 538
 539   /**
 540    * Sets the form to be rebuilt after processing.
 541    *
 542    * @param bool $rebuild
 543    *   (optional) Whether the form should be rebuilt or not. Defaults to TRUE.
 544    *
 545    * @return $this
 546    */
 547   public function setRebuild($rebuild = TRUE);
 548
 549   /**
 550    * Determines if the form should be rebuilt after processing.
 551    *
 552    * @return bool
 553    *   TRUE if the form should be rebuilt, FALSE otherwise.
 554    */
 555   public function isRebuilding();
 556
 557   /**
 558    * Flags the form state as having or not an invalid token.
 559    *
 560    * @param bool $invalid_token
 561    *   Whether the form has an invalid token.
 562    *
 563    * @return $this
 564    */
 565   public function setInvalidToken($invalid_token);
 566
 567   /**
 568    * Determines if the form has an invalid token.
 569    *
 570    * @return bool
 571    *   TRUE if the form has an invalid token, FALSE otherwise.
 572    */
 573   public function hasInvalidToken();
 574
 575   /**
 576    * Converts support notations for a form callback to a valid callable.
 577    *
 578    * Specifically, supports methods on the form/callback object as strings when
 579    * they start with ::, for example "::submitForm()".
 580    *
 581    * @param string|array $callback
 582    *   The callback.
 583    *
 584    * @return array|string
 585    *   A valid callable.
 586    */
 587   public function prepareCallback($callback);
 588
 589   /**
 590    * Returns the form object that is responsible for building this form.
 591    *
 592    * @return \Drupal\Core\Form\FormInterface
 593    *   The form object.
 594    */
 595   public function getFormObject();
 596
 597   /**
 598    * Sets the form object that is responsible for building this form.
 599    *
 600    * @param \Drupal\Core\Form\FormInterface $form_object
 601    *   The form object.
 602    *
 603    * @return $this
 604    */
 605   public function setFormObject(FormInterface $form_object);
 606
 607   /**
 608    * Sets this form to always be processed.
 609    *
 610    * This should only be used on RESTful GET forms that do NOT write data, as
 611    * this could lead to security issues. It is useful so that searches do not
 612    * need to have a form_id in their query arguments to trigger the search.
 613    *
 614    * @param bool $always_process
 615    *   TRUE if the form should always be processed, FALSE otherwise.
 616    *
 617    * @return $this
 618    */
 619   public function setAlwaysProcess($always_process = TRUE);
 620
 621   /**
 622    * Determines if this form should always be processed.
 623    *
 624    * @return bool
 625    *   TRUE if the form should always be processed, FALSE otherwise.
 626    */
 627   public function getAlwaysProcess();
 628
 629   /**
 630    * Stores the submit and button elements for the form.
 631    *
 632    * @param array $buttons
 633    *   The submit and button elements.
 634    *
 635    * @return $this
 636    */
 637   public function setButtons(array $buttons);
 638
 639   /**
 640    * Returns the submit and button elements for the form.
 641    *
 642    * @return array
 643    *   The submit and button elements.
 644    */
 645   public function getButtons();
 646
 647   /**
 648    * Sets this form to be cached.
 649    *
 650    * @param bool $cache
 651    *   TRUE if the form should be cached, FALSE otherwise.
 652    *
 653    * @return $this
 654    *
 655    * @throws \LogicException
 656    *   If the current request is using an HTTP method that must not change
 657    *   state (e.g., GET).
 658    */
 659   public function setCached($cache = TRUE);
 660
 661   /**
 662    * Determines if the form should be cached.
 663    *
 664    * @return bool
 665    *   TRUE if the form should be cached, FALSE otherwise.
 666    */
 667   public function isCached();
 668
 669   /**
 670    * Prevents the form from being cached.
 671    *
 672    * @return $this
 673    */
 674   public function disableCache();
 675
 676   /**
 677    * Sets that the form was submitted and has been processed and executed.
 678    *
 679    * @return $this
 680    */
 681   public function setExecuted();
 682
 683   /**
 684    * Determines if the form was submitted and has been processed and executed.
 685    *
 686    * @return bool
 687    *   TRUE if the form was submitted and has been processed and executed.
 688    */
 689   public function isExecuted();
 690
 691   /**
 692    * Sets references to details elements to render them within vertical tabs.
 693    *
 694    * @param array $groups
 695    *   References to details elements to render them within vertical tabs.
 696    *
 697    * @return $this
 698    */
 699   public function setGroups(array $groups);
 700
 701   /**
 702    * Returns references to details elements to render them within vertical tabs.
 703    *
 704    * @return array
 705    */
 706   public function &getGroups();
 707
 708   /**
 709    * Sets that this form has a file element.
 710    *
 711    * @param bool $has_file_element
 712    *   Whether this form has a file element.
 713    *
 714    * @return $this
 715    */
 716   public function setHasFileElement($has_file_element = TRUE);
 717
 718   /**
 719    * Returns whether this form has a file element.
 720    *
 721    * @return bool
 722    *   Whether this form has a file element.
 723    */
 724   public function hasFileElement();
 725
 726   /**
 727    * Sets the limited validation error sections.
 728    *
 729    * @param array|null $limit_validation_errors
 730    *   The limited validation error sections.
 731    *
 732    * @return $this
 733    *
 734    * @see \Drupal\Core\Form\FormState::$limit_validation_errors
 735    */
 736   public function setLimitValidationErrors($limit_validation_errors);
 737
 738   /**
 739    * Retrieves the limited validation error sections.
 740    *
 741    * @return array|null
 742    *   The limited validation error sections.
 743    *
 744    * @see \Drupal\Core\Form\FormState::$limit_validation_errors
 745    */
 746   public function getLimitValidationErrors();
 747
 748   /**
 749    * Sets the HTTP method to use for the form's submission.
 750    *
 751    * This is what the form's "method" attribute should be, not necessarily what
 752    * the current request's HTTP method is. For example, a form can have a
 753    * method attribute of POST, but the request that initially builds it uses
 754    * GET.
 755    *
 756    * @param string $method
 757    *   Either "GET" or "POST". Other HTTP methods are not valid form submission
 758    *   methods.
 759    *
 760    * @see \Drupal\Core\Form\FormState::$method
 761    * @see \Drupal\Core\Form\FormStateInterface::setRequestMethod()
 762    *
 763    * @return $this
 764    */
 765   public function setMethod($method);
 766
 767   /**
 768    * Sets the HTTP method used by the request that is building the form.
 769    *
 770    * @param string $method
 771    *   Can be any valid HTTP method, such as GET, POST, HEAD, etc.
 772    *
 773    * @return $this
 774    *
 775    * @see \Drupal\Core\Form\FormStateInterface::setMethod()
 776    */
 777   public function setRequestMethod($method);
 778
 779   /**
 780    * Returns the HTTP form method.
 781    *
 782    * @param string $method_type
 783    *   The HTTP form method.
 784    *
 785    * @return bool
 786    *   TRUE if the HTTP form method matches.
 787    *
 788    * @see \Drupal\Core\Form\FormState::$method
 789    */
 790   public function isMethodType($method_type);
 791
 792   /**
 793    * Enforces that validation is run.
 794    *
 795    * @param bool $must_validate
 796    *   If TRUE, validation will always be run.
 797    *
 798    * @return $this
 799    */
 800   public function setValidationEnforced($must_validate = TRUE);
 801
 802   /**
 803    * Checks if validation is enforced.
 804    *
 805    * @return bool
 806    *   If TRUE, validation will always be run.
 807    */
 808   public function isValidationEnforced();
 809
 810   /**
 811    * Prevents the form from redirecting.
 812    *
 813    * @param bool $no_redirect
 814    *   If TRUE, the form will not redirect.
 815    *
 816    * @return $this
 817    */
 818   public function disableRedirect($no_redirect = TRUE);
 819
 820   /**
 821    * Determines if redirecting has been prevented.
 822    *
 823    * @return bool
 824    *   If TRUE, the form will not redirect.
 825    */
 826   public function isRedirectDisabled();
 827
 828   /**
 829    * Sets that the form should process input.
 830    *
 831    * @param bool $process_input
 832    *   If TRUE, the form input will be processed.
 833    *
 834    * @return $this
 835    */
 836   public function setProcessInput($process_input = TRUE);
 837
 838   /**
 839    * Determines if the form input will be processed.
 840    *
 841    * @return bool
 842    *   If TRUE, the form input will be processed.
 843    */
 844   public function isProcessingInput();
 845
 846   /**
 847    * Sets that this form was submitted programmatically.
 848    *
 849    * @param bool $programmed
 850    *   If TRUE, the form was submitted programmatically.
 851    *
 852    * @return $this
 853    */
 854   public function setProgrammed($programmed = TRUE);
 855
 856   /**
 857    * Returns if this form was submitted programmatically.
 858    *
 859    * @return bool
 860    *   If TRUE, the form was submitted programmatically.
 861    */
 862   public function isProgrammed();
 863
 864   /**
 865    * Sets if this form submission should bypass #access.
 866    *
 867    * @param bool $programmed_bypass_access_check
 868    *   If TRUE, programmatic form submissions are processed without taking
 869    *   #access into account.
 870    *
 871    * @return $this
 872    *
 873    * @see \Drupal\Core\Form\FormState::$programmed_bypass_access_check
 874    */
 875   public function setProgrammedBypassAccessCheck($programmed_bypass_access_check = TRUE);
 876
 877   /**
 878    * Determines if this form submission should bypass #access.
 879    *
 880    * @return bool
 881    *
 882    * @see \Drupal\Core\Form\FormState::$programmed_bypass_access_check
 883    */
 884   public function isBypassingProgrammedAccessChecks();
 885
 886   /**
 887    * Sets the rebuild info.
 888    *
 889    * @param array $rebuild_info
 890    *   The rebuild info.
 891    *
 892    * @return $this
 893    *
 894    * @see \Drupal\Core\Form\FormState::$rebuild_info
 895    */
 896   public function setRebuildInfo(array $rebuild_info);
 897
 898   /**
 899    * Gets the rebuild info.
 900    *
 901    * @return array
 902    *   The rebuild info.
 903    *
 904    * @see \Drupal\Core\Form\FormState::$rebuild_info
 905    */
 906   public function getRebuildInfo();
 907
 908   /**
 909    * Adds a value to the rebuild info.
 910    *
 911    * @param string $property
 912    *   The property to use for the value.
 913    * @param mixed $value
 914    *   The value to set.
 915    *
 916    * @return $this
 917    */
 918   public function addRebuildInfo($property, $value);
 919
 920   /**
 921    * Sets the submit handlers.
 922    *
 923    * @param array $submit_handlers
 924    *   An array of submit handlers.
 925    *
 926    * @return $this
 927    */
 928   public function setSubmitHandlers(array $submit_handlers);
 929
 930   /**
 931    * Gets the submit handlers.
 932    *
 933    * @return array
 934    *   An array of submit handlers.
 935    */
 936   public function getSubmitHandlers();
 937
 938   /**
 939    * Sets that the form has been submitted.
 940    *
 941    * @return $this
 942    */
 943   public function setSubmitted();
 944
 945   /**
 946    * Determines if the form has been submitted.
 947    *
 948    * @return bool
 949    *   TRUE if the form has been submitted, FALSE otherwise.
 950    */
 951   public function isSubmitted();
 952
 953   /**
 954    * Sets temporary data.
 955    *
 956    * @param array $temporary
 957    *   Temporary data accessible during the current page request only.
 958    *
 959    * @return $this
 960    */
 961   public function setTemporary(array $temporary);
 962
 963   /**
 964    * Gets temporary data.
 965    *
 966    * @return array
 967    *   Temporary data accessible during the current page request only.
 968    */
 969   public function getTemporary();
 970
 971   /**
 972    * Gets an arbitrary value from temporary storage.
 973    *
 974    * @param string|array $key
 975    *   Properties are often stored as multi-dimensional associative arrays. If
 976    *   $key is a string, it will return $temporary[$key]. If $key is an array,
 977    *   each element of the array will be used as a nested key. If
 978    *   $key = ['foo', 'bar'] it will return $temporary['foo']['bar'].
 979    *
 980    * @return mixed
 981    *   A reference to the value for that key, or NULL if the property does
 982    *   not exist.
 983    */
 984   public function &getTemporaryValue($key);
 985
 986   /**
 987    * Sets an arbitrary value in temporary storage.
 988    *
 989    * @param string|array $key
 990    *   Properties are often stored as multi-dimensional associative arrays. If
 991    *   $key is a string, it will use $temporary[$key] = $value. If $key is an
 992    *   array, each element of the array will be used as a nested key. If
 993    *   $key = ['foo', 'bar'] it will use $temporary['foo']['bar'] = $value.
 994    * @param mixed $value
 995    *   The value to set.
 996    *
 997    * @return $this
 998    */
 999   public function setTemporaryValue($key, $value);
1000
1001   /**
1002    * Determines if a temporary value is present.
1003    *
1004    * @param string $key
1005    *   Properties are often stored as multi-dimensional associative arrays. If
1006    *   $key is a string, it will return isset($temporary[$key]). If $key is an
1007    *   array, each element of the array will be used as a nested key. If
1008    *   $key = ['foo', 'bar'] it will return isset($temporary['foo']['bar']).
1009    */
1010   public function hasTemporaryValue($key);
1011
1012   /**
1013    * Sets the form element that triggered submission.
1014    *
1015    * @param array|null $triggering_element
1016    *   The form element that triggered submission, of NULL if there is none.
1017    *
1018    * @return $this
1019    */
1020   public function setTriggeringElement($triggering_element);
1021
1022   /**
1023    * Gets the form element that triggered submission.
1024    *
1025    * @return array|null
1026    *   The form element that triggered submission, of NULL if there is none.
1027    */
1028   public function &getTriggeringElement();
1029
1030   /**
1031    * Sets the validate handlers.
1032    *
1033    * @param array $validate_handlers
1034    *   An array of validate handlers.
1035    *
1036    * @return $this
1037    */
1038   public function setValidateHandlers(array $validate_handlers);
1039
1040   /**
1041    * Gets the validate handlers.
1042    *
1043    * @return array
1044    *   An array of validate handlers.
1045    */
1046   public function getValidateHandlers();
1047
1048   /**
1049    * Sets that validation has been completed.
1050    *
1051    * @param bool $validation_complete
1052    *   TRUE if validation is complete, FALSE otherwise.
1053    *
1054    * @return $this
1055    */
1056   public function setValidationComplete($validation_complete = TRUE);
1057
1058   /**
1059    * Determines if validation has been completed.
1060    *
1061    * @return bool
1062    *   TRUE if validation is complete, FALSE otherwise.
1063    */
1064   public function isValidationComplete();
1065
1066   /**
1067    * Gets the keys of the form values that will be cleaned.
1068    *
1069    * @return array
1070    *   An array of form value keys to be cleaned.
1071    */
1072   public function getCleanValueKeys();
1073
1074   /**
1075    * Sets the keys of the form values that will be cleaned.
1076    *
1077    * @param array $keys
1078    *   An array of form value keys to be cleaned.
1079    *
1080    * @return $this
1081    */
1082   public function setCleanValueKeys(array $keys);
1083
1084   /**
1085    * Adds a key to the array of form values that will be cleaned.
1086    *
1087    * @param string $key
1088    *   The form value key to be cleaned.
1089    *
1090    * @return $this
1091    */
1092   public function addCleanValueKey($key);
1093
1094   /**
1095    * Removes internal Form API elements and buttons from submitted form values.
1096    *
1097    * This function can be used when a module wants to store all submitted form
1098    * values, for example, by serializing them into a single database column. In
1099    * such cases, all internal Form API values and all form button elements
1100    * should not be contained, and this function allows their removal before the
1101    * module proceeds to storage. Next to button elements, the following internal
1102    * values are removed by default.
1103    * - form_id
1104    * - form_token
1105    * - form_build_id
1106    * - op
1107    *
1108    * @return $this
1109    */
1110   public function cleanValues();
1111
1112 }