TwigTweakExtension.php in Twig Tweak 3.1.x

Namespace

Drupal\twig_tweak

File

src/TwigTweakExtension.php

<?php

namespace Drupal\twig_tweak;

use Drupal\Component\Utility\NestedArray;
use Drupal\Component\Utility\Unicode;
use Drupal\Component\Uuid\Uuid;
use Drupal\Core\Cache\CacheableMetadata;
use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Extension\ModuleHandlerInterface;
use Drupal\Core\Field\FieldItemInterface;
use Drupal\Core\Field\FieldItemListInterface;
use Drupal\Core\Link;
use Drupal\Core\Render\Element;
use Drupal\Core\Render\Markup;
use Drupal\Core\Site\Settings;
use Drupal\Core\Theme\ThemeManagerInterface;
use Drupal\Core\Url;
use Drupal\image\Entity\ImageStyle;
use Twig\Environment;
use Twig\Extension\AbstractExtension;
use Twig\Markup as TwigMarkup;
use Twig\TwigFilter;
use Twig\TwigFunction;

/**
 * Twig extension with some useful functions and filters.
 *
 * The extension consumes quite a lot of dependencies. Most of them are not used
 * on each page request. For performance reasons services are wrapped in static
 * callbacks.
 */
class TwigTweakExtension extends AbstractExtension {

  /**
   * The module handler to invoke alter hooks.
   *
   * @var \Drupal\Core\Extension\ModuleHandlerInterface
   */
  protected $moduleHandler;

  /**
   * The theme manager to invoke alter hooks.
   *
   * @var \Drupal\Core\Theme\ThemeManagerInterface
   */
  protected $themeManager;

  /**
   * Constructs the TwigTweakExtension object.
   */
  public function __construct(ModuleHandlerInterface $module_handler, ThemeManagerInterface $theme_manager) {
    $this->moduleHandler = $module_handler;
    $this->themeManager = $theme_manager;
  }

  /**
   * {@inheritdoc}
   */
  public function getFunctions() : array {
    $context_options = [
      'needs_context' => TRUE,
    ];
    $all_options = [
      'needs_environment' => TRUE,
      'needs_context' => TRUE,
    ];
    $functions = [
      new TwigFunction('drupal_view', 'views_embed_view'),
      new TwigFunction('drupal_view_result', 'views_get_view_result'),
      new TwigFunction('drupal_block', [
        self::class,
        'drupalBlock',
      ]),
      new TwigFunction('drupal_region', [
        self::class,
        'drupalRegion',
      ]),
      new TwigFunction('drupal_entity', [
        self::class,
        'drupalEntity',
      ]),
      new TwigFunction('drupal_entity_form', [
        self::class,
        'drupalEntityForm',
      ]),
      new TwigFunction('drupal_field', [
        self::class,
        'drupalField',
      ]),
      new TwigFunction('drupal_menu', [
        self::class,
        'drupalMenu',
      ]),
      new TwigFunction('drupal_form', [
        self::class,
        'drupalForm',
      ]),
      new TwigFunction('drupal_image', [
        self::class,
        'drupalImage',
      ]),
      new TwigFunction('drupal_token', [
        self::class,
        'drupalToken',
      ]),
      new TwigFunction('drupal_config', [
        self::class,
        'drupalConfig',
      ]),
      new TwigFunction('drupal_dump', [
        self::class,
        'drupalDump',
      ], $context_options),
      new TwigFunction('dd', [
        self::class,
        'drupalDump',
      ], $context_options),
      new TwigFunction('drupal_title', [
        self::class,
        'drupalTitle',
      ]),
      new TwigFunction('drupal_url', [
        self::class,
        'drupalUrl',
      ]),
      new TwigFunction('drupal_link', [
        self::class,
        'drupalLink',
      ]),
      new TwigFunction('drupal_messages', function () : array {
        return [
          '#type' => 'status_messages',
        ];
      }),
      new TwigFunction('drupal_breadcrumb', [
        self::class,
        'drupalBreadcrumb',
      ]),
      new TwigFunction('drupal_breakpoint', [
        self::class,
        'drupalBreakpoint',
      ], $all_options),
      // @phpcs:ignore Drupal.Arrays.Array.LongLineDeclaration
      new TwigFunction('drupal_contextual_links', [
        self::class,
        'drupalContextualLinks',
      ]),
    ];
    $this->moduleHandler
      ->alter('twig_tweak_functions', $functions);
    $this->themeManager
      ->alter('twig_tweak_functions', $functions);
    return $functions;
  }

