Drupal 8  8.0.2
FormBuilder Class Reference
Inheritance diagram for FormBuilder:

Public Member Functions

 __construct (FormValidatorInterface $form_validator, FormSubmitterInterface $form_submitter, FormCacheInterface $form_cache, ModuleHandlerInterface $module_handler, EventDispatcherInterface $event_dispatcher, RequestStack $request_stack, ClassResolverInterface $class_resolver, ElementInfoManagerInterface $element_info, ThemeManagerInterface $theme_manager, CsrfTokenGenerator $csrf_token=NULL)
 
 getFormId ($form_arg, FormStateInterface &$form_state)
 
 getForm ($form_arg)
 
 buildForm ($form_id, FormStateInterface &$form_state)
 
 rebuildForm ($form_id, FormStateInterface &$form_state, $old_form=NULL)
 
 getCache ($form_build_id, FormStateInterface $form_state)
 
 setCache ($form_build_id, $form, FormStateInterface $form_state)
 
 deleteCache ($form_build_id)
 
 submitForm ($form_arg, FormStateInterface &$form_state)
 
 retrieveForm ($form_id, FormStateInterface &$form_state)
 
 processForm ($form_id, &$form, FormStateInterface &$form_state)
 
 renderPlaceholderFormAction ()
 
 renderFormTokenPlaceholder ($placeholder)
 
 prepareForm ($form_id, &$form, FormStateInterface &$form_state)
 
 setInvalidTokenError (FormStateInterface $form_state)
 
 validateForm ($form_id, &$form, FormStateInterface &$form_state)
 
 redirectForm (FormStateInterface $form_state)
 
 executeValidateHandlers (&$form, FormStateInterface &$form_state)
 
 executeSubmitHandlers (&$form, FormStateInterface &$form_state)
 
 doSubmitForm (&$form, FormStateInterface &$form_state)
 
 doBuildForm ($form_id, &$element, FormStateInterface &$form_state)
 

Protected Member Functions

 buildFormAction ()
 
 valueCallableIsSafe (callable $value_callable)
 
 handleInputElement ($form_id, &$element, FormStateInterface &$form_state)
 
 elementTriggeredScriptedSubmission ($element, FormStateInterface &$form_state)
 
 buttonWasClicked ($element, FormStateInterface &$form_state)
 
 getFileUploadMaxSize ()
 
 currentUser ()
 

Protected Attributes

 $moduleHandler
 
 $eventDispatcher
 
 $requestStack
 
 $elementInfo
 
 $csrfToken
 
 $classResolver
 
 $currentUser
 
 $themeManager
 
 $formValidator
 
 $formSubmitter
 
 $formCache
 
 $safeCoreValueCallables
 

Additional Inherited Members

- Data Fields inherited from FormBuilderInterface
const AJAX_FORM_REQUEST = 'ajax_form'
 

Detailed Description

Provides form building and processing.

Constructor & Destructor Documentation

__construct ( FormValidatorInterface  $form_validator,
FormSubmitterInterface  $form_submitter,
FormCacheInterface  $form_cache,
ModuleHandlerInterface  $module_handler,
EventDispatcherInterface  $event_dispatcher,
RequestStack  $request_stack,
ClassResolverInterface  $class_resolver,
ElementInfoManagerInterface  $element_info,
ThemeManagerInterface  $theme_manager,
CsrfTokenGenerator  $csrf_token = NULL 
)

Constructs a new FormBuilder.

Parameters
\Drupal\Core\Form\FormValidatorInterface$form_validatorThe form validator.
\Drupal\Core\Form\FormSubmitterInterface$form_submitterThe form submission processor.
\Drupal\Core\Form\FormCacheInterface$form_cacheThe form cache.
\Drupal\Core\Extension\ModuleHandlerInterface$module_handlerThe module handler.
\Symfony\Component\EventDispatcher\EventDispatcherInterface$event_dispatcherThe event dispatcher.
\Symfony\Component\HttpFoundation\RequestStack$request_stackThe request stack.
\Drupal\Core\DependencyInjection\ClassResolverInterface$class_resolverThe class resolver.
\Drupal\Core\Render\ElementInfoManagerInterface$element_infoThe element info manager.
\Drupal\Core\Theme\ThemeManagerInterface$theme_managerThe theme manager.
\Drupal\Core\Access\CsrfTokenGenerator$csrf_tokenThe CSRF token generator.

