Same name in other branches

1. 7.x includes/module.inc \hooks
2. 9 core/core.api.php \hooks
3. 8.9.x core/core.api.php \hooks
4. 10 core/core.api.php \hooks

Define functions that alter the behavior of Drupal core.

One way for modules to alter the core behavior of Drupal (or another module) is to use hooks. Hooks are functions or methods that a module defines (this is known as "implementing the hook"), which are discovered and called at specific times to alter or add to the base behavior or data (this is known as "invoking the hook"). Each hook has a name (example: hook_batch_alter()), a defined set of parameters, and a defined return value. Your modules can implement hooks that are defined by Drupal core or other modules that they interact with. Your modules can also define their own hooks, in order to let other modules interact with them.

Implementing a hook

There are two ways to implement a hook:

• Class method, by adding an attribute to a class or a method. This is the preferred method.
• Procedural, by defining a specially-named function. Some hooks can only be implemented as procedural.

In both cases, first locate the documentation for the hook. Hooks are documented in *.api.php files, by defining functions whose name starts with "hook_" (these files and their functions are never loaded by Drupal -- they exist solely for documentation). The function should have a documentation header, as well as a sample function body. For example, in the core file form.api.php, you can find hooks such as hook_batch_alter(). Also, if you are viewing this documentation on an API reference site, the Core hooks will be listed in this topic.

Class method hook implementation

Class method hooks use the attribute \Drupal\Core\Hook\Attribute\Hook to declare a method as being the hook implementation. The first parameter to the attribute is the short hook name, that is, with the 'hook_' prefix removed.

The Hook attribute can be used in any of the following ways:

• On a method, use the attribute with the hook name:

  #[Hook('user_cancel')]
  public method userCancel(...)
  

• On a class, specify the method name as well as the hook name:

  #[Hook('user_cancel', method: 'userCancel')]
  class Hooks {
    method userCancel(...) {}
  }
  

• On a class with an __invoke method, which is taken to be the hook implementation:

  #[Hook('user_cancel')]
  class Hooks {
    method __invoke(...) {}
  }
  

The following hooks can not be implemented as a class method, and must be implemented as procedural:

Legacy meta hooks:

• hook_hook_info()
• hook_module_implements_alter()

Install hooks:

• hook_install()
• hook_install_tasks()
• hook_install_tasks_alter()
• hook_post_update_NAME()
• hook_schema()
• hook_uninstall()
• hook_update_last_removed()
• hook_update_N()

Theme hooks:

• hook_preprocess_HOOK()
• hook_process_HOOK()

Procedural hook implementation

Procedural implementation should use the following technique:

• Copy the function to your module's .module file.
• Change the name of the function, substituting your module's short name (name of the module's directory, and .info.yml file without the extension) for the "hook" part of the sample function name. For instance, to implement hook_batch_alter(), you would rename it to my_module_batch_alter().
• Edit the documentation for the function (normally, your implementation should just have one line saying "Implements hook_batch_alter().").
• Edit the body of the function, substituting in what you need your module to do.

Defining a hook

To define a hook:

• Choose a unique name for your hook. It should start with "hook_", followed by your module's short name.
• Provide documentation in a *.api.php file in your module's main directory. See the "implementing" section above for details of what this should contain (parameters, return value, and sample function body).
• Invoke the hook in your module's code.

Invoking a hook

To invoke a hook, use methods on \Drupal\Core\Extension\ModuleHandlerInterface such as alter(), invoke(), and invokeAll(). You can obtain a module handler by calling \Drupal::moduleHandler(), or getting the 'module_handler' service on an injected container.

See also

Extending and altering Drupal

Theme system overview

Callbacks

\Drupal\Core\Extension\ModuleHandlerInterface

\Drupal\Core\Hook\Attribute\Hook

\Drupal::moduleHandler()

File

core/core.api.php, line 1593

Functions

Sub-Topics

---