public function Token::replace in Drupal 8

Same name and namespace in other branches

9 core/lib/Drupal/Core/Utility/Token.php \Drupal\Core\Utility\Token::replace()

Replaces all tokens in a given string with appropriate values.

Parameters

string $text: An HTML string containing replaceable tokens. The caller is responsible for calling \Drupal\Component\Utility\Html::escape() in case the $text was plain text.

array $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.

array $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.
clear: A boolean flag indicating that tokens should be removed from the final text if no replacement value can be generated.

\Drupal\Core\Render\BubbleableMetadata|null $bubbleable_metadata: (optional) An object to which static::generate() and the hooks and functions that it invokes will add their required bubbleable metadata.

To ensure that the metadata associated with the token replacements gets attached to the same render array that contains the token-replaced text, callers of this method are encouraged to pass in a BubbleableMetadata object and apply it to the corresponding render array. For example:

$bubbleable_metadata = new BubbleableMetadata();
$build['#markup'] = $token_service
  ->replace('Tokens: [node:nid] [current-user:uid]', [
  'node' => $node,
], [], $bubbleable_metadata);
$bubbleable_metadata
  ->applyTo($build);

When the caller does not pass in a BubbleableMetadata object, this method creates a local one, and applies the collected metadata to the Renderer's currently active render context.

Return value

string The token result is the entered HTML text with tokens replaced. The caller is responsible for choosing the right escaping / sanitization. If the result is intended to be used as plain text, using PlainTextOutput::renderFromHtml() is recommended. If the result is just printed as part of a template relying on Twig autoescaping is possible, otherwise for example the result can be put into #markup, in which case it would be sanitized by Xss::filterAdmin().

File

core/lib/Drupal/Core/Utility/Token.php, line 185

Class

Token: Drupal placeholder/token replacement system.

Namespace

Drupal\Core\Utility

Code

public function replace($text, array $data = [], array $options = [], BubbleableMetadata $bubbleable_metadata = NULL) {
  $text_tokens = $this
    ->scan($text);
  if (empty($text_tokens)) {
    return $text;
  }
  $bubbleable_metadata_is_passed_in = (bool) $bubbleable_metadata;
  $bubbleable_metadata = $bubbleable_metadata ?: new BubbleableMetadata();
  $replacements = [];
  foreach ($text_tokens as $type => $tokens) {
    $replacements += $this
      ->generate($type, $tokens, $data, $options, $bubbleable_metadata);
    if (!empty($options['clear'])) {
      $replacements += array_fill_keys($tokens, '');
    }
  }

  // Escape the tokens, unless they are explicitly markup.
  foreach ($replacements as $token => $value) {
    $replacements[$token] = $value instanceof MarkupInterface ? $value : new HtmlEscapedText($value);
  }

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

  // If a local $bubbleable_metadata object was created, apply the metadata
  // it collected to the renderer's currently active render context.
  if (!$bubbleable_metadata_is_passed_in && $this->renderer
    ->hasRenderContext()) {
    $build = [];
    $bubbleable_metadata
      ->applyTo($build);
    $this->renderer
      ->render($build);
  }
  return str_replace($tokens, $values, $text);
}

You are here