References Drupal\csrfToken(), Drupal\moduleHandler(), and Drupal\requestStack().

Here is the call graph for this function:

Member Function Documentation

buildForm (   $form_id,
FormStateInterface $form_state 
)

{Builds and processes a form for a given form ID.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, and submission if there is proper input.

Parameters
\Drupal\Core\Form\FormInterface | string$form_idThe value must be one of the following:
  • The name of a class that implements .
  • An instance of a class that implements .
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form.
Returns
array 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.
Exceptions
\Drupal\Core\Form\FormAjaxExceptionThrown when a form is triggered via an AJAX submission. It will be handled by .
\Drupal\Core\Form\EnforcedResponseExceptionThrown when a form builder returns a response directly, usually a . It will be handled by .
See Also
self::redirectForm()
}

Implements FormBuilderInterface.

References FormStateInterface\disableRedirect(), FormStateInterface\getAlwaysProcess(), FormBuilder\getCache(), FormStateInterface\getCacheableArray(), FormBuilder\getFileUploadMaxSize(), FormBuilder\getFormId(), FormStateInterface\getTemporary(), FormStateInterface\getUserInput(), FormStateInterface\isMethodType(), FormStateInterface\isProcessingInput(), FormBuilder\prepareForm(), FormBuilder\processForm(), FormBuilder\rebuildForm(), Drupal\requestStack(), FormBuilder\retrieveForm(), FormStateInterface\setFormState(), FormStateInterface\setRequestMethod(), and FormStateInterface\setUserInput().

Referenced by FormBuilder\getForm().

Here is the call graph for this function:

Here is the caller graph for this function:

buildFormAction ( )
protected

Builds the $form['#action'].

Returns
string The URL to be used as the $form['#action'].

References UrlHelper\buildQuery(), UrlHelper\parse(), Drupal\requestStack(), and MainContentViewSubscriber\WRAPPER_FORMAT.

Referenced by FormBuilder\renderPlaceholderFormAction().

Here is the call graph for this function:

Here is the caller graph for this function:

buttonWasClicked (   $element,
FormStateInterface $form_state 
)
protected

Determines if a given button triggered the form submission.

This detects button controls that trigger a form submission by being clicked and having the click processed by the browser rather than being captured by JavaScript. Essentially, it detects if the button's name and value are part of the POST data, but with extra code to deal with the convoluted way in which browsers submit data for image button clicks.

This does not detect button clicks processed by Ajax (that is done in self::elementTriggeredScriptedSubmission()) and it does not detect form submissions from Internet Explorer in response to an ENTER key pressed in a textfield (self::doBuildForm() has extra code for that).

Because this function contains only part of the logic needed to determine $form_state->getTriggeringElement(), it should not be called from anywhere other than within the Form API. Form validation and submit handlers needing to know which button was clicked should get that information from $form_state->getTriggeringElement().

References Html\decodeEntities(), and FormStateInterface\getUserInput().

Referenced by FormBuilder\handleInputElement().

Here is the call graph for this function:

Here is the caller graph for this function:

currentUser ( )
protected

Gets the current active user.

Returns

References Drupal\currentUser(), and Drupal\hasService().

Referenced by FormBuilder\prepareForm().

Here is the call graph for this function:

Here is the caller graph for this function:

deleteCache (   $form_build_id)

{Deletes a form in the cache.

Parameters
string$form_build_idThe unique form build ID.
}

Implements FormCacheInterface.

Referenced by FormBuilder\processForm().

Here is the caller graph for this function:

doBuildForm (   $form_id,
$element,
FormStateInterface $form_state 
)

