You are here

class FormState in Drupal 8

Same name and namespace in other branches
  1. 9 core/lib/Drupal/Core/Form/FormState.php \Drupal\Core\Form\FormState

Stores information about the state of a form.

Hierarchy

Expanded class hierarchy of FormState

74 files declare their use of FormState
AggregatorPluginSettingsBaseTest.php in core/modules/aggregator/tests/src/Unit/Plugin/AggregatorPluginSettingsBaseTest.php
AreaDisplayLinkTest.php in core/modules/views/tests/src/Kernel/Handler/AreaDisplayLinkTest.php
AreaEntityTest.php in core/modules/views/tests/src/Kernel/Handler/AreaEntityTest.php
ArgumentValidateTest.php in core/modules/user/tests/src/Kernel/Views/ArgumentValidateTest.php
batch.inc in core/includes/batch.inc
Batch processing API for processes to run in multiple HTTP requests.

... See full list

File

core/lib/Drupal/Core/Form/FormState.php, line 12

Namespace

Drupal\Core\Form
View source
class FormState implements FormStateInterface {
  use FormStateValuesTrait;

  /**
   * Tracks if any errors have been set on any form.
   *
   * @var bool
   */
  protected static $anyErrors = FALSE;

  /**
   * 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.
   *
   * @see self::getCompleteForm()
   *
   * This property is uncacheable.
   *
   * @var array
   */
  protected $complete_form;

  /**
   * 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:
   *   - callback: The actual callback to be used to retrieve the form array.
   *     Can be any callable. If none is provided $form_id is used as the name
   *     of a function to call instead.
   *   - args: A list of arguments to pass to the form constructor.
   *   - 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
   *     automatically loaded by \Drupal::formBuilder()->getCache(). By default
   *     the current menu router item's 'file' definition is added, if any. Use
   *     self::loadInclude() to add include files from a form constructor.
   *   - form_id: Identification of the primary form being constructed and
   *     processed.
   *   - base_form_id: Identification for a base form, as declared in the form
   *     class's \Drupal\Core\Form\BaseFormIdInterface::getBaseFormId() method.
   *   - immutable: If this flag is set to TRUE, a new form build id is
   *     generated when the form is loaded from the cache. If it is subsequently
   *     saved to the cache again, it will have another cache id and therefore
   *     the original form and form-state will remain unaltered. This is
   *     important when page caching is enabled in order to prevent form state
   *     from leaking between anonymous users.
   *
   * @var array
   */
  protected $build_info = [
    'args' => [],
    'files' => [],
  ];

  /**
   * Similar to self::$build_info, but pertaining to
   * \Drupal\Core\Form\FormBuilderInterface::rebuildForm().
   *
   * This property is uncacheable.
   *
   * @var array
   */
  protected $rebuild_info = [];

  /**
   * Normally, after the entire form processing is completed and submit handlers
   * have run, a form is considered to be done and
   * \Drupal\Core\Form\FormSubmitterInterface::redirectForm() 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 immediately built and sent to the browser, instead of a
   * redirect. This is used for multi-step forms, such as wizards and
   * confirmation forms. Normally, self::$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 self::$rebuild to cause the form processing to bypass submit
   * handlers and rebuild the form instead, even if there are no validation
   * errors.
   *
   * This property is uncacheable.
   *
   * @see self::setRebuild()
   *
   * @var bool
   */
  protected $rebuild = FALSE;

  /**
   * If set to TRUE the form will skip calling form element value callbacks,
   * except for a select list of callbacks provided by Drupal core that are
   * known to be safe.
   *
   * This property is uncacheable.
   *
   * @see self::setInvalidToken()
   *
   * @var bool
   */
  protected $invalidToken = FALSE;

  /**
   * Used when a form needs to return some kind of a
   * \Symfony\Component\HttpFoundation\Response object, e.g., a
   * \Symfony\Component\HttpFoundation\BinaryFileResponse when triggering a
   * file download. If you use self::setRedirect() or self::setRedirectUrl(),
   * it will be used to build a
   * \Symfony\Component\HttpFoundation\RedirectResponse and will populate this
   * key.
   *
   * @var \Symfony\Component\HttpFoundation\Response|null
   */
  protected $response;

  /**
   * Used to redirect the form on submission.
   *
   * @see self::getRedirect()
   *
   * This property is uncacheable.
   *
   * @var \Drupal\Core\Url|\Symfony\Component\HttpFoundation\RedirectResponse|null
   */
  protected $redirect;

  /**
   * If set to TRUE the form will NOT perform a redirect, even if
   * self::$redirect is set.
   *
   * This property is uncacheable.
   *
   * @var bool
   */
  protected $no_redirect;

  /**
   * 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 forms that do
   * not change data, as that is exclusively the domain of 'POST.'
   *
   * This property is uncacheable.
   *
   * @var string
   */
  protected $method = 'POST';

  /**
   * The HTTP method used by the request building or processing this form.
   *
   * May be any valid HTTP method. Defaults to 'GET', because even though
   * $method is 'POST' for most forms, the form's initial build is usually
   * performed as part of a GET request.
   *
   * This property is uncacheable.
   *
   * @var string
   */
  protected $requestMethod = 'GET';

