Need some help with your project? Contact me

I’m Hooked! 1: a weekly examiner of a Drupal hook.

So I decided to start a series of posts in which I choose every week a Drupal 7 hook and talk a bit about what you can do with it. If all goes well, it should come out every Wednesday but I am sure you understand if there are exceptions.

In Drupal, hooks are the way pluggable modules interact with the Drupal core. They are php functions with a special name construction that are called by core at specific times - depending on the hook itself.

I will explain their naming convention when I talk about the first one in the series: hook_username_alter(). For more general info about hooks, visit the API page.


OK, so let’s look at hook_username_alter(). Like I said, each Drupal hook (php function) is called by core at a specific time in its flow. This particular one gets called every time a username gets displayed on the page. Why? So you can alter it (change it). Usually, hooks which have the word alter in their name work also invoked from a theme - not just from a custom module. Their purpose is to change the display of something that gets outputted on the page, right before this happens.

For simplicity, I will talk about the implementation of hook_username_alter() from a module perspective. Leave the themes for later.

The name of every hook starts with the word hook. That is what you replace with the name of your module or theme. So to implement hook_username_alter() in a module called demo, you’d write the following: demo_username_alter(). This makes sure that each module on the site gets its fair chance to get hooked into core without name collisions. But wait. No parameters?


When you develop custom modules and work with hooks, the Drupal API website is your best friend.

There you can find references to all the available hooks and functions specific to Drupal. So if you check the documentation for hook_username_alter(), you’ll find that it takes 2 parameters: &$name and $account.

The $name paramenter is passed via reference and contains the username whereas the $account variable contains the user object. Just install the Devel module (if you haven't already) and use the krumo() or dpm() function to check out what’s inside these parameters. This can give you an idea of some of the stuff you can do with the hook.

Use case

Now, hook_username_alter() is a simple hook, designed to - for some reason - change the name of a user when it gets displayed on the page. So a basic use case is this:

function demo_username_alter(&$name, $account) {
  if($account->name == "admin") {
    $name = "Private Administrator Account";

Just replace demo with the name of your module. With this we accomplish the following:
Whenever the admin user’s name gets outputted on the page, Drupal will write instead of admin (which is and stays the actual name of the user as it is stored in the database and found in the $account object) Private Administrator Account. Pretty simple. Can you find a use for this in reality? Probably. Otherwise they would not have created this hook. There is also a Drupal function designed specially for outputting usernames, so you can check that out too.

So feel free to play with it and see what other logic you can apply. The $account object is pretty rich so you can use some other info there as well. For instance, change the name of admin only if the account has a certain permission role as well. Have fun.


How about providing real examples of the hooks as used in core/contrib?

For instance:

Good idea. I'll keep that in mind.


Looking forward to this new series. Might be interesting to also see a post about how a module can create their own hook as part of this series. I know there are already posts like that elsewhere, but it would help being part of this series.

what a good idea for a fun series of blog posts

Is it necessary to write a module to call a hook? Can this be done elsewhere in drupal?

Hey there!

Like I said in the post, there are a few hooks that can be called from themes as well, such as the ones that contain the word "alter" in them. This I think is for Drupal 7. The reason is that they allow you to make some theming changes by hooking into the normal Drupal process. I will bring some examples probably in future posts.

Rules events are a bit like hooks - you can configure actions responding to events through the Rules UI. Some are both hooks and events (invoked via rules_invoke_all()).

I'm hooked !

Nice article, thanks Danny.

Hi Danny,

I'm really digging your Hooked series. Very nice format and the information is straightforward and helpful. Keep up the good work!

Thanks Rob,
Much appreciated!

Add new comment

You can post comments in Markdown and basic HTML tags.
For code blocks, wrap your code within '~~~'. For example:
$var = 'my variable';