  /**
   * {@inheritdoc}
   */
  public function getFilters() : array {
    $filters = [
      new TwigFilter('token_replace', [
        self::class,
        'tokenReplaceFilter',
      ]),
      new TwigFilter('preg_replace', [
        self::class,
        'pregReplaceFilter',
      ]),
      new TwigFilter('image_style', [
        self::class,
        'imageStyleFilter',
      ]),
      new TwigFilter('transliterate', [
        self::class,
        'transliterateFilter',
      ]),
      new TwigFilter('check_markup', 'check_markup'),
      new TwigFilter('format_size', 'format_size'),
      new TwigFilter('truncate', [
        Unicode::class,
        'truncate',
      ]),
      new TwigFilter('view', [
        self::class,
        'viewFilter',
      ]),
      new TwigFilter('with', [
        self::class,
        'withFilter',
      ]),
      new TwigFilter('children', [
        self::class,
        'childrenFilter',
      ]),
      new TwigFilter('file_uri', [
        self::class,
        'fileUriFilter',
      ]),
      new TwigFilter('file_url', [
        self::class,
        'fileUrlFilter',
      ]),
      new TwigFilter('translation', [
        self::class,
        'entityTranslation',
      ]),
      new TwigFilter('cache_metadata', [
        self::class,
        'CacheMetadata',
      ]),
    ];
    if (Settings::get('twig_tweak_enable_php_filter')) {
      $filters[] = new TwigFilter('php', [
        self::class,
        'phpFilter',
      ], [
        'needs_context' => TRUE,
      ]);
    }
    $this->moduleHandler
      ->alter('twig_tweak_filters', $filters);
    $this->themeManager
      ->alter('twig_tweak_filters', $filters);
    return $filters;
  }

  /**
   * {@inheritdoc}
   */
  public function getTests() : array {
    $tests = [];
    $this->moduleHandler
      ->alter('twig_tweak_tests', $tests);
    $this->themeManager
      ->alter('twig_tweak_tests', $tests);
    return $tests;
  }

  /**
   * Builds the render array for a block.
   */
  public static function drupalBlock(string $id, array $configuration = [], bool $wrapper = TRUE) : array {
    return \Drupal::service('twig_tweak.block_view_builder')
      ->build($id, $configuration, $wrapper);
  }

  /**
   * Builds the render array of a given region.
   */
  public static function drupalRegion(string $region, ?string $theme = NULL) : array {
    return \Drupal::service('twig_tweak.region_view_builder')
      ->build($region, $theme);
  }

  /**
   * Returns the render array to represent an entity.
   */
  public static function drupalEntity(string $entity_type, string $selector, string $view_mode = 'full', ?string $langcode = NULL, bool $check_access = TRUE) : array {
    $storage = \Drupal::entityTypeManager()
      ->getStorage($entity_type);
    if (Uuid::isValid($selector)) {
      $entities = $storage
        ->loadByProperties([
        'uuid' => $selector,
      ]);
      $entity = reset($entities);
    }
    else {
      $entity = $storage
        ->load($selector);
    }
    if ($entity) {
      return \Drupal::service('twig_tweak.entity_view_builder')
        ->build($entity, $view_mode, $langcode, $check_access);
    }
    return [];
  }

  /**
   * Gets the built and processed entity form for the given entity type.
   */
  public static function drupalEntityForm(string $entity_type, ?string $id = NULL, string $form_mode = 'default', array $values = [], bool $check_access = TRUE) : array {
    $entity_storage = \Drupal::entityTypeManager()
      ->getStorage($entity_type);
    $entity = $id ? $entity_storage
      ->load($id) : $entity_storage
      ->create($values);
    if ($entity) {
      return \Drupal::service('twig_tweak.entity_form_view_builder')
        ->build($entity, $form_mode, $check_access);
    }
    return [];
  }

  /**
   * Returns the render array for a single entity field.
   */
  public static function drupalField(string $field_name, string $entity_type, string $id, $view_mode = 'full', string $langcode = NULL, bool $check_access = TRUE) : array {
    $entity = \Drupal::entityTypeManager()
      ->getStorage($entity_type)
      ->load($id);
    if ($entity) {
      return \Drupal::service('twig_tweak.field_view_builder')
        ->build($entity, $field_name, $view_mode, $langcode, $check_access);
    }
    return [];
  }

  /**
   * Returns the render array for Drupal menu.
   */
  public static function drupalMenu(string $menu_name, int $level = 1, int $depth = 0, bool $expand = FALSE) : array {
    return \Drupal::service('twig_tweak.menu_view_builder')
      ->build($menu_name, $level, $depth, $expand);
  }

