Token API hooks

There are two kinds of hooks that specify tokens data in Drupal. hook_token_info supplies information about tokens, and hook_tokens supplies the token values.

hook_token_info

This hook provides information about available placeholder tokens. It returns an associative array structure denoting two sets of information:

• types - An associative array of token types. The array key is the type ID, which maps to the kind of information being handled, such as site or date or node.
  The array value consists of:

  • name - The translated human-readable short name of the token type, eg. "Site", "Date" or "Nodes".

  • description - Optional translated human-readable description of the token type.

  • needs-data - The type of data that needs to be supplied to fulfil tokens of this type. For example, if this type needs a node, needs-data must be 'node'.

• tokens - An associative array of tokens. Outer array is keyed by group name. Within this is another associative array keyed by token name.
  The array values consist of:

  • name - The translated human-readable short name of the token.

  • description - A translated longer description of the token.

  • type - A 'needs-data' data type supplied by this token, which should match a 'needs-data' value from another token type.

So the output might look something like this:

[
  'types' => [
    'node' => [
      'name' => 'Nodes',
      'description' => 'Tokens related to individual nodes',
      'needs-data' => 'node',
    ],
  ],
  'tokens' => [
    'node' => [
      'nid' => [
        'name' => 'Node ID',
        'description' => 'The unique ID of the node.',
      ],
      'title' => [
        'name' => 'Node Title',
      ],
    ],
  ],
]

hook_token_info is more fully documented at api.drupal.org.

Classic functional implementation example

Add the following to your module's .module file.

/**
 * Implements hook_token_info().
 */
function mymodule_token_info(): array {
  $output['types']['myentity'] = [
    'name' => t('My Entity'),
    'description' => t('My custom entity.'),
    'needs-data' => 'myentity',
  ];

  $output['tokens']['myentity']['eid'] = [
    'name' => t('ID'),
    'description' => t('My custom entity ID.'),
  ];

  return $output;
}

Object-oriented implementation example (for Drupal 11.1+)

Add a file to your module under src/Hook/MyModuleHooks.php.

<?php

namespace Drupal\mymodule\Hook;

use Drupal\Core\Hook\Attribute\Hook;
use Drupal\Core\StringTranslation\StringTranslationTrait;

/**
 * Hook implementations for my module.
 */
class MyModuleHooks {

  use StringTranslationTrait;

  /**
   * Implements hook_token_info().
   */
  #[Hook('token_info')]
  public function tokenInfo(): array {
    $output['types']['myentity'] = [
      'name' => $this->t('My Entity'),
      'description' => $this->t('My custom entity.'),
      'needs-data' => 'myentity',
    ];

    $output['tokens']['myentity']['eid'] = [
      'name' => $this->t('ID'),
      'description' => $this->t('My custom entity ID.'),
    ];

    return $output;
  }

}

Alter hook

hook_token_info_alter can be used to manipulate the metadata about available tokens.

Example:

/**
 * Implements hook_token_info_alter().
 */
function mymodule_token_info_alter(array &$data): void {
  if (!empty($data['tokens']['myentity']['eid'])) {
    $data['tokens']['myentity']['eid'] = t('My fancy entity ID');
  }
}

hook_token_info_alter is more fully documented at api.drupal.org.

hook_tokens

This hook generates the replacements for the tokens defined in hook_token_info. The implementation is generally more freeform than what hook_token_info suggests; this allows for additional parameters to be handled.

The hook implementation takes the following parameters:

• $type - a string that contains the machine-readable name of the type/group of token being replaced. This is the same as the index of the types array from hook_token_info. Examples include 'node', 'site', 'date' and so on.

• $tokens - an array of tokens that are due to be replaced. The keys are the machine-readable token names, and the values are the raw [type:token] strings from the original text. This provides a quick way to loop through the tokens.

• $data - an associative array of data objects or entities to be used when generating replacement values. This is the same $data argument as what you would see in \Drupal::token()->replace().

• $options - an associative array of options for token replacement. This is the same $options argument as what you would see in \Drupal::token()->replace().

• $bubbleable_metadata - the same as the argument of the same name from \Drupal::token()->replace(), with the difference being that the argument for the hook is guaranteed to be of type Drupal\Core\Render\BubbleableMetadata instead of being optional.

The hook implementation returns an array of token replacements, keyed by the original token string.

[
  '[node:nid]' => '123',
  '[node:title]' => 'Super easy vegetarian pasta bake',
]

If your method does not provide an implementation for a given token, don't add it to the list of replacements.

hook_tokens is more fully documented at api.drupal.org.

Classic functional implementation example

Add the following to your module's .module file.

/**
 * Implements hook_tokens().
 */
function mymodule_tokens($type, $tokens, array $data, array $options, \Drupal\Core\Render\BubbleableMetadata $bubbleable_metadata): array {
  $replacements = [];
  if ($type === 'myentity' && !empty($data['myentity'])) {
    $myentity = $data['myentity'];
    foreach ($tokens as $name => $original) {
      switch($name) {
        case 'eid':
          $replacements[$original] = $myentity->id();
          break;
      }
    }
  }
  return $replacements;
}

Object-oriented implementation example (for Drupal 11.1+)

Add a file to your module under src/Hook/MyModuleHooks.php.

<?php

namespace Drupal\mymodule\Hook;

use Drupal\Core\Hook\Attribute\Hook;
use Drupal\Core\StringTranslation\StringTranslationTrait;

/**
 * Hook implementations for my module.
 */
class MyModuleHooks {

  use StringTranslationTrait;

  /**
   * Implements hook_tokens().
   */
  #[Hook('tokens')]
  public function tokens($type, $tokens, array $data, array $options, \Drupal\Core\Render\BubbleableMetadata $bubbleable_metadata): array {
    $replacements = [];
    if ($type === 'myentity' && !empty($data['myentity'])) {
      $myentity = $data['myentity'];
      foreach ($tokens as $name => $original) {
        switch($name) {
          case 'eid':
          $replacements[$original] = $myentity->id();
              break;
        }
      }
    }
    return $replacements;
  }

}

Alter hook

hook_tokens_alter can be used to modify the token replacements array.

Example:

/**
 * Implements hook_tokens_alter().
 */
function mymodule_tokens_alter(array &$replacements, array $context): void {
  if ($context['type'] === 'myentity' && !empty($context['data']['myentity'])) {
    $myentity = $context['data']['myentity'];
    $replacements[$context['tokens']['eid']] = $myentity->id() . '-2';
  }
}

hook_tokens_alter is more fully documented at api.drupal.org.