Token

A token is a placeholder in square brackets, such as [site:name] or [node:title], that Drupal swaps for a real value when it processes a piece of text. Tokens save you from typing values that change, like a site name, a page title or an author. The core Token API does the replacement; the contributed Token module adds a browser for looking tokens up.

How tokens work in Drupal 11

A token has the form [type:name]. The type is a group such as site, user or node. Some tokens chain: in [node:author:mail], author points to the user who created the node, and mail is a token of that user.

Code replaces tokens with the Drupal\Core\Utility\Token service, available as \Drupal::token(). Its replace() method takes the text, an array of data objects keyed by token type, and options. The options include langcode, callback and clear; with clear, tokens that get no value are removed from the result. Modules supply values by implementing two hooks: hook_token_info() lists the tokens they offer, and hook_tokens() returns the replacements. In Drupal 11.4, core implements them in hook classes with #[Hook('token_info')] and #[Hook('tokens')].

Among the token types that core modules define are site (such as name, slogan, URL and login URL), date (short, medium and long formats, time-since) and node (such as ID, title, body, URL and author). The Token module project page describes the contributed module as providing placeholder variables and an interface for browsing available tokens. Version 8.x-1.17 declares Drupal ^10.3 || ^11. The Pathauto project page lists Token as a requirement and says its alias patterns use tokens.

Example

Go to Configuration › People › Account settings. The email fields, such as Welcome (new user created by administrator), accept tokens. A subject of Welcome to [site:name] arrives as, for example, Welcome to Example Corp. Pathauto uses the same idea in URL aliases: a pattern is built from tokens such as [node:title], so each alias is generated automatically instead of typed by hand.

Common mistakes

• Assuming tokens work everywhere. Only code that calls the token service replaces them. The account email form, for example, lists the tokens it supports under Available variables.
• Treating the result as safe. The API documentation says the return value of replace() must be treated as unsafe, even when the input was safe markup. The caller chooses the sanitization.
• Mixing up meanings. Drupal also adds a CSRF token to some links as a token query parameter. That is a security check, not a placeholder.

For marketing and content teams

Use tokens where Drupal offers them to keep wording consistent: the site name in an email subject, or a title in a URL pattern. If the site name changes later, new messages that use [site:name] carry the new name. Ask your developer to install the Token module if you want a browser to pick tokens from.

Sources

• Drupal core 11.4.8: Token class (Drupal\Core\Utility\Token)
• Drupal core 11.4.8: Token hooks documentation (token.api.php)
• Drupal core 11.4.8: Site and date tokens (SystemTokensHooks.php)
• Drupal core 11.4.8: Node tokens (NodeTokensHooks.php)
• Drupal core 11.4.8: Account settings form (AccountSettingsForm.php)
• Drupal core 11.4.8: User module routing and menu links
• Drupal core 11.4.8: CSRF route processor (RouteProcessorCsrf.php)
• Token module project page
• Token module 8.x-1.17: token.info.yml
• Pathauto module project page