  /**
   * Builds and processes a form for a given form ID.
   *
   * @param string $form_id
   *   The form ID.
   * @param mixed $args
   *   Additional arguments are passed to form constructor.
   *
   * @return array
   *   A render array to represent the form.
   */
  public static function drupalForm(string $form_id, ...$args) : array {
    $callback = [
      \Drupal::formBuilder(),
      'getForm',
    ];
    return call_user_func_array($callback, func_get_args());
  }

  /**
   * Builds an image.
   */
  public static function drupalImage(string $selector, string $style = NULL, array $attributes = [], bool $responsive = FALSE, bool $check_access = TRUE) : array {

    // Determine selector type by its value.
    if (preg_match('/^\\d+$/', $selector)) {
      $selector_type = 'fid';
    }
    elseif (Uuid::isValid($selector)) {
      $selector_type = 'uuid';
    }
    else {
      $selector_type = 'uri';
    }
    $files = \Drupal::entityTypeManager()
      ->getStorage('file')
      ->loadByProperties([
      $selector_type => $selector,
    ]);

    // To avoid ambiguity render nothing unless exact one image has been found.
    if (count($files) != 1) {
      return [];
    }
    $file = reset($files);
    return \Drupal::service('twig_tweak.image_view_builder')
      ->build($file, $style, $attributes, $responsive, $check_access);
  }

  /**
   * Replaces a given token with appropriate value.
   *
   * @param string $token
   *   A replaceable token.
   * @param 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.
   * @param array $options
   *   (optional) A keyed array of settings and flags to control the token
   *   replacement process.
   *
   * @return string
   *   The token value.
   *
   * @see \Drupal\Core\Utility\Token::replace()
   */
  public static function drupalToken(string $token, array $data = [], array $options = []) : string {
    return \Drupal::token()
      ->replace("[{$token}]", $data, $options);
  }

  /**
   * Retrieves data from a given configuration object.
   *
   * @param string $name
   *   The name of the configuration object to construct.
   * @param string $key
   *   A string that maps to a key within the configuration data.
   *
   * @return mixed
   *   The data that was requested.
   */
  public static function drupalConfig(string $name, string $key) {
    return \Drupal::config($name)
      ->get($key);
  }

  /**
   * Dumps information about variables.
   *
   * @param array $context
   *   Variables from the Twig template.
   * @param mixed $variable
   *   (optional) The variable to dump.
   */
  public static function drupalDump(array $context, $variable = NULL) : void {
    $var_dumper = '\\Symfony\\Component\\VarDumper\\VarDumper';
    if (class_exists($var_dumper)) {
      call_user_func($var_dumper . '::dump', func_num_args() == 1 ? $context : $variable);
    }
    else {
      trigger_error('Could not dump the variable because symfony/var-dumper component is not installed.', E_USER_WARNING);
    }
  }

  /**
   * Returns a title for the current route.
   */
  public static function drupalTitle() : array {
    $title = \Drupal::service('title_resolver')
      ->getTitle(\Drupal::request(), \Drupal::routeMatch()
      ->getRouteObject());
    $build['#markup'] = render($title);
    $build['#cache']['contexts'] = [
      'url',
    ];
    return $build;
  }

  /**
   * Generates a URL from an internal path.
   *
   * @param string $user_input
   *   User input for a link or path.
   * @param array $options
   *   (optional) An array of options.
   * @param bool $check_access
   *   (optional) Indicates that access check is required.
   *
   * @return \Drupal\Core\Url|null
   *   A new Url object or null if the URL is not accessible.
   *
   * @see \Drupal\Core\Url::fromUserInput()
   */
  public static function drupalUrl(string $user_input, array $options = [], bool $check_access = FALSE) : ?Url {
    if (isset($options['langcode'])) {
      $language_manager = \Drupal::languageManager();
      if ($language = $language_manager
        ->getLanguage($options['langcode'])) {
        $options['language'] = $language;
      }
    }
    if (!in_array($user_input[0], [
      '/',
      '#',
      '?',
    ])) {
      $user_input = '/' . $user_input;
    }
    $url = Url::fromUserInput($user_input, $options);
    return !$check_access || $url
      ->access() ? $url : NULL;
  }

  /**
   * Generates a link from an internal path.
   *
   * @param string|\Twig\Markup $text
   *   The text to be used for the link.
   * @param string $user_input
   *   User input for a link or path.
   * @param array $options
   *   (optional) An array of options.
   * @param bool $check_access
   *   (optional) Indicates that access check is required.
   *
   * @return \Drupal\Core\Link|null
   *   A new Link object or null of the URL is not accessible.
   *
   * @see \Drupal\Core\Link::fromTextAndUrl()
   */
  public static function drupalLink($text, string $user_input, array $options = [], bool $check_access = FALSE) : ?Link {
    $url = self::drupalUrl($user_input, $options, $check_access);
    if ($url) {

      // The text has been processed by twig already, convert it to a safe
      // object for the render system.
      // @see \Drupal\Core\Template\TwigExtension::getLink()
      if ($text instanceof TwigMarkup) {
        $text = Markup::create($text);
      }
      return Link::fromTextAndUrl($text, $url);
    }
    return NULL;
  }

