How To Create A Custom Token In Drupal 8?

Tokens are placeholders which act as a substitute for programmatically derived values. Drupal provides a lot of default tokens, but a case may arise where we need to write our own custom token depending on our needs.

In another case, we may also like to provide a token for some value which our module is generating. 

Creating a custom token involves two important parts
Declaring Tokens ( Using hook_token_info() )
Providing values for the declared token. ( Using hook_tokens() )

Let’s first learn to declare a token.

The hook_token_info() mainly returns an associative array of two components, ‘types’ and ‘tokens’.  The following snippet declares a token. 

/**
 * Implements hook_token_info().
 */
function my_module_token_token_info() {
  $info = [];
  $info['types']['my_token_group'] = ['name' => t('Custom Group'), 'description' => t('Custom Group')];
  $info['tokens']['my_token_group’][‘my_token’][] = 'A token to extract desired characters from Node body to be used in meta descriptions';
  return $info;
}

Here, 'my_token_group' is the machine-name for the token type, while, ‘my_token’ is the machine-name of the token within this group.
 
Then we provide the values for the declared token. Unlike Drupal 7, the hook_tokens() takes an extra $bubble_metadata as the parameter. This collects metadata for all of the data objects in $data.

/**
 * Implements hook_tokens().
 */
function  my_module_token_tokens($type, $tokens, array $data, array $options, \Drupal\Core\Render\BubbleableMetadata $bubbleable_metadata) {
  $replacements = [];
  if ($type == 'my_token_group') {

    foreach ($tokens as $name => $original) {
      // Find the desired token by name.
      switch ($name) {
        case ‘my_token’:
          $replacements[$original] = my_token_value();
          break;
      }
    }
  }
  return $replacements;
}

The my_token_value() function returns the replacement value for the token declared. The return value must be either plain text strings or some HTML markup implementing MarkupInterface
The token [my_token:my_token_value] can be used at any desired place in the Drupal Site.

Using  tokens in contributed modules

1. Path Auto
   The Pathauto module generates automatic path aliases for various kinds of content.The tokens provide the value for the replacement pattern. Eg. [node:content-type]/[node:title].
    
2. Metatag
   Metatag module uses the tokens to provide automatic metadata about a site.Tokens automatically provide value to meta descriptions, keywords, page title etc based on the content of the node.
   
   The user can have the flexibility to use any of the field information, it's length while creating custom tokens.
    
3. Flag
   Flag module provides an efficient flagging system which provides functionality like following a user, subscribe to a topic, etc.
   
   This module uses tokens to fill the values automatically like, [node:flag-vote-count] (providing the vote count). This helps in giving a user a better user experience.