function token_build_tree

Build a tree array of tokens, commonly used for rendering the token browser.

Parameters

string $token_type: The token type.

array $options: An array of options including the following keys:

• flat: A boolean if TRUE will only make a flat array of tokens, otherwise child tokens will be inside the 'children' parameter of a token.
• restricted: A boolean if TRUE will show restricted tokens. Otherwise they will be hidden. Default is FALSE.
• depth: An integer with the maximum number of token levels to recurse.
• parents: An optional array with the current parents of the tokens.

Return value

array: An array of token information, keyed by the full token and each containing:

• name: The translated human-readable name of the token.
• description: The translated description of the token.
• raw token: The full token (same as the key of this entry).
• restricted: Optionally present if the token should only be available in trusted environments.
• deprecated: Optionally present if the token will be removed from a future version of Backdrop and should not be used.
• token: The last portion of the token. e.g. in [node:nid], the value would be nid.

File

core/includes/token.inc, line 507

Backdrop placeholder/token replacement system.

Code

function token_build_tree($token_type, array $options = array()) {
  global $language_content;

  $cache_token = cache('token');

  // Static cache of already built token trees.
  $trees = &backdrop_static(__FUNCTION__, array());

  $options += array(
    'restricted' => FALSE,
    'depth' => 4,
    'data' => array(),
    'values' => FALSE,
    'flat' => FALSE,
  );

  // Do not allow past the maximum token information depth.
  $options['depth'] = min($options['depth'], TOKEN_MAX_DEPTH);

  $tree_cid = "tree:{$token_type}:{$language_content->langcode}:{$options['depth']}";

  // If we do not have this base tree in the static cache, check {cache_token}
  // otherwise generate and store it in the cache.
  if (!isset($trees[$tree_cid])) {
    if ($cache = $cache_token->get($tree_cid)) {
      $trees[$tree_cid] = $cache->data;
    }
    else {
      $options['parents'] = array();
      $trees[$tree_cid] = _token_build_tree($token_type, $options);
      cache_set($tree_cid, $trees[$tree_cid], 'cache', CACHE_PERMANENT);
    }
  }

  $tree = $trees[$tree_cid];

  // If the user has requested a flat tree, convert it.
  if (!empty($options['flat'])) {
    $tree = token_flatten_tree($tree);
  }

  // Fill in token values.
  if (!empty($options['values'])) {
    $token_values = array();
    foreach ($tree as $token => $token_info) {
      if (!empty($token_info['dynamic']) || !empty($token_info['restricted'])) {
        continue;
      }
      elseif (!isset($token_info['value'])) {
        $token_values[$token_info['token']] = $token;
      }
    }
    if (!empty($token_values)) {
      $token_values = token_generate($token_type, $token_values, $options['data']);
      foreach ($token_values as $token => $replacement) {
        $tree[$token]['value'] = $replacement;
      }
    }
  }

  return $tree;
}