Same name and namespace in other branches
  1. 7.x modules/system/system.api.php \hook_form_BASE_FORM_ID_alter()
  2. 8.9.x core/lib/Drupal/Core/Form/form.api.php \hook_form_BASE_FORM_ID_alter()
  3. 9 core/lib/Drupal/Core/Form/form.api.php \hook_form_BASE_FORM_ID_alter()

Provide a form-specific alteration for shared ('base') forms.

Implementations are responsible for adding cache contexts/tags/max-age as needed. See https://www.drupal.org/docs/8/api/cache-api/cache-api.

By default, when \Drupal::formBuilder()->getForm() is called, Drupal looks for a function with the same name as the form ID, and uses that function to build the form. In contrast, base forms allow multiple form IDs to be mapped to a single base (also called 'factory') form function.

Modules can implement hook_form_BASE_FORM_ID_alter() to modify a specific base form, rather than implementing hook_form_alter() and checking for conditions that would identify the shared form constructor.

To identify the base form ID for a particular form (or to determine whether one exists) check the $form_state. The base form ID is stored under $form_state->getBuildInfo()['base_form_id'].

The call order is as follows: all existing form alter functions are called for module A, then all for module B, etc., followed by all for any base theme(s), and finally for the theme itself. The module order is determined by system weight, then by module name.

Within each module, form alter hooks are called in the following order: first, hook_form_alter(); second, hook_form_BASE_FORM_ID_alter(); third, hook_form_FORM_ID_alter(). So, for each module, the more general hooks are called first followed by the more specific.

Parameters

$form: Nested array of form elements that comprise the form.

$form_state: The current state of the form.

$form_id: String representing the name of the form itself. Typically this is the name of the function that generated the form.

See also

hook_form_alter()

hook_form_FORM_ID_alter()

\Drupal\Core\Form\FormBuilderInterface::prepareForm()

Related topics

92 functions implement hook_form_BASE_FORM_ID_alter()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

automated_cron_form_system_cron_settings_alter in core/modules/automated_cron/automated_cron.module
Implements hook_form_FORM_ID_alter() for the system_cron_settings() form.
block_form_form_test_alter_form_alter in core/modules/system/tests/modules/form_test/form_test.module
Implements hook_form_FORM_ID_alter().
book_form_node_confirm_form_alter in core/modules/book/book.module
Implements hook_form_BASE_FORM_ID_alter() for \Drupal\node\Form\NodeDeleteForm.
book_form_node_form_alter in core/modules/book/book.module
Implements hook_form_BASE_FORM_ID_alter() for \Drupal\node\NodeForm.
ckeditor5_form_filter_format_form_alter in core/modules/ckeditor5/ckeditor5.module
Implements hook_form_FORM_ID_alter().

... See full list

File

core/lib/Drupal/Core/Form/form.api.php, line 310
Callbacks and hooks related to form system.

Code

function hook_form_BASE_FORM_ID_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {

  // Modification for the form with the given BASE_FORM_ID goes here. For
  // example, if BASE_FORM_ID is "node_form", this code would run on every
  // node form, regardless of node type.
  // Add a checkbox to the node form about agreeing to terms of use.
  $form['terms_of_use'] = [
    '#type' => 'checkbox',
    '#title' => t("I agree with the website's terms and conditions."),
    '#required' => TRUE,
  ];
}