  /**
   * If set to TRUE the original, unprocessed form structure will be 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
   * \Drupal\Core\Render\Element\RenderElement::processAjaxForm()
   * 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
   * self::$rebuild flag set, regardless of the value for self::$cache.
   *
   * @var bool
   */
  protected $cache = FALSE;

  /**
   * If set to TRUE the form will NOT be cached, even if 'cache' is set.
   *
   * @var bool
   */
  protected $no_cache;

  /**
   * 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 #tree determines whether the values are a
   * flat array or an array whose structure parallels the $form array. See
   * \Drupal\Core\Render\Element\FormElement for more information.)
   *
   * This property is uncacheable.
   *
   * @var array
   */
  protected $values = [];

  /**
   * An associative array of form value keys to be removed by cleanValues().
   *
   * Any values that are temporary but must still be displayed as values in
   * the rendered form should be added to this array using addCleanValueKey().
   * Initialized with internal Form API values.
   *
   * This property is uncacheable.
   *
   * @var array
   */
  protected $cleanValueKeys = [
    'form_id',
    'form_token',
    'form_build_id',
    'op',
  ];

  /**
   * 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 \Drupal::request()->request or
   * \Drupal::request()->query, depending on the 'method' chosen.
   *
   * This property is uncacheable.
   *
   * @var array|null
   *   The submitted user input array, or NULL if no input was submitted yet.
   */
  protected $input;

  /**
   * If TRUE and the method is GET, a form_id is not necessary.
   *
   * This property is uncacheable.
   *
   * @var bool
   */
  protected $always_process;

  /**
   * Ordinarily, a form is only validated once, but there are times when a form
   * is resubmitted internally and should be validated again. Setting this to
   * TRUE will force that to happen. This is most likely to occur during Ajax
   * operations.
   *
   * This property is uncacheable.
   *
   * @var bool
   */
  protected $must_validate;

  /**
   * If TRUE, the form was submitted programmatically, usually invoked via
   * \Drupal\Core\Form\FormBuilderInterface::submitForm(). Defaults to FALSE.
   *
   * @var bool
   */
  protected $programmed = FALSE;

  /**
   * If TRUE, programmatic form submissions are processed without taking #access
   * into account. Set this to FALSE when submitting a form programmatically
   * with values that may have been input by the user executing the current
   * request; this will cause #access to be respected as it would on a normal
   * form submission. Defaults to TRUE.
   *
   * @var bool
   */
  protected $programmed_bypass_access_check = TRUE;

  /**
   * TRUE signifies correct form submission. This is always TRUE for programmed
   * forms coming from \Drupal\Core\Form\FormBuilderInterface::submitForm() (see
   * 'programmed' key), or if the form_id coming from the
   * \Drupal::request()->request data is set and matches the current form_id.
   *
   * @var bool
   */
  protected $process_input;

  /**
   * If TRUE, the form has been submitted. Defaults to FALSE.
   *
   * This property is uncacheable.
   *
   * @var bool
   */
  protected $submitted = FALSE;

  /**
   * If TRUE, the form was submitted and has been processed and executed.
   *
   * This property is uncacheable.
   *
   * @var bool
   */
  protected $executed = FALSE;

  /**
   * The form element that triggered 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.
   *
   * This property is uncacheable.
   *
   * @var array|null
   */
  protected $triggering_element;

  /**
   * If TRUE, there is a file element and Form API will set the appropriate
   * 'enctype' HTML attribute on the form.
   *
   * @var bool
   */
  protected $has_file_element;

  /**
   * Contains references to details elements to render them within vertical tabs.
   *
   * This property is uncacheable.
   *
   * @var array
   */
  protected $groups = [];

  /**
   * This 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
   * entity form classes use $this->entity in entity forms, or
   * $form_state->getFormObject()->getEntity() outside the controller, to store
   * information about the entity being edited, and this information stays
   * available across successive clicks of the "Preview" button (if available)
   * as well as when the "Save" button is finally clicked.
   *
   * @var array
   */
  protected $storage = [];

  /**
   * A list containing copies of all submit and button elements in the form.
   *
   * This property is uncacheable.
   *
   * @var array
   */
  protected $buttons = [];

  /**
   * Holds temporary data accessible during the current page request only.
   *
   * All $form_state properties that are not reserved keys (see
   * other properties marked as uncacheable) 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.
   *
   * This property is uncacheable.
   *
   * @var array
   */
  protected $temporary = [];

  /**
   * Tracks if the form has finished validation.
   *
   * This property is uncacheable.
   *
   * @var bool
   */
  protected $validation_complete = FALSE;

  /**
   * Contains errors for this form.
   *
   * This property is uncacheable.
   *
   * @var array
   */
  protected $errors = [];