  /**
   * Builds the breadcrumb.
   */
  public static function drupalBreadcrumb() : array {
    return \Drupal::service('breadcrumb')
      ->build(\Drupal::routeMatch())
      ->toRenderable();
  }

  /**
   * Builds contextual links.
   *
   * @param string $id
   *   A serialized representation of a #contextual_links property value array.
   *
   * @return array
   *   A renderable array representing contextual links.
   *
   * @see https://www.drupal.org/node/2133283
   */
  public static function drupalContextualLinks(string $id) : array {
    $build['#cache']['contexts'] = [
      'user.permissions',
    ];
    if (\Drupal::currentUser()
      ->hasPermission('access contextual links')) {
      $build['#type'] = 'contextual_links_placeholder';
      $build['#id'] = $id;
    }
    return $build;
  }

  /**
   * Emits a breakpoint to the debug client.
   *
   * @param \Twig\Environment $environment
   *   The Twig environment instance.
   * @param array $context
   *   Variables from the current Twig template.
   */
  public static function drupalBreakpoint(Environment $environment, array $context) : void {
    if (function_exists('xdebug_break')) {
      xdebug_break();
    }
    else {
      trigger_error('Could not make a break because xdebug is not available.', E_USER_WARNING);
    }
  }

  /**
   * Replaces all tokens in a given string with appropriate values.
   *
   * @param string $text
   *   An HTML string containing replaceable tokens.
   * @param 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.
   * @param array $options
   *   (optional) A keyed array of settings and flags to control the token
   *   replacement process.
   *
   * @return string
   *   The entered HTML text with tokens replaced.
   */
  public static function tokenReplaceFilter(string $text, array $data = [], array $options = []) : string {
    return \Drupal::token()
      ->replace($text, $data, $options);
  }

  /**
   * Performs a regular expression search and replace.
   *
   * @param string $text
   *   The text to search and replace.
   * @param string $pattern
   *   The pattern to search for.
   * @param string $replacement
   *   The string to replace.
   *
   * @return string
   *   The new text if matches are found, otherwise unchanged text.
   */
  public static function pregReplaceFilter(string $text, string $pattern, string $replacement) : string {
    return preg_replace($pattern, $replacement, $text);
  }

  /**
   * Returns the URL of this image derivative for an original image path or URI.
   *
   * @param string|null $path
   *   The path or URI to the original image.
   * @param string $style
   *   The image style.
   *
   * @return string|null
   *   The absolute URL where a style image can be downloaded, suitable for use
   *   in an <img> tag. Requesting the URL will cause the image to be created.
   */
  public static function imageStyleFilter(?string $path, string $style) : ?string {
    if (!$path) {
      trigger_error('Image path is empty.');
      return NULL;
    }
    if (!($image_style = ImageStyle::load($style))) {
      trigger_error(sprintf('Could not load image style %s.', $style));
      return NULL;
    }
    if (!$image_style
      ->supportsUri($path)) {
      trigger_error(sprintf('Could not apply image style %s.', $style));
      return NULL;
    }
    return file_url_transform_relative($image_style
      ->buildUrl($path));
  }

  /**
   * Transliterates text from Unicode to US-ASCII.
   *
   * @param string $text
   *   The $text to transliterate.
   * @param string $langcode
   *   (optional) The language code of the language the string is in. Defaults
   *   to 'en' if not provided. Warning: this can be unfiltered user input.
   * @param string $unknown_character
   *   (optional) The character to substitute for characters in $string without
   *   transliterated equivalents. Defaults to '?'.
   * @param int $max_length
   *   (optional) If provided, return at most this many characters, ensuring
   *   that the transliteration does not split in the middle of an input
   *   character's transliteration.
   *
   * @return string
   *   $string with non-US-ASCII characters transliterated to US-ASCII
   *   characters, and unknown characters replaced with $unknown_character.
   */
  public static function transliterateFilter(string $text, string $langcode = 'en', string $unknown_character = '?', int $max_length = NULL) {
    return \Drupal::transliteration()
      ->transliterate($text, $langcode, $unknown_character, $max_length);
  }

