Skip to main content

Create your own tokens in Drupal 7

Tokens are a pretty powerful weapon to have in your arsenal, and they actually come in useful a lot if you remember that they're there.

If you haven't used them before, tokens are essentially text placeholders - they can be static text, variables, field values, whatever you want really.

The Token API is now part of Drupal 7 core and as it turns out, using it to create your own tokens is super easy - you just need a couple of hooks.

The first hook, hook_token_info(), is used to declare any custom tokens.

 * Implements hook_token_info().
function module_name_token_info() {
  $info = array();
  // Define a new token type.
  $info['types']['my_custom_tokens'] = array(
    'name' => t('My custom tokens'),
    'description' => t('A token type for my custom tokens.'),
  // Define any new tokens.
  $info['tokens']['my_custom_tokens']['my_cool_token'] = array(
    'name' => t('My cool token'),
    'description' => t('A token I use to show that I am cool.'),
  return $info;

We are creating our own custom token type here too but if you just want to put your token in an already existing type, you can get a list of the existing tokens and types by calling token_get_info().

Now that our new token is good and defined, we just need to give it some content with hook_tokens().

 * Implements hook_tokens().
function module_name_tokens($type, $tokens, array $data = array(), array $options = array()) {
  $replacements = array();

  if ($type == 'my_custom_tokens') {
    // Loop through the available tokens.
    foreach ($tokens as $name => $original) {
      // Find our custom tokens by name.
      switch ($name) {
        case 'my_cool_token':
          // Work out the value of our token.
          $value = 'Whatever we want the token to be';
          // Give our token it's value!
          $replacements[$original] = $value;

  return $replacements;

That's it! Our token should now be available and appear in the list of tokens wherever tokens are available.