{Builds and processes all elements in the structured form array.Adds any required properties to each element, maps the incoming input data to the proper elements, and executes any #process handlers attached to a specific element.This is one of the three primary functions that recursively iterates a form array. This one does it for completing the form building process. The other two are self::doValidateForm() (invoked via self::validateForm() and used to invoke validation logic for each element) and drupal_render() (for rendering each element). Each of these three pipelines provides ample opportunity for modules to customize what happens. For example, during this function's life cycle, the following functions get called for each element:

  • $element['#value_callback']: A callable that implements how user input is mapped to an element's #value property. This defaults to a function named 'form_type_TYPE_value' where TYPE is $element['#type'].
  • $element['#process']: An array of functions called after user input has been mapped to the element's #value property. These functions can be used to dynamically add child elements: for example, for the 'date' element type, one of the functions in this array is form_process_datetime(), which adds the individual 'date', and 'time'. child elements. These functions can also be used to set additional properties or implement special logic other than adding child elements: for example, for the 'details' element type, one of the functions in this array is form_process_details(), which adds the attributes and JavaScript needed to make the details work in older browsers. The #process functions are called in preorder traversal, meaning they are called for the parent element first, then for the child elements.
  • $element['#after_build']: An array of callables called after self::doBuildForm() is done with its processing of the element. These are called in postorder traversal, meaning they are called for the child elements first, then for the parent element. There are similar properties containing callback functions invoked by self::doValidateForm() and drupal_render(), appropriate for those operations.
Developers are strongly encouraged to integrate the functionality needed by their form or module within one of these three pipelines, using the appropriate callback property, rather than implementing their own recursive traversal of a form array. This facilitates proper integration between multiple modules. For example, module developers are familiar with the relative order in which hook_form_alter() implementations and #process functions run. A custom traversal function that affects the building of a form is likely to not integrate with hook_form_alter() and #process in the expected way. Also, deep recursion within PHP is both slow and memory intensive, so it is best to minimize how often it's done.As stated above, each element's #process functions are executed after its #value has been set. This enables those functions to execute conditional logic based on the current value. However, all of self::doBuildForm() runs before self::validateForm() is called, so during #process function execution, the element's #value has not yet been validated, so any code that requires validated values must reside within a submit handler.As a security measure, user input is used for an element's #value only if the element exists within $form, is not disabled (as per the #disabled property), and can be accessed (as per the #access property, except that forms submitted using self::submitForm() bypass #access restrictions). When user input is ignored due to #disabled and #access restrictions, the element's default value is used.Because of the preorder traversal, where #process functions of an element run before user input for its child elements is processed, and because of the Form API security of user input processing with respect to #access and #disabled described above, this generally means that #process functions should not use an element's (unvalidated) #value to affect the #disabled or #access of child elements. Use-cases where a developer may be tempted to implement such conditional logic usually fall into one of two categories:

  • Where user input from the current submission must affect the structure of a form, including properties like #access and #disabled that affect how the next submission needs to be processed, a multi-step workflow is needed. This is most commonly implemented with a submit handler setting persistent data within $form_state based on validated values in $form_state->getValues() and checking $form_state->isRebuilding(). The form building functions must then be implemented to use the $form_state to rebuild the form with the structure appropriate for the new state.
  • Where user input must affect the rendering of the form without affecting its structure, the necessary conditional rendering logic should reside within functions that run during the rendering phase (#pre_render, theme, #theme_wrappers, and #post_render).
Parameters
string$form_idA unique string identifying the form for validation, submission, theming, and hook_form_alter functions.
array$elementAn associative array containing the structure of the current element.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form. In this context, it is used to accumulate information about which button was clicked when the form was submitted, as well as the sanitized ::request()->request data.
Returns
array
}

Implements FormBuilderInterface.

References Element\children(), Drupal\csrfToken(), FormStateInterface\getButtons(), FormStateInterface\getCompleteForm(), Html\getId(), FormStateInterface\getTriggeringElement(), Html\getUniqueId(), FormStateInterface\getUserInput(), FormBuilder\handleInputElement(), FormStateInterface\hasFileElement(), AccessResultInterface\isAllowed(), UrlHelper\isExternal(), FormStateInterface\isProgrammed(), FormStateInterface\prepareCallback(), Drupal\requestStack(), FormStateInterface\setCompleteForm(), FormStateInterface\setHasFileElement(), FormStateInterface\setInvalidToken(), FormBuilder\setInvalidTokenError(), FormStateInterface\setProcessInput(), FormStateInterface\setSubmitHandlers(), FormStateInterface\setSubmitted(), FormStateInterface\setTriggeringElement(), FormStateInterface\setValidateHandlers(), and FormStateInterface\setValue().

Referenced by FormBuilder\processForm(), and FormBuilder\rebuildForm().

Here is the call graph for this function:

Here is the caller graph for this function:

doSubmitForm ( $form,
FormStateInterface $form_state 
)

{Handles the submitted form, executing callbacks and processing responses.

Parameters
array$formAn associative array containing the structure of the form.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form.
Returns
null| If a response was set by a submit handler, or if the form needs to redirect, a Response object will be returned.
}

Implements FormSubmitterInterface.

elementTriggeredScriptedSubmission (   $element,
FormStateInterface $form_state 
)
protected

Detects if an element triggered the form submission via Ajax.

This detects button or non-button controls that trigger a form submission via Ajax or some other scriptable environment. These environments can set the special input key '_triggering_element_name' to identify the triggering element. If the name alone doesn't identify the element uniquely, the input key '_triggering_element_value' may also be set to require a match on element value. An example where this is needed is if there are several // buttons all named 'op', and only differing in their value.

References FormStateInterface\getUserInput().

Referenced by FormBuilder\handleInputElement().

Here is the call graph for this function:

Here is the caller graph for this function:

executeSubmitHandlers ( $form,
FormStateInterface $form_state 
)

{Executes custom submission handlers for a given form.Button-specific handlers are checked first. If none exist, the function falls back to form-level handlers.

Parameters
$formAn associative array containing the structure of the form.
$form_stateThe current state of the form. If the user submitted the form by clicking a button with custom handler functions defined, those handlers will be stored here.
}

Implements FormSubmitterInterface.

executeValidateHandlers ( $form,
FormStateInterface $form_state 
)

{Executes custom validation handlers for a given form.Button-specific handlers are checked first. If none exist, the function falls back to form-level handlers.

Parameters
$formAn associative array containing the structure of the form.
$form_stateThe current state of the form. If the user submitted the form by clicking a button with custom handler functions defined, those handlers will be stored here.
}

Implements FormValidatorInterface.

getCache (   $form_build_id,
FormStateInterface  $form_state 
)

{Fetches a form from the cache.

Parameters
string$form_build_idThe unique form build ID.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form.
}

Implements FormCacheInterface.

Referenced by FormBuilder\buildForm().

Here is the caller graph for this function:

getFileUploadMaxSize ( )
protected

Wraps file_upload_max_size().

Returns
string A translated string representation of the size of the file size limit based on the PHP upload_max_filesize and post_max_size.

References file_upload_max_size().

Referenced by FormBuilder\buildForm().

Here is the call graph for this function:

Here is the caller graph for this function:

getForm (   $form_arg)

{Gets a renderable form array.This function should be used instead of self::buildForm() when $form_state is not needed (i.e., when initially rendering the form) and is often used as a menu callback.

Parameters
\Drupal\Core\Form\FormInterface | string$form_argThe value must be one of the following:
  • The name of a class that implements .
  • An instance of a class that implements .
...Any additional arguments are passed on to the functions called by ::formBuilder()->getForm(), including the unique form constructor function. For example, the node_edit form requires that a node object is passed in here when it is called. These are available to implementations of hook_form_alter() and hook_form_FORM_ID_alter() as the array $form_state->getBuildInfo()['args'].
Returns
array The form array.
See Also
::buildForm()
}

Implements FormBuilderInterface.

References FormBuilder\buildForm().

Here is the call graph for this function:

getFormId (   $form_arg,
FormStateInterface $form_state 
)

{Determines the ID of a form.

Parameters
\Drupal\Core\Form\FormInterface | string$form_argThe value is identical to that of self::getForm()'s $form_arg argument.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form.
Returns
string The unique string identifying the desired form.
}

Implements FormBuilderInterface.

References FormStateInterface\addBuildInfo(), and FormStateInterface\setFormObject().

Referenced by FormBuilder\buildForm(), and FormBuilder\submitForm().

Here is the call graph for this function:

Here is the caller graph for this function:

handleInputElement (   $form_id,
$element,
FormStateInterface $form_state 
)
protected

Adds the #name and #value properties of an input element before rendering.

References FormBuilder\buttonWasClicked(), FormBuilder\elementTriggeredScriptedSubmission(), FormStateInterface\getButtons(), FormStateInterface\getUserInput(), NestedArray\getValue(), FormStateInterface\getValues(), FormStateInterface\hasInvalidToken(), FormStateInterface\isBypassingProgrammedAccessChecks(), FormStateInterface\isProcessingInput(), FormStateInterface\isProgrammed(), FormStateInterface\isRebuilding(), NestedArray\keyExists(), FormStateInterface\setButtons(), FormStateInterface\setTriggeringElement(), NestedArray\setValue(), FormStateInterface\setValueForElement(), and FormBuilder\valueCallableIsSafe().

Referenced by FormBuilder\doBuildForm().

Here is the call graph for this function:

Here is the caller graph for this function:

prepareForm (   $form_id,
$form,
FormStateInterface $form_state 
)

{Prepares a structured form array.Adds required elements, executes any hook_form_alter functions, and optionally inserts a validation token to prevent tampering.

Parameters
string$form_idA unique string identifying the form for validation, submission, theming, and hook_form_alter functions.
array$formAn associative array containing the structure of the form.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form. Passed in here so that hook_form_alter() calls can use it, as well.
}

Implements FormBuilderInterface.

References FormBuilder\currentUser(), FormStateInterface\getBuildInfo(), Html\getId(), Html\getUniqueId(), FormStateInterface\isMethodType(), FormStateInterface\isProgrammed(), Drupal\moduleHandler(), and Crypt\randomBytesBase64().

Referenced by FormBuilder\buildForm(), FormBuilder\rebuildForm(), and FormBuilder\submitForm().

Here is the call graph for this function:

Here is the caller graph for this function:

processForm (   $form_id,
$form,
FormStateInterface $form_state 
)

{Processes a form submission.This function is the heart of form API. The form gets built, validated and in appropriate cases, submitted and rebuilt.

Parameters
string$form_idThe unique string identifying the current form.
array$formAn associative array containing the structure of the form.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form. This includes the current persistent storage data for the form, and any data passed along by earlier steps when displaying a multi-step form. Additional information, like the sanitized ::request()->request data, is also accumulated here.
Returns
|null
}

Implements FormBuilderInterface.

References Drupal\csrfToken(), FormBuilder\deleteCache(), FormBuilder\doBuildForm(), FormStateInterface\getAlwaysProcess(), FormStateInterface\getButtons(), FormStateInterface\getTriggeringElement(), FormStateInterface\getUserInput(), FormState\hasAnyErrors(), FormStateInterface\isCached(), FormStateInterface\isExecuted(), FormStateInterface\isMethodType(), FormStateInterface\isProcessingInput(), FormStateInterface\isProgrammed(), FormStateInterface\isRebuilding(), FormBuilder\rebuildForm(), Html\resetSeenIds(), FormBuilder\setCache(), FormStateInterface\setRebuild(), FormStateInterface\setTriggeringElement(), FormStateInterface\setUserInput(), and FormStateInterface\setValues().

Referenced by FormBuilder\buildForm(), and FormBuilder\submitForm().

Here is the call graph for this function:

Here is the caller graph for this function:

rebuildForm (   $form_id,
FormStateInterface $form_state,
  $old_form = NULL 
)

{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 self::processForm() 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->isRebuilding() 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.Ajax form submissions are almost always multi-step workflows, so that is one common use-case during which form rebuilding occurs.

Parameters
string$form_idThe unique string identifying the desired form. If a function with that name exists, it is called to build the form array.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form.
array | null$old_form(optional) A previously built $form. Used to retain the #build_id and #action properties in Ajax callbacks and similar partial form rebuilds. The only properties copied from $old_form are the ones which both exist in $old_form and for which $form_state->getRebuildInfo()['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.
Returns
array The newly built form.
See Also
self::processForm()
}

Implements FormBuilderInterface.

References FormBuilder\doBuildForm(), FormStateInterface\getRebuildInfo(), FormStateInterface\isCached(), FormStateInterface\isMethodType(), FormBuilder\prepareForm(), Crypt\randomBytesBase64(), FormBuilder\retrieveForm(), FormBuilder\setCache(), FormStateInterface\setCached(), and FormStateInterface\setGroups().

Referenced by FormBuilder\buildForm(), and FormBuilder\processForm().

Here is the call graph for this function:

Here is the caller graph for this function:

redirectForm ( FormStateInterface  $form_state)

{Redirects the user to a URL after a form has been processed.After a form is submitted and processed, normally the user should be redirected to a new destination page. This function figures out what that destination should be, based on the $form_state and the 'destination' query string in the request URL, and redirects the user there.The result of |FormStateInterface::getRedirect() determines where to redirect the user. See the possible return values listed there. If the result is FALSE, then the user will not be redirected.Here is an example of how to set up a form to redirect to the path 'user':

$form_state->setRedirect('user.page');

And here is an example of how to redirect to 'node/123?foo=bar::baz':

$form_state->setRedirect('entity.node.canonical',
array('node' => 123),
array(
'query' => array(
'foo' => 'bar',
),
'fragment' => 'baz',
),
));
Parameters
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form.
Returns
|null
See Also
::processForm()
::buildForm()
}

