Same name and namespace in other branches
  1. 4.7.x developer/hooks/core.php \hook_form_alter()
  2. 5.x developer/hooks/core.php \hook_form_alter()
  3. 6.x developer/hooks/core.php \hook_form_alter()
  4. 7.x modules/system/system.api.php \hook_form_alter()
  5. 8.9.x core/lib/Drupal/Core/Form/form.api.php \hook_form_alter()
  6. 9 core/lib/Drupal/Core/Form/form.api.php \hook_form_alter()

Perform alterations before a form is rendered.

One popular use of this hook is to add form elements to the node form. When altering a node form, the node entity can be retrieved by invoking $form_state->getFormObject()->getEntity().

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

In addition to hook_form_alter(), which is called for all forms, there are two more specific form hooks available. The first, hook_form_BASE_FORM_ID_alter(), allows targeting of a form/forms via a base form (if one exists). The second, hook_form_FORM_ID_alter(), can be used to target a specific form directly.

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. The arguments that \Drupal::formBuilder()->getForm() was originally called with are available in the array $form_state->getBuildInfo()['args'].

$form_id: A string that is the unique ID of the form, set by Drupal\Core\Form\FormInterface::getFormId().

See also

hook_form_BASE_FORM_ID_alter()

hook_form_FORM_ID_alter()

Related topics

79 functions implement hook_form_alter()

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

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().
ckeditor5_read_only_mode_form_node_page_form_alter in core/modules/ckeditor5/tests/modules/ckeditor5_read_only_mode/ckeditor5_read_only_mode.module
Implements hook_form_alter().

... See full list

File

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

Code

function hook_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
  if (isset($form['type']) && $form['type']['#value'] . '_node_settings' == $form_id) {
    $upload_enabled_types = \Drupal::config('my_module.settings')
      ->get('upload_enabled_types');
    $form['workflow']['upload_' . $form['type']['#value']] = [
      '#type' => 'radios',
      '#title' => t('Attachments'),
      '#default_value' => in_array($form['type']['#value'], $upload_enabled_types) ? 1 : 0,
      '#options' => [
        t('Disabled'),
        t('Enabled'),
      ],
    ];

    // Add a custom submit handler to save the array of types back to the config file.
    $form['actions']['submit']['#submit'][] = 'my_module_upload_enabled_types_submit';
  }
}