Understanding hooks

Last updated on
21 September 2023

Hooks are one of the ways for modules to interact with contributed modules or Drupal core subsystems. Hooks are used for a variety of tasks including preprocessing variables for template files (hook_preprocess()), altering lists of information (hook_tokens_alter(), hook_views_data_alter()), and manipulating forms (hook_form_alter()) amongst other things. This page lists all the hooks provided by core.

Modules can define additional hooks of their own. For example the Flag module defines hook_flag_options_alter(), which can be used by modules that want to alter an existing flag's default options. Most modules that define hooks will also provide documentation about them. This documentation is located in a *.api.php file.

Hooks occur at various points in the thread of execution, where Drupal seeks contributions from all the enabled modules. For example, when a user visits a help page on a Drupal site, as Drupal builds the help page it will give each module a chance to contribute documentation about itself. It does this by scanning all enabled modules for implementations of hook_help(). That is, functions that have the name mymodule_help($route_name, \Drupal\Core\Routing\RouteMatchInterface $route_match), where "mymodule" is the module's name, e.g., the block module's help hook is called block_help() and the node module's help hook is called node_help(). The hook may provide parameters; hook_help's parameters $route_name and $route_match allow the developer to determine what page or pages the help messages will appear on.

A hook can be thought of as an event listener in the sense that an event triggers an action. The event in Drupal, such as deleting a node, would trigger the hook "hook_node_delete". If your module implemented hook_node_delete, that function would run when a node deletion occurred. As an example, your function might be to decrease the count of the total number of nodes, so when a node was deleted, your function would be called and lower the count by 1.

Module hook execution order

For each hook, implementations are called in order of the weight of the module.

Modules with lower weight (including negative numbers) are called before higher weight.

Where the weight is the same, they are called in alphabetical order of module machine name.

Getting module weight

Module weight is stored in the core.extension configuration item.

drush cget core.extension

Each enabled module and theme is listed, with a numeric weight value.

Setting module weight

Use module_set_weight:

module_set_weight('[your_module_name]', [your_preferred_weight]);

You can set the weight when the module is enabled:

function your_module_name_install() {
  module_set_weight('[your_module_name]', [your_preferred_weight]);
}

See also the overview of module hooks, in the Drupal API Reference. You might want to check out also this good article discussing how Drupal 7 module/hook system works, using simple PHP constructs/snippets.

Help improve this page

Page status: No known problems

You can: