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.

Naming

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?

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.