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().

For example:

// Set the administrator role to 'content_editor'.
$values['user_admin_role'] = 'content_editor';
$form_state = new FormState();
$form_state->setValues($values);
\Drupal::formBuilder()->submitForm(RoleSettingsForm::class, $form_state);

Parameters

\Drupal\Core\Form\FormInterface|string $form_arg: The value must be one of the following:

• The name of a class that implements \Drupal\Core\Form\FormInterface.
• An instance of a class that implements \Drupal\Core\Form\FormInterface.

\Drupal\Core\Form\FormStateInterface $form_state: The current state of the form. Most important is the $form_state->getValues() collection, a tree of data used to simulate the incoming \Drupal::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 \Drupal::request()->request entry, include the key, but set the value to NULL.

mixed ...$args: 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 whose ID is my_module_form, built from a class for which its buildForm() method expects a &$object argument would be called via self::submitForm() as follows:

$form_state->setValues($my_form_values);
$form_state->addBuildInfo('args', [
  &$object,
]);
\Drupal::formBuilder()->submitForm('my_module_form', $form_state);

Overrides FormBuilderInterface::submitForm

File

core/lib/Drupal/Core/Form/FormBuilder.php, line 498

Class

FormBuilder

Provides form building and processing.

Namespace

Drupal\Core\Form

Code

public function submitForm($form_arg, FormStateInterface &$form_state, mixed ...$args) {
  $build_info = $form_state->getBuildInfo();
  if (empty($build_info['args'])) {
    $form_state->addBuildInfo('args', $args);
  }
  // Populate FormState::$input with the submitted values before retrieving
  // the form, to be consistent with what self::buildForm() does for
  // non-programmatic submissions (form builder functions may expect it to be
  // there).
  $form_state->setUserInput($form_state->getValues());
  $form_state->setProgrammed();
  $form_id = $this->getFormId($form_arg, $form_state);
  $form = $this->retrieveForm($form_id, $form_state);
  // Programmed forms are always submitted.
  $form_state->setSubmitted();
  // Reset form validation.
  $form_state->setValidationEnforced();
  $form_state->clearErrors();
  $this->prepareForm($form_id, $form, $form_state);
  $this->processForm($form_id, $form, $form_state);
}

---