Profile picture for user admin
Daniel Sipos
06 Feb 2013

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.

Profile picture for user admin

Daniel Sipos

CEO @ Web Omelette

Danny founded WEBOMELETTE in 2012 as a passion project, mostly writing about Drupal problems he faced day to day, as well as about new technologies and things that he thought other developers would find useful. Now he now manages a team of developers and designers, delivering quality products that make businesses successful.

Contact us


pjcdawkins 06 Feb 2013 15:55


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

For instance:

Daniel Sipos 06 Feb 2013 15:50

Good idea. I'll keep that in

Good idea. I'll keep that in mind.


Craig 06 Feb 2013 16:09

Looking forward to this new

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.

shawn 06 Feb 2013 19:59

Only from module?

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

Daniel Sipos 06 Feb 2013 20:18

In reply to by shawn (not verified)

Hey there!

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.

Anonymous 07 Feb 2013 03:34

In reply to by shawn (not verified)


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()).

Rob Ellis 01 May 2013 21:51

Catching up on your posts

Hi Danny,

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

Add new comment