You are here

Drupal 7 - Making Your Own Tokens

According to the Drupal API:

Tokens are placeholders that can be put into text by using the syntax [type:token], where type is the machine-readable name of a token type, and token is the machine-readable name of a token within this group.

Many modules in and out of the Drupal core provide tokens which can be used in conjunction with token_replace() to provide myriad options for contextual data to be used in content on your sites. There are two hooks needed to implement your own tokens, the first one is the hook_token_info() function:

 * Implements hook_token_info().
function simple_tokens_token_info() {
  $types['andy_pangus'] = array(
    'name' => t("Andy Pangus Tokens"),
    'description' => t("Tokens for Andy Pangus."),
  // Andy Pangus specific tokens.
  $andy_pangus['user_name'] = array(
    'name' => t("User Name"),
    'description' => t("The {user}.name of the user viewing the content."),
  $andy_pangus['user_email'] = array(
    'name' => t("User Email"),
    'description' => t("The {user}.mail of the user viewing the content."),
  return array(
    'types' => $types,
    'tokens' => array(
      'andy_pangus' => $andy_pangus,

The above hook is used to provide a list of types and tokens to be displayed on text editing screens, so that people editing text can see what tokens are available. We define only one type, 'andy_pangus', which will be used to replace the 'type' of [type:token]. Then we define two tokens for use along with our token type and return that information as an associative array. Next, the hook_tokens() function is used to do the actual replacement of tokens when token_replace() is called:

 * Implements hook_tokens().
function simple_tokens_tokens($type, $tokens, array $data = array(), array $options = array()) {
  global $user;
  $replacements = array();
  if ($type == 'andy_pangus') {
    foreach ($tokens as $name => $original) {
      switch ($name) {
        case 'user_name':
          $replacements[$original] = $user->name;
        case 'user_email':
          $replacements[$original] = $user->mail;
  return $replacements;

The hook_tokens() function is invoked on each token-type group. This allows us to provide replacement text for any of the tokens in the groups that we defined with hook_token_info(). We pass each token of our type through a switch statement which handles replacing the token with its string representation. Lastly here's the file:

name = Simple Tokens
description = A module with a couple tokens
package = Andy Pangus Examples
core = 7.x
dependencies[] = token
files[] = simple_tokens.module

After you enable the module you may need to clear your cache to make the new tokens available. If you want to make sure they are ready for use, go to 'admin/help/token' to see them listed:

The tokens listed on the help page.

To test, create a new node, I used a basic page, and set the text area to use the PHP filter to render text. We'll use token_replace() to render the tokens on the page:

  <strong>Your user name:</strong> <?php print_r(token_replace('[andy_pangus:user_name]')); ?>
  <strong>Your email address:</strong>  <?php print_r(token_replace('[andy_pangus:user_email]')); ?>

Now save your node and check it out. Any time someone visits that page they will see the user name and email they have listed in their user information. While these tokens are very basic there are myriad possibilities which can be as complicated as you need them to be.

Download the source for this example.