Implements FormSubmitterInterface.

renderFormTokenPlaceholder (   $placeholder)

#lazy_builder callback; renders form CSRF token.

Parameters
string$placeholderA string containing a placeholder, matching the value of the form's token.
Returns
array A renderable array containing the CSRF token.

References Drupal\csrfToken().

Here is the call graph for this function:

renderPlaceholderFormAction ( )

#lazy_builder callback; renders a form action URL.

Returns
array A renderable array representing the form action.

References FormBuilder\buildFormAction().

Here is the call graph for this function:

retrieveForm (   $form_id,
FormStateInterface $form_state 
)

{Retrieves the structured array that defines a given form.

Parameters
string$form_idThe unique string identifying the desired form. If a function with that name exists, it is called to build the form array.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form, including the additional arguments to self::getForm() or self::submitForm() in the 'args' component of the array.
Returns
mixed|
}

Implements FormBuilderInterface.

References FormStateInterface\addBuildInfo(), FormStateInterface\getBuildInfo(), Html\getClass(), and FormStateInterface\getFormObject().

Referenced by FormBuilder\buildForm(), FormBuilder\rebuildForm(), and FormBuilder\submitForm().

Here is the call graph for this function:

Here is the caller graph for this function:

setCache (   $form_build_id,
  $form,
FormStateInterface  $form_state 
)