  /**
   * Returns a render array for entity, field list or field item.
   *
   * @param object|null $object
   *   The object to build a render array from.
   * @param string|array $view_mode
   *   Can be either the name of a view mode, or an array of display settings.
   * @param string $langcode
   *   (optional) For which language the entity should be rendered, defaults to
   *   the current content language.
   * @param bool $check_access
   *   (optional) Indicates that access check for an entity is required.
   *
   * @return array
   *   A render array to represent the object.
   */
  public static function viewFilter(?object $object, $view_mode = 'default', string $langcode = NULL, bool $check_access = TRUE) : array {
    $build = [];
    if ($object instanceof FieldItemListInterface || $object instanceof FieldItemInterface) {
      $build = $object
        ->view($view_mode);

      /** @var \Drupal\Core\Entity\Plugin\DataType\EntityAdapter $parent */
      if ($parent = $object
        ->getParent()) {
        CacheableMetadata::createFromRenderArray($build)
          ->merge(CacheableMetadata::createFromObject($parent
          ->getEntity()))
          ->applyTo($build);
      }
    }
    elseif ($object instanceof EntityInterface) {
      $build = \Drupal::service('twig_tweak.entity_view_builder')
        ->build($object, $view_mode, $langcode, $check_access);
    }
    return $build;
  }

  /**
   * Adds new element to the array.
   *
   * @param array $build
   *   The renderable array to add the child item.
   * @param mixed $key
   *   The key of the new element.
   * @param mixed $element
   *   The element to add.
   *
   * @return array
   *   The modified array.
   */
  public static function withFilter(array $build, $key, $element) : array {
    if (is_array($key)) {
      NestedArray::setValue($build, $key, $element);
    }
    else {
      $build[$key] = $element;
    }
    return $build;
  }

  /**
   * Filters out the children of a render array, optionally sorted by weight.
   *
   * @param array $build
   *   The render array whose children are to be filtered.
   * @param bool $sort
   *   Boolean to indicate whether the children should be sorted by weight.
   *
   * @return array
   *   The element's children.
   */
  public static function childrenFilter(array $build, bool $sort = FALSE) : array {
    $keys = Element::children($build, $sort);
    return array_intersect_key($build, array_flip($keys));
  }

  /**
   * Returns a URI to the file.
   *
   * @param object $input
   *   An object that contains the URI.
   *
   * @return string|null
   *   A URI that may be used to access the file.
   */
  public static function fileUriFilter($input) : ?string {
    return \Drupal::service('twig_tweak.uri_extractor')
      ->extractUri($input);
  }

  /**
   * Returns a URL path to the file.
   *
   * @param string|object $input
   *   Can be either file URI or an object that contains the URI.
   * @param bool $relative
   *   (optional) Whether the URL should be root-relative, defaults to true.
   *
   * @return string|null
   *   A URL that may be used to access the file.
   */
  public static function fileUrlFilter($input, bool $relative = TRUE) : ?string {
    return \Drupal::service('twig_tweak.url_extractor')
      ->extractUrl($input, $relative);
  }

  /**
   * Returns the translation for the given entity.
   *
   * @param \Drupal\Core\Entity\EntityInterface $entity
   *   The entity to get the translation from.
   * @param string $langcode
   *   (optional) For which language the translation should be looked for,
   *   defaults to the current language context.
   *
   * @return \Drupal\Core\Entity\EntityInterface
   *   The appropriate translation for the given language context.
   */
  public static function entityTranslation(EntityInterface $entity, string $langcode = NULL) : EntityInterface {
    return \Drupal::service('entity.repository')
      ->getTranslationFromContext($entity, $langcode);
  }

  /**
   * Extracts cache metadata from object or render array.
   *
   * @param \Drupal\Core\Cache\CacheableDependencyInterface|array $input
   *   The cacheable object or render array.
   *
   * @return array
   *   A render array with extracted cache metadata.
   */
  public static function cacheMetadata($input) : array {
    return \Drupal::service('twig_tweak.cache_metadata_extractor')
      ->extractCacheMetadata($input);
  }

  /**
   * Evaluates a string of PHP code.
   *
   * @param array $context
   *   Twig context.
   * @param string $code
   *   Valid PHP code to be evaluated.
   *
   * @return mixed
   *   The eval() result.
   */
  public static function phpFilter(array $context, string $code) {

    // Make Twig variables available in PHP code.
    extract($context);
    ob_start();

    // phpcs:ignore Drupal.Functions.DiscouragedFunctions.Discouraged
    print eval($code);
    $output = ob_get_contents();
    ob_end_clean();
    return $output;
  }

}

Classes

Name	Description
TwigTweakExtension	Twig extension with some useful functions and filters.