  /**
   * Stores which errors should be limited during validation.
   *
   * An array of "sections" within which user input must be valid. If the
   * element is within one of these sections, the error must be recorded.
   * Otherwise, it can be suppressed. self::$limit_validation_errors can be an
   * empty array, in which case all errors are suppressed. For example, a
   * "Previous" button might want its submit action to be triggered even if none
   * of the submitted values are valid.
   *
   * This property is uncacheable.
   *
   * @var array|null
   */
  protected $limit_validation_errors;

  /**
   * Stores the gathered validation handlers.
   *
   * This property is uncacheable.
   *
   * @var array
   */
  protected $validate_handlers = [];

  /**
   * Stores the gathered submission handlers.
   *
   * This property is uncacheable.
   *
   * @var array
   */
  protected $submit_handlers = [];

  /**
   * {@inheritdoc}
   */
  public function setFormState(array $form_state_additions) {
    foreach ($form_state_additions as $key => $value) {
      if (property_exists($this, $key)) {
        $this->{$key} = $value;
      }
      else {
        $this
          ->set($key, $value);
      }
    }
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function setAlwaysProcess($always_process = TRUE) {
    $this->always_process = (bool) $always_process;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getAlwaysProcess() {
    return $this->always_process;
  }

  /**
   * {@inheritdoc}
   */
  public function setButtons(array $buttons) {
    $this->buttons = $buttons;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getButtons() {
    return $this->buttons;
  }

  /**
   * {@inheritdoc}
   */
  public function setCached($cache = TRUE) {

    // Persisting $form_state is a side-effect disallowed during a "safe" HTTP
    // method.
    if ($cache && $this
      ->isRequestMethodSafe()) {
      throw new \LogicException(sprintf('Form state caching on %s requests is not allowed.', $this->requestMethod));
    }
    $this->cache = (bool) $cache;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isCached() {
    return empty($this->no_cache) && $this->cache;
  }

  /**
   * {@inheritdoc}
   */
  public function disableCache() {
    $this->no_cache = TRUE;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function setExecuted() {
    $this->executed = TRUE;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isExecuted() {
    return $this->executed;
  }

  /**
   * {@inheritdoc}
   */
  public function setGroups(array $groups) {
    $this->groups = $groups;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function &getGroups() {
    return $this->groups;
  }

  /**
   * {@inheritdoc}
   */
  public function setHasFileElement($has_file_element = TRUE) {
    $this->has_file_element = (bool) $has_file_element;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function hasFileElement() {
    return $this->has_file_element;
  }

  /**
   * {@inheritdoc}
   */
  public function setLimitValidationErrors($limit_validation_errors) {
    $this->limit_validation_errors = $limit_validation_errors;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getLimitValidationErrors() {
    return $this->limit_validation_errors;
  }

  /**
   * {@inheritdoc}
   */
  public function setMethod($method) {
    $this->method = strtoupper($method);
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isMethodType($method_type) {
    return $this->method === strtoupper($method_type);
  }

  /**
   * {@inheritdoc}
   */
  public function setRequestMethod($method) {
    $this->requestMethod = strtoupper($method);
    return $this;
  }

  /**
   * Checks whether the request method is a "safe" HTTP method.
   *
   * Link below defines GET and HEAD as "safe" methods, meaning they SHOULD NOT
   * have side-effects, such as persisting $form_state changes.
   *
   * @return bool
   *
   * @see \Symfony\Component\HttpFoundation\Request::isMethodSafe()
   * @see http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
   */
  protected function isRequestMethodSafe() {
    return in_array($this->requestMethod, [
      'GET',
      'HEAD',
    ]);
  }

  /**
   * {@inheritdoc}
   */
  public function setValidationEnforced($must_validate = TRUE) {
    $this->must_validate = (bool) $must_validate;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isValidationEnforced() {
    return $this->must_validate;
  }

  /**
   * {@inheritdoc}
   */
  public function disableRedirect($no_redirect = TRUE) {
    $this->no_redirect = (bool) $no_redirect;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isRedirectDisabled() {
    return $this->no_redirect;
  }

  /**
   * {@inheritdoc}
   */
  public function setProcessInput($process_input = TRUE) {
    $this->process_input = (bool) $process_input;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isProcessingInput() {
    return $this->process_input;
  }

  /**
   * {@inheritdoc}
   */
  public function setProgrammed($programmed = TRUE) {
    $this->programmed = (bool) $programmed;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isProgrammed() {
    return $this->programmed;
  }

  /**
   * {@inheritdoc}
   */
  public function setProgrammedBypassAccessCheck($programmed_bypass_access_check = TRUE) {
    $this->programmed_bypass_access_check = (bool) $programmed_bypass_access_check;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isBypassingProgrammedAccessChecks() {
    return $this->programmed_bypass_access_check;
  }

  /**
   * {@inheritdoc}
   */
  public function setRebuildInfo(array $rebuild_info) {
    $this->rebuild_info = $rebuild_info;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getRebuildInfo() {
    return $this->rebuild_info;
  }

  /**
   * {@inheritdoc}
   */
  public function addRebuildInfo($property, $value) {
    $rebuild_info = $this
      ->getRebuildInfo();
    $rebuild_info[$property] = $value;
    $this
      ->setRebuildInfo($rebuild_info);
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function setStorage(array $storage) {
    $this->storage = $storage;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function &getStorage() {
    return $this->storage;
  }

  /**
   * {@inheritdoc}
   */
  public function setSubmitHandlers(array $submit_handlers) {
    $this->submit_handlers = $submit_handlers;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getSubmitHandlers() {
    return $this->submit_handlers;
  }

  /**
   * {@inheritdoc}
   */
  public function setSubmitted() {
    $this->submitted = TRUE;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isSubmitted() {
    return $this->submitted;
  }

  /**
   * {@inheritdoc}
   */
  public function setTemporary(array $temporary) {
    $this->temporary = $temporary;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getTemporary() {
    return $this->temporary;
  }

  /**
   * {@inheritdoc}
   */
  public function &getTemporaryValue($key) {
    $value =& NestedArray::getValue($this->temporary, (array) $key);
    return $value;
  }

  /**
   * {@inheritdoc}
   */
  public function setTemporaryValue($key, $value) {
    NestedArray::setValue($this->temporary, (array) $key, $value, TRUE);
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function hasTemporaryValue($key) {
    $exists = NULL;
    NestedArray::getValue($this->temporary, (array) $key, $exists);
    return $exists;
  }

  /**
   * {@inheritdoc}
   */
  public function setTriggeringElement($triggering_element) {
    $this->triggering_element = $triggering_element;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function &getTriggeringElement() {
    return $this->triggering_element;
  }

  /**
   * {@inheritdoc}
   */
  public function setValidateHandlers(array $validate_handlers) {
    $this->validate_handlers = $validate_handlers;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getValidateHandlers() {
    return $this->validate_handlers;
  }

  /**
   * {@inheritdoc}
   */
  public function setValidationComplete($validation_complete = TRUE) {
    $this->validation_complete = (bool) $validation_complete;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isValidationComplete() {
    return $this->validation_complete;
  }

  /**
   * {@inheritdoc}
   */
  public function loadInclude($module, $type, $name = NULL) {
    if (!isset($name)) {
      $name = $module;
    }
    $build_info = $this
      ->getBuildInfo();
    if (!isset($build_info['files']["{$module}:{$name}.{$type}"])) {

      // Only add successfully included files to the form state.
      if ($result = $this
        ->moduleLoadInclude($module, $type, $name)) {
        $build_info['files']["{$module}:{$name}.{$type}"] = [
          'type' => $type,
          'module' => $module,
          'name' => $name,
        ];
        $this
          ->setBuildInfo($build_info);
        return $result;
      }
    }
    return FALSE;
  }

  /**
   * {@inheritdoc}
   */
  public function getCacheableArray() {
    return [
      'build_info' => $this
        ->getBuildInfo(),
      'response' => $this
        ->getResponse(),
      'programmed' => $this
        ->isProgrammed(),
      'programmed_bypass_access_check' => $this
        ->isBypassingProgrammedAccessChecks(),
      'process_input' => $this
        ->isProcessingInput(),
      'has_file_element' => $this
        ->hasFileElement(),
      'storage' => $this
        ->getStorage(),
      // Use the properties directly, since self::isCached() combines them and
      // cannot be relied upon.
      'cache' => $this->cache,
      'no_cache' => $this->no_cache,
    ];
  }

  /**
   * {@inheritdoc}
   */
  public function setCompleteForm(array &$complete_form) {
    $this->complete_form =& $complete_form;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function &getCompleteForm() {
    return $this->complete_form;
  }

  /**
   * {@inheritdoc}
   */
  public function &get($property) {
    $value =& NestedArray::getValue($this->storage, (array) $property);
    return $value;
  }

  /**
   * {@inheritdoc}
   */
  public function set($property, $value) {
    NestedArray::setValue($this->storage, (array) $property, $value, TRUE);
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function has($property) {
    $exists = NULL;
    NestedArray::getValue($this->storage, (array) $property, $exists);
    return $exists;
  }

  /**
   * {@inheritdoc}
   */
  public function setBuildInfo(array $build_info) {
    $this->build_info = $build_info;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getBuildInfo() {
    return $this->build_info;
  }

  /**
   * {@inheritdoc}
   */
  public function addBuildInfo($property, $value) {
    $build_info = $this
      ->getBuildInfo();
    $build_info[$property] = $value;
    $this
      ->setBuildInfo($build_info);
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function &getUserInput() {
    return $this->input;
  }

  /**
   * {@inheritdoc}
   */
  public function setUserInput(array $user_input) {
    $this->input = $user_input;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function &getValues() {
    return $this->values;
  }

  /**
   * {@inheritdoc}
   */
  public function setResponse(Response $response) {
    $this->response = $response;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getResponse() {
    return $this->response;
  }

  /**
   * {@inheritdoc}
   */
  public function setRedirect($route_name, array $route_parameters = [], array $options = []) {
    $url = new Url($route_name, $route_parameters, $options);
    return $this
      ->setRedirectUrl($url);
  }

  /**
   * {@inheritdoc}
   */
  public function setRedirectUrl(Url $url) {
    $this->redirect = $url;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getRedirect() {

    // Skip redirection for form submissions invoked via
    // \Drupal\Core\Form\FormBuilderInterface::submitForm().
    if ($this
      ->isProgrammed()) {
      return FALSE;
    }

    // Skip redirection if rebuild is activated.
    if ($this
      ->isRebuilding()) {
      return FALSE;
    }

    // Skip redirection if it was explicitly disallowed.
    if ($this
      ->isRedirectDisabled()) {
      return FALSE;
    }
    return $this->redirect;
  }

  /**
   * Sets the global status of errors.
   *
   * @param bool $errors
   *   TRUE if any form has any errors, FALSE otherwise.
   */
  protected static function setAnyErrors($errors = TRUE) {
    static::$anyErrors = $errors;
  }

  /**
   * {@inheritdoc}
   */
  public static function hasAnyErrors() {
    return static::$anyErrors;
  }

  /**
   * {@inheritdoc}
   */
  public function setErrorByName($name, $message = '') {
    if ($this
      ->isValidationComplete()) {
      throw new \LogicException('Form errors cannot be set after form validation has finished.');
    }
    $errors = $this
      ->getErrors();
    if (!isset($errors[$name])) {
      $record = TRUE;
      $limit_validation_errors = $this
        ->getLimitValidationErrors();
      if ($limit_validation_errors !== NULL) {
        $record = FALSE;
        foreach ($limit_validation_errors as $section) {

          // Exploding by '][' reconstructs the element's #parents. If the
          // reconstructed #parents begin with the same keys as the specified
          // section, then the element's values are within the part of
          // $form_state->getValues() that the clicked button requires to be
          // valid, so errors for this element must be recorded. As the exploded
          // array will all be strings, we need to cast every value of the
          // section array to string.
          if (array_slice(explode('][', $name), 0, count($section)) === array_map('strval', $section)) {
            $record = TRUE;
            break;
          }
        }
      }
      if ($record) {
        $errors[$name] = $message;
        $this->errors = $errors;
        static::setAnyErrors();
      }
    }
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function setError(array &$element, $message = '') {
    $this
      ->setErrorByName(implode('][', $element['#parents']), $message);
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function clearErrors() {
    $this->errors = [];
    static::setAnyErrors(FALSE);
  }

  /**
   * {@inheritdoc}
   */
  public function getError(array $element) {
    if ($errors = $this
      ->getErrors()) {
      $parents = [];
      foreach ($element['#parents'] as $parent) {
        $parents[] = $parent;
        $key = implode('][', $parents);
        if (isset($errors[$key])) {
          return $errors[$key];
        }
      }
    }
  }

  /**
   * {@inheritdoc}
   */
  public function getErrors() {
    return $this->errors;
  }

  /**
   * {@inheritdoc}
   */
  public function setRebuild($rebuild = TRUE) {
    $this->rebuild = $rebuild;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function isRebuilding() {
    return $this->rebuild;
  }

  /**
   * {@inheritdoc}
   */
  public function prepareCallback($callback) {
    if (is_string($callback) && substr($callback, 0, 2) == '::') {
      $callback = [
        $this
          ->getFormObject(),
        substr($callback, 2),
      ];
    }
    return $callback;
  }

  /**
   * {@inheritdoc}
   */
  public function setFormObject(FormInterface $form_object) {
    $this
      ->addBuildInfo('callback_object', $form_object);
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getFormObject() {
    return $this
      ->getBuildInfo()['callback_object'];
  }

  /**
   * {@inheritdoc}
   */
  public function getCleanValueKeys() {
    return $this->cleanValueKeys;
  }

  /**
   * {@inheritdoc}
   */
  public function setCleanValueKeys(array $cleanValueKeys) {
    $this->cleanValueKeys = $cleanValueKeys;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function addCleanValueKey($cleanValueKey) {
    $keys = $this
      ->getCleanValueKeys();
    $this
      ->setCleanValueKeys(array_merge((array) $keys, [
      $cleanValueKey,
    ]));
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function cleanValues() {
    foreach ($this
      ->getCleanValueKeys() as $value) {
      $this
        ->unsetValue($value);
    }

    // Remove button values.
    // \Drupal::formBuilder()->doBuildForm() collects all button elements in a
    // form. We remove the button value separately for each button element.
    foreach ($this
      ->getButtons() as $button) {

      // Remove this button's value from the submitted form values by finding
      // the value corresponding to this button.
      // We iterate over the #parents of this button and move a reference to
      // each parent in self::getValues(). For example, if #parents is:
      //   array('foo', 'bar', 'baz')
      // then the corresponding self::getValues() part will look like this:
      // array(
      //   'foo' => array(
      //     'bar' => array(
      //       'baz' => 'button_value',
      //     ),
      //   ),
      // )
      // We start by (re)moving 'baz' to $last_parent, so we are able unset it
      // at the end of the iteration. Initially, $values will contain a
      // reference to self::getValues(), but in the iteration we move the
      // reference to self::getValue('foo'), and finally to
      // self::getValue(array('foo', 'bar')), which is the level where we
      // can unset 'baz' (that is stored in $last_parent).
      $parents = $button['#parents'];
      $last_parent = array_pop($parents);
      $key_exists = NULL;
      $values =& NestedArray::getValue($this
        ->getValues(), $parents, $key_exists);
      if ($key_exists && is_array($values)) {
        unset($values[$last_parent]);
      }
    }
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function setInvalidToken($invalid_token) {
    $this->invalidToken = (bool) $invalid_token;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function hasInvalidToken() {
    return $this->invalidToken;
  }

  /**
   * Wraps ModuleHandler::loadInclude().
   */
  protected function moduleLoadInclude($module, $type, $name = NULL) {
    return \Drupal::moduleHandler()
      ->loadInclude($module, $type, $name);
  }

}

Members

Namesort descending Modifiers Type Description Overrides
FormState::$always_process protected property If TRUE and the method is GET, a form_id is not necessary.
FormState::$anyErrors protected static property Tracks if any errors have been set on any form.
FormState::$build_info protected property 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:
FormState::$buttons protected property A list containing copies of all submit and button elements in the form.
FormState::$cache protected property If set to TRUE the original, unprocessed form structure will be 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…
FormState::$cleanValueKeys protected property An associative array of form value keys to be removed by cleanValues().
FormState::$complete_form protected property The complete form structure.
FormState::$errors protected property Contains errors for this form.
FormState::$executed protected property If TRUE, the form was submitted and has been processed and executed.
FormState::$groups protected property Contains references to details elements to render them within vertical tabs.
FormState::$has_file_element protected property If TRUE, there is a file element and Form API will set the appropriate 'enctype' HTML attribute on the form.
FormState::$input protected property The array of values as they were submitted by the user.
FormState::$invalidToken protected property If set to TRUE the form will skip calling form element value callbacks, except for a select list of callbacks provided by Drupal core that are known to be safe.
FormState::$limit_validation_errors protected property Stores which errors should be limited during validation.
FormState::$method protected property The HTTP form method to use for finding the input for this form.
FormState::$must_validate protected property Ordinarily, a form is only validated once, but there are times when a form is resubmitted internally and should be validated again. Setting this to TRUE will force that to happen. This is most likely to occur during Ajax operations.
FormState::$no_cache protected property If set to TRUE the form will NOT be cached, even if 'cache' is set.
FormState::$no_redirect protected property If set to TRUE the form will NOT perform a redirect, even if self::$redirect is set.
FormState::$process_input protected property TRUE signifies correct form submission. This is always TRUE for programmed forms coming from \Drupal\Core\Form\FormBuilderInterface::submitForm() (see 'programmed' key), or if the form_id coming from the \Drupal::request()->request data…
FormState::$programmed protected property If TRUE, the form was submitted programmatically, usually invoked via \Drupal\Core\Form\FormBuilderInterface::submitForm(). Defaults to FALSE.
FormState::$programmed_bypass_access_check protected property If TRUE, programmatic form submissions are processed without taking #access into account. Set this to FALSE when submitting a form programmatically with values that may have been input by the user executing the current request; this will cause #access…
FormState::$rebuild protected property Normally, after the entire form processing is completed and submit handlers have run, a form is considered to be done and \Drupal\Core\Form\FormSubmitterInterface::redirectForm() will redirect the user to a new page using a GET request (so a browser…
FormState::$rebuild_info protected property Similar to self::$build_info, but pertaining to \Drupal\Core\Form\FormBuilderInterface::rebuildForm().
FormState::$redirect protected property Used to redirect the form on submission.
FormState::$requestMethod protected property The HTTP method used by the request building or processing this form.
FormState::$response protected property Used when a form needs to return some kind of a \Symfony\Component\HttpFoundation\Response object, e.g., a \Symfony\Component\HttpFoundation\BinaryFileResponse when triggering a file download. If you use self::setRedirect() or…
FormState::$storage protected property This 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…
FormState::$submitted protected property If TRUE, the form has been submitted. Defaults to FALSE.
FormState::$submit_handlers protected property Stores the gathered submission handlers.
FormState::$temporary protected property Holds temporary data accessible during the current page request only.
FormState::$triggering_element protected property The form element that triggered 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.
FormState::$validate_handlers protected property Stores the gathered validation handlers.
FormState::$validation_complete protected property Tracks if the form has finished validation.
FormState::$values protected property An associative array of values submitted to the form.
FormState::addBuildInfo public function Adds a value to the build info. Overrides FormStateInterface::addBuildInfo
FormState::addCleanValueKey public function Adds a key to the array of form values that will be cleaned. Overrides FormStateInterface::addCleanValueKey
FormState::addRebuildInfo public function Adds a value to the rebuild info. Overrides FormStateInterface::addRebuildInfo
FormState::cleanValues public function Removes internal Form API elements and buttons from submitted form values. Overrides FormStateInterface::cleanValues
FormState::clearErrors public function Clears all errors against all form elements made by self::setErrorByName(). Overrides FormStateInterface::clearErrors
FormState::disableCache public function Prevents the form from being cached. Overrides FormStateInterface::disableCache
FormState::disableRedirect public function Prevents the form from redirecting. Overrides FormStateInterface::disableRedirect
FormState::get public function Gets any arbitrary property. Overrides FormStateInterface::get
FormState::getAlwaysProcess public function Determines if this form should always be processed. Overrides FormStateInterface::getAlwaysProcess
FormState::getBuildInfo public function Returns the build info for the form. Overrides FormStateInterface::getBuildInfo
FormState::getButtons public function Returns the submit and button elements for the form. Overrides FormStateInterface::getButtons
FormState::getCacheableArray public function Returns an array representation of the cacheable portion of the form state. Overrides FormStateInterface::getCacheableArray
FormState::getCleanValueKeys public function Gets the keys of the form values that will be cleaned. Overrides FormStateInterface::getCleanValueKeys
FormState::getCompleteForm public function Returns a reference to the complete form array. Overrides FormStateInterface::getCompleteForm
FormState::getError public function Returns the error message filed against the given form element. Overrides FormStateInterface::getError
FormState::getErrors public function Returns an associative array of all errors. Overrides FormStateInterface::getErrors
FormState::getFormObject public function Returns the form object that is responsible for building this form. Overrides FormStateInterface::getFormObject
FormState::getGroups public function Returns references to details elements to render them within vertical tabs. Overrides FormStateInterface::getGroups
FormState::getLimitValidationErrors public function Retrieves the limited validation error sections. Overrides FormStateInterface::getLimitValidationErrors
FormState::getRebuildInfo public function Gets the rebuild info. Overrides FormStateInterface::getRebuildInfo
FormState::getRedirect public function Gets the value to use for redirecting after the form has been executed. Overrides FormStateInterface::getRedirect
FormState::getResponse public function Gets a response for this form. Overrides FormStateInterface::getResponse
FormState::getStorage public function Returns the entire set of arbitrary data. Overrides FormStateInterface::getStorage
FormState::getSubmitHandlers public function Gets the submit handlers. Overrides FormStateInterface::getSubmitHandlers
FormState::getTemporary public function Gets temporary data. Overrides FormStateInterface::getTemporary
FormState::getTemporaryValue public function Gets an arbitrary value from temporary storage. Overrides FormStateInterface::getTemporaryValue
FormState::getTriggeringElement public function Gets the form element that triggered submission. Overrides FormStateInterface::getTriggeringElement
FormState::getUserInput public function Returns the form values as they were submitted by the user. Overrides FormStateInterface::getUserInput
FormState::getValidateHandlers public function Gets the validate handlers. Overrides FormStateInterface::getValidateHandlers
FormState::getValues public function Implements \Drupal\Core\Form\FormStateInterface::getValues() Overrides FormStateValuesTrait::getValues
FormState::has public function Determines if an arbitrary property is present. Overrides FormStateInterface::has
FormState::hasAnyErrors public static function Determines if any forms have any errors. Overrides FormStateInterface::hasAnyErrors
FormState::hasFileElement public function Returns whether this form has a file element. Overrides FormStateInterface::hasFileElement
FormState::hasInvalidToken public function Determines if the form has an invalid token. Overrides FormStateInterface::hasInvalidToken
FormState::hasTemporaryValue public function Determines if a temporary value is present. Overrides FormStateInterface::hasTemporaryValue
FormState::isBypassingProgrammedAccessChecks public function Determines if this form submission should bypass #access. Overrides FormStateInterface::isBypassingProgrammedAccessChecks
FormState::isCached public function Determines if the form should be cached. Overrides FormStateInterface::isCached
FormState::isExecuted public function Determines if the form was submitted and has been processed and executed. Overrides FormStateInterface::isExecuted
FormState::isMethodType public function Returns the HTTP form method. Overrides FormStateInterface::isMethodType
FormState::isProcessingInput public function Determines if the form input will be processed. Overrides FormStateInterface::isProcessingInput
FormState::isProgrammed public function Returns if this form was submitted programmatically. Overrides FormStateInterface::isProgrammed
FormState::isRebuilding public function Determines if the form should be rebuilt after processing. Overrides FormStateInterface::isRebuilding
FormState::isRedirectDisabled public function Determines if redirecting has been prevented. Overrides FormStateInterface::isRedirectDisabled
FormState::isRequestMethodSafe protected function Checks whether the request method is a "safe" HTTP method.
FormState::isSubmitted public function Determines if the form has been submitted. Overrides FormStateInterface::isSubmitted
FormState::isValidationComplete public function Determines if validation has been completed. Overrides FormStateInterface::isValidationComplete
FormState::isValidationEnforced public function Checks if validation is enforced. Overrides FormStateInterface::isValidationEnforced
FormState::loadInclude public function Ensures an include file is loaded whenever the form is processed. Overrides FormStateInterface::loadInclude
FormState::moduleLoadInclude protected function Wraps ModuleHandler::loadInclude().
FormState::prepareCallback public function Converts support notations for a form callback to a valid callable. Overrides FormStateInterface::prepareCallback
FormState::set public function Sets a value to an arbitrary property. Overrides FormStateInterface::set
FormState::setAlwaysProcess public function Sets this form to always be processed. Overrides FormStateInterface::setAlwaysProcess
FormState::setAnyErrors protected static function Sets the global status of errors.
FormState::setBuildInfo public function Sets the build info for the form. Overrides FormStateInterface::setBuildInfo
FormState::setButtons public function Stores the submit and button elements for the form. Overrides FormStateInterface::setButtons
FormState::setCached public function Sets this form to be cached. Overrides FormStateInterface::setCached
FormState::setCleanValueKeys public function Sets the keys of the form values that will be cleaned. Overrides FormStateInterface::setCleanValueKeys
FormState::setCompleteForm public function Stores the complete form array. Overrides FormStateInterface::setCompleteForm
FormState::setError public function Flags an element as having an error. Overrides FormStateInterface::setError
FormState::setErrorByName public function Files an error against a form element. Overrides FormStateInterface::setErrorByName
FormState::setExecuted public function Sets that the form was submitted and has been processed and executed. Overrides FormStateInterface::setExecuted
FormState::setFormObject public function Sets the form object that is responsible for building this form. Overrides FormStateInterface::setFormObject
FormState::setFormState public function Sets the value of the form state. Overrides FormStateInterface::setFormState
FormState::setGroups public function Sets references to details elements to render them within vertical tabs. Overrides FormStateInterface::setGroups
FormState::setHasFileElement public function Sets that this form has a file element. Overrides FormStateInterface::setHasFileElement
FormState::setInvalidToken public function Flags the form state as having or not an invalid token. Overrides FormStateInterface::setInvalidToken
FormState::setLimitValidationErrors public function Sets the limited validation error sections. Overrides FormStateInterface::setLimitValidationErrors
FormState::setMethod public function Sets the HTTP method to use for the form's submission. Overrides FormStateInterface::setMethod
FormState::setProcessInput public function Sets that the form should process input. Overrides FormStateInterface::setProcessInput
FormState::setProgrammed public function Sets that this form was submitted programmatically. Overrides FormStateInterface::setProgrammed
FormState::setProgrammedBypassAccessCheck public function Sets if this form submission should bypass #access. Overrides FormStateInterface::setProgrammedBypassAccessCheck
FormState::setRebuild public function Sets the form to be rebuilt after processing. Overrides FormStateInterface::setRebuild
FormState::setRebuildInfo public function Sets the rebuild info. Overrides FormStateInterface::setRebuildInfo
FormState::setRedirect public function Sets the redirect for the form. Overrides FormStateInterface::setRedirect
FormState::setRedirectUrl public function Sets the redirect URL for the form. Overrides FormStateInterface::setRedirectUrl
FormState::setRequestMethod public function Sets the HTTP method used by the request that is building the form. Overrides FormStateInterface::setRequestMethod
FormState::setResponse public function Sets a response for this form. Overrides FormStateInterface::setResponse
FormState::setStorage public function Sets the entire set of arbitrary data. Overrides FormStateInterface::setStorage
FormState::setSubmitHandlers public function Sets the submit handlers. Overrides FormStateInterface::setSubmitHandlers
FormState::setSubmitted public function Sets that the form has been submitted. Overrides FormStateInterface::setSubmitted
FormState::setTemporary public function Sets temporary data. Overrides FormStateInterface::setTemporary
FormState::setTemporaryValue public function Sets an arbitrary value in temporary storage. Overrides FormStateInterface::setTemporaryValue
FormState::setTriggeringElement public function Sets the form element that triggered submission. Overrides FormStateInterface::setTriggeringElement
FormState::setUserInput public function Sets the form values as though they were submitted by a user. Overrides FormStateInterface::setUserInput
FormState::setValidateHandlers public function Sets the validate handlers. Overrides FormStateInterface::setValidateHandlers
FormState::setValidationComplete public function Sets that validation has been completed. Overrides FormStateInterface::setValidationComplete
FormState::setValidationEnforced public function Enforces that validation is run. Overrides FormStateInterface::setValidationEnforced
FormStateValuesTrait::getValue public function Implements \Drupal\Core\Form\FormStateInterface::getValue()
FormStateValuesTrait::hasValue public function Implements \Drupal\Core\Form\FormStateInterface::hasValue()
FormStateValuesTrait::isValueEmpty public function Implements \Drupal\Core\Form\FormStateInterface::isValueEmpty()
FormStateValuesTrait::setValue public function Implements \Drupal\Core\Form\FormStateInterface::setValue()
FormStateValuesTrait::setValueForElement public function Implements \Drupal\Core\Form\FormStateInterface::setValueForElement()
FormStateValuesTrait::setValues public function Implements \Drupal\Core\Form\FormStateInterface::setValues()
FormStateValuesTrait::unsetValue public function Implements \Drupal\Core\Form\FormStateInterface::unsetValue()