{Stores a form in the cache.

Parameters
string$form_build_idThe unique form build ID.
array$formThe form to cache.
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form.
}

Implements FormCacheInterface.

Referenced by FormBuilder\processForm(), and FormBuilder\rebuildForm().

Here is the caller graph for this function:

setInvalidTokenError ( FormStateInterface  $form_state)

{Sets a form_token error on the given form state.

Parameters
\Drupal\Core\Form\FormStateInterface$form_stateThe current state of the form.
Returns
$this
}

Implements FormValidatorInterface.

Referenced by FormBuilder\doBuildForm().

Here is the caller graph for this function:

submitForm (   $form_arg,
FormStateInterface $form_state 
)

{Retrieves, populates, and processes a form.This function allows you to supply values for form elements and submit a form for processing. Compare to self::getForm(), 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_state->getErrors().

Parameters
\Drupal\Core\Form\FormInterface | string$form_argA form object to use to build the form, or the unique string identifying the desired form. If $form_arg is a string and a function with that name exists, it is called to build the form array.
$form_stateThe current state of the form. Most important is the $form_state->getValues() collection, a tree of data used to simulate the incoming ::request()->request information from a user's form submission. If a key is not filled in $form_state->getValues(), 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 ::request()->request entry, include the key, but set the value to NULL.
...Any additional arguments are passed on to the functions called by self::submitForm(), including the unique form constructor function. For example, the node_edit form requires that a node object be passed 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:
function mymodule_form($form, FormStateInterface &$form_state, &$object) {
}
would be called via self::submitForm() as follows:
$form_state->setValues($my_form_values);
$form_state->addBuildInfo('args', [&$object]);
\Drupal::formBuilder()->submitForm('mymodule_form', $form_state);
For example:
// register a new user
$form_state = new FormState();
$values['name'] = 'robo-user';
$values['mail'] = 'robouser@example.com';
$values['pass']['pass1'] = 'password';
$values['pass']['pass2'] = 'password';
$values['op'] = t('Create new account');
$form_state->setValues($values);
\Drupal::formBuilder()->submitForm('user_register_form', $form_state);
}

