token_replace

Versions

mediamosa-21

token_replace($text, array $data = array(), array $options = array())

Replace 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:

• language: A language object 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.

Code

includes/token.inc, line 76

<?php
function token_replace($text, array $data = array(), array $options = array()) {
  $replacements = array();
  foreach (token_scan($text) 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_exists($options['callback'])) {
    $function = $options['callback'];
    $function($replacements, $data, $options);
  }

  $tokens = array_keys($replacements);
  $values = array_values($replacements);

  return str_replace($tokens, $values, $text);
}
?>