Introduction to Hooks

Objectives
  • Learn how hooks let you modify Drupal's standard behaviour.
  • Learn what it means to implement a hook, and how you can do so.
  • Create a new module and implement your first hook.

Hooks let you modify or entirely replace behaviour of Drupal core and contributed modules/themes in a clean, controlled way.

Examples:

  • You want to replace Drupal's login mechanism with your own mechanism that checks credentials against an external Single Sign-On system.
  • You want to do something every time a node is loaded from the database, saved to the database, or prepared for display.
  • You want to insert a record in a custom security log table every time a user logs in or out.
  • You want to remove a field from a form that you didn't build (so you can't just change the class definition).
  • You want to use Drupal's cron mechanism to periodically run some code (to retrieve data form an external system, to clean up local data, …).

The process is the same each time: when a certain event occurs, you want your code to be executed.

Note:
As of Drupal 8, a more modern system of events and subscribers started replacing the older hook system.

This transition is not yet complete, for the time being Drupal uses the hook system in certain places, and the event/subscriber system in other places. Eventually all hooks should get replaced by events/subscribers.

Events/subscribers are more robust and flexible, but are more complex and require more code. We will not discuss them in this course, but stick to hooks which are still very much in use.

How to use hooks

Hooks are functions that follow a certain naming convention, defined by Drupal core or contributed modules.

Every function whose name starts with hook_ is hook that you can use. Using a hook is called implementing a hook.

Example

One of the hooks Drupal core defines is hook_user_login().

It's description: "The user just logged in".

If you want to execute some code every time a user logs in, this is the hook to implement.

To implement a certain hook, you must create a function in your module's MODULENAME.module file, that has the same name and parameters as the hook you want to implement, but replace the word 'hook' with the name of your module.

Assuming you want to implement hook_user_login() to show users a welcome message, you would do something like the following:

<?php
// File: MODULENAME/MODULENAME.module

use Drupal\User\UserInterface;

/**
 * Implements hook_user_login().
 */
Function MODULENAME_user_login(UserInterface $account) {
  \Drupal::messenger()->addMessage("Welcome!");
}

→ by convention, every hook implementation should be preceded by the comment Implements <hook_name_of_hook>().

You're not expected to remember all the function signatures of all the hooks you have available; every Drupal developer follows the same steps:

  • Search for a hook on https://api.drupal.org or via a text search through locally installed modules.
  • Read the documentation and/or the source code.
  • Copy paste the function signature (the name of the function + its parameters) into their own module.
  • Replace the word hook with the name of their module.
  • Add their own logic to the function's body.

Activity

  • Create a new module named my_hooks_demo.
  • Create a module file named my_hooks_demo.module.
  • Make sure the contents of the file starts with <?php and does has NO closing ?> tag.
  • Enable (install) the module.

The result should be:

my_hooks_demo/
├─ my_hooks_demo.module
Hide hints
show hints

Activity

  • Research hook_user_login()
  • Implement it in your own module to say Hello to users when they log in.
Hide hints
show hints

Troubleshooting

  • Have you cleared your caches?
  • Are you sure your module is enabled?
  • Have you given your module file and your hook implementation the correct name?
  • Are you importing the correct namespace?

Activity

hook_cache_flush() lets you do something when the caches are flushed.

  • Implement hook_cache_flush() to show a message like "You flushed the cache!" after you've flushed the cache.
Hide hints
show hints

Troubleshooting

  • Have you given your hook implementation the correct name?

Activity

  • Searching for "hook_" brings you to a page with all of Drupal core's functions that start with "hook_".
Hide hints
show hints

Summary

  • Hooks let you modify Drupal's behaviour without directly modifying Drupal's own source code.
  • All available hooks start with hook_.
  • To implement a hook, create a function with the same function signature in your module file, replacing the word 'hook' with the name of your module.