drupal/core/themes/engines/twig/twig.engine

<?php

/**
 * @file
 * Handles integration of Twig templates with the Drupal theme system.
 */

use Drupal\Core\Extension\Extension;
use Drupal\Component\Utility\Settings;

/**
 * Implements hook_theme().
 */
function twig_theme($existing, $type, $theme, $path) {
  $templates = drupal_find_theme_functions($existing, array($theme));
  $templates += drupal_find_theme_templates($existing, '.html.twig', $path);
  return $templates;
}

/**
 * Implements hook_extension().
 */
function twig_extension() {
  return '.html.twig';
}

/**
 * Implements hook_init().
 */
function twig_init(Extension $theme) {
  $theme->load();
}

/**
 * Renders a Twig template.
 *
 * If the Twig debug setting is enabled, HTML comments including _theme() call
 * and template file name suggestions will surround the template markup.
 *
 * @param $template_file
 *   The file name of the template to render.
 * @param $variables
 *   A keyed array of variables that will appear in the output.
 *
 * @return
 *   The output generated by the template, plus any debug information.
 */
function twig_render_template($template_file, $variables) {
  $output = array(
    'debug_prefix'    => '',
    'debug_info'      => '',
    'rendered_markup' => \Drupal::service('twig')->loadTemplate($template_file)->render($variables),
    'debug_suffix'    => '',
  );
  if (Settings::get('twig_debug', FALSE)) {
    $output['debug_prefix'] .= "\n\n<!-- THEME DEBUG -->";
    $output['debug_prefix'] .= "\n<!-- CALL: _theme('{$variables['theme_hook_original']}') -->";
    // If there are theme suggestions, reverse the array so more specific
    // suggestions are shown first.
    if (!empty($variables['theme_hook_suggestions'])) {
      $variables['theme_hook_suggestions'] = array_reverse($variables['theme_hook_suggestions']);
    }
    // Add debug output for directly called suggestions like
    // '#theme' => 'comment__node__article'.
    if (strpos($variables['theme_hook_original'], '__') !== FALSE) {
      $derived_suggestions[] = $hook = $variables['theme_hook_original'];
      while ($pos = strrpos($hook, '__')) {
        $hook = substr($hook, 0, $pos);
        $derived_suggestions[] = $hook;
      }
      // Get the value of the base hook (last derived suggestion) and append it
      // to the end of all theme suggestions.
      $base_hook = array_pop($derived_suggestions);
      $variables['theme_hook_suggestions'] = array_merge($derived_suggestions, $variables['theme_hook_suggestions']);
      $variables['theme_hook_suggestions'][] = $base_hook;
    }
    if (!empty($variables['theme_hook_suggestions'])) {
      $extension = twig_extension();
      $current_template = basename($template_file);
      $suggestions = $variables['theme_hook_suggestions'];
      // Only add the original theme hook if it wasn't a directly called
      // suggestion.
      if (strpos($variables['theme_hook_original'], '__') === FALSE) {
        $suggestions[] = $variables['theme_hook_original'];
      }
      foreach ($suggestions as &$suggestion) {
        $template = strtr($suggestion, '_', '-') . $extension;
        $prefix = ($template == $current_template) ? 'x' : '*';
        $suggestion = $prefix . ' ' . $template;
      }
      $output['debug_info'] .= "\n<!-- FILE NAME SUGGESTIONS:\n   " . implode("\n   ", $suggestions) . "\n-->";
    }
    $output['debug_info']   .= "\n<!-- BEGIN OUTPUT from '{$template_file}' -->\n";
    $output['debug_suffix'] .= "\n<!-- END OUTPUT from '{$template_file}' -->\n\n";
  }
  return implode('', $output);
}

/**
 * Wrapper around render() for twig printed output.
 *
 * If an object is passed that has no __toString method an exception is thrown;
 * other objects are casted to string. However in the case that the object is an
 * instance of a Twig_Markup object it is returned directly to support auto
 * escaping.
 *
 * If an array is passed it is rendered via render() and scalar values are
 * returned directly.
 *
 * @param mixed $arg
 *   String, Object or Render Array
 *
 * @return
 *   The rendered output or an Twig_Markup object.
 *
 * @see render
 * @see TwigNodeVisitor
 */
function twig_render_var($arg) {
  // Check for numeric zero.
  if ($arg === 0) {
    return 0;
  }

  // Return early for NULL and also true for empty arrays.
  if ($arg == NULL) {
    return NULL;
  }

  // Keep Twig_Markup objects intact to prepare for later autoescaping support.
  if ($arg instanceOf Twig_Markup) {
    return $arg;
  }

  if (is_scalar($arg)) {
    return $arg;
  }

  if (is_object($arg)) {
    if (method_exists($arg, '__toString')) {
      return (string) $arg;
    }
    throw new Exception(t('Object of type "@class" cannot be printed.', array('@class' => get_class($arg))));
  }

  // This is a normal render array.
  return render($arg);
}

/**
 * Removes child elements from a copy of the original array.
 *
 * Creates a copy of the renderable array and removes child elements by key
 * specified throught filter's arguments. The copy can be printed without these
 * elements. The original renderable array is still available and can be used
 * to print child elements in their entirety in the twig template.
 *
 * @param array $element
 *   The parent renderable array to exclude the child items.
 * @param string[] $args, ...
 *   The string keys of $element to prevent printing.
 *
 * @return array
 *   The filtered renderable array.
 */
function twig_without($element) {
  $filtered_element = $element;
  $args = func_get_args();
  unset($args[0]);
  foreach ($args as $arg) {
    if (isset($filtered_element[$arg])) {
      unset($filtered_element[$arg]);
    }
  }
  return $filtered_element;
}