function token_replace

Replaces all tokens in a given string with appropriate values.

Parameters

$text: A string potentially containing replaceable tokens.

$data: (optional) An array of keyed objects. For simple replacement scenarios 'node', 'user', and others are common keys, with an accompanying node or user object being the value. Some token types, like 'site', do not require any explicit information from $data and can be replaced even if it is empty.

$options: (optional) A keyed array of settings and flags to control the token replacement process. Supported options are:

  • langcode: A language code to be used when generating locale-sensitive tokens.
  • callback: A callback function that will be used to post-process the array of token replacements after they are generated. For example, a module using tokens in a text-only email might provide a callback to strip HTML entities from token values before they are inserted into the final text.
  • clear: A boolean flag indicating that tokens should be removed from the final text if no replacement value can be generated.
  • sanitize: A boolean flag indicating that tokens should be sanitized for display to a web browser. Defaults to TRUE. Developers who set this option to FALSE assume responsibility for running filter_xss(), check_plain() or other appropriate scrubbing functions before displaying data to users.

Return value

Text with tokens replaced.

24 calls to token_replace()
action_goto_action in drupal/core/modules/action/action.module
Redirects to a different URL.
action_message_action in drupal/core/modules/action/action.module
Sends a message to the current user's screen.
action_send_email_action in drupal/core/modules/action/action.module
Sends an e-mail message.
AreaTest::testRenderAreaToken in drupal/core/modules/views/lib/Drupal/views/Tests/Handler/AreaTest.php
Tests global tokens.
CommentTokenReplaceTest::testCommentTokenReplacement in drupal/core/modules/comment/lib/Drupal/comment/Tests/CommentTokenReplaceTest.php
Creates a comment, then tests the tokens generated from it.

... See full list

File

drupal/core/includes/token.inc, line 79
Drupal placeholder/token replacement system.

Code

function token_replace($text, array $data = array(), array $options = array()) {
  $text_tokens = token_scan($text);
  if (empty($text_tokens)) {
    return $text;
  }
  $replacements = array();
  foreach ($text_tokens as $type => $tokens) {
    $replacements += token_generate($type, $tokens, $data, $options);
    if (!empty($options['clear'])) {
      $replacements += array_fill_keys($tokens, '');
    }
  }

  // Optionally alter the list of replacement values.
  if (!empty($options['callback'])) {
    $function = $options['callback'];
    $function($replacements, $data, $options);
  }
  $tokens = array_keys($replacements);
  $values = array_values($replacements);
  return str_replace($tokens, $values, $text);
}