Implements FormBuilderInterface.

References FormStateInterface\addBuildInfo(), FormStateInterface\clearErrors(), FormStateInterface\getBuildInfo(), FormBuilder\getFormId(), FormStateInterface\getValues(), FormBuilder\prepareForm(), FormBuilder\processForm(), FormBuilder\retrieveForm(), FormStateInterface\setProgrammed(), FormStateInterface\setSubmitted(), FormStateInterface\setUserInput(), and FormStateInterface\setValidationEnforced().

Here is the call graph for this function:

validateForm (   $form_id,
$form,
FormStateInterface $form_state 
)

{Validates user-submitted form data in the $form_state.

Parameters
$form_idA unique string identifying the form for validation, submission, theming, and hook_form_alter functions.
$formAn 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->getValues() to prevent form submit handlers from receiving unvalidated values.
$form_stateThe current state of the form. The current user-submitted data is stored in $form_state->getValues(), though form validation functions are passed an explicit copy of the values for the sake of simplicity. Validation handlers can also use $form_state to pass information on to submit handlers. For example: $form_state->set('data_for_submission', $data); 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.
}

Implements FormValidatorInterface.

valueCallableIsSafe ( callable  $value_callable)
protected

Helper function to normalize the different callable formats.

Parameters
callable$value_callableThe callable to be checked.
Returns
bool TRUE if the callable is safe even if the CSRF token is invalid, FALSE otherwise.

Referenced by FormBuilder\handleInputElement().

Here is the caller graph for this function:

Field Documentation

$safeCoreValueCallables
protected
Initial value:
= [
'Drupal\Core\Render\Element\Checkbox::valueCallback',
'Drupal\Core\Render\Element\Checkboxes::valueCallback',
'Drupal\Core\Render\Element\Email::valueCallback',
'Drupal\Core\Render\Element\FormElement::valueCallback',
'Drupal\Core\Render\Element\MachineName::valueCallback',
'Drupal\Core\Render\Element\Number::valueCallback',
'Drupal\Core\Render\Element\PathElement::valueCallback',
'Drupal\Core\Render\Element\Password::valueCallback',
'Drupal\Core\Render\Element\PasswordConfirm::valueCallback',
'Drupal\Core\Render\Element\Radio::valueCallback',
'Drupal\Core\Render\Element\Radios::valueCallback',
'Drupal\Core\Render\Element\Range::valueCallback',
'Drupal\Core\Render\Element\Search::valueCallback',
'Drupal\Core\Render\Element\Select::valueCallback',
'Drupal\Core\Render\Element\Tableselect::valueCallback',
'Drupal\Core\Render\Element\Table::valueCallback',
'Drupal\Core\Render\Element\Tel::valueCallback',
'Drupal\Core\Render\Element\Textarea::valueCallback',
'Drupal\Core\Render\Element\Textfield::valueCallback',
'Drupal\Core\Render\Element\Token::valueCallback',
'Drupal\Core\Render\Element\Url::valueCallback',
'Drupal\Core\Render\Element\Weight::valueCallback',
]

The documentation for this class was generated from the following file: