HelpTwigExtension.php

<?php

namespace Drupal\help;

use Drupal\Component\Plugin\Exception\PluginNotFoundException;
use Drupal\Core\Access\AccessManagerInterface;
use Drupal\Core\Render\BubbleableMetadata;
use Drupal\Core\StringTranslation\StringTranslationTrait;
use Drupal\Core\StringTranslation\TranslationInterface;
use Drupal\Core\Url;
use Symfony\Component\Routing\Exception\InvalidParameterException;
use Symfony\Component\Routing\Exception\MissingMandatoryParametersException;
use Symfony\Component\Routing\Exception\RouteNotFoundException;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

/**
 * Defines and registers Drupal Twig extensions for rendering help topics.
 *
 * @internal
 *   Tagged services are internal.
 */
class HelpTwigExtension extends AbstractExtension {
    use StringTranslationTrait;
    
    /**
     * Constructs a \Drupal\help\HelpTwigExtension.
     *
     * @param \Drupal\Core\Access\AccessManagerInterface $accessManager
     *   The access manager.
     * @param \Drupal\help\HelpTopicPluginManagerInterface $pluginManager
     *   The help topic plugin manager service.
     * @param \Drupal\Core\StringTranslation\TranslationInterface $string_translation
     *   The string translation service.
     */
    public function __construct(AccessManagerInterface $accessManager, HelpTopicPluginManagerInterface $pluginManager, TranslationInterface $string_translation) {
        $this->stringTranslation = $string_translation;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getFunctions() {
        return [
            new TwigFunction('help_route_link', [
                $this,
                'getRouteLink',
            ]),
            new TwigFunction('help_topic_link', [
                $this,
                'getTopicLink',
            ]),
        ];
    }
    
    /**
     * Returns a link or plain text, given text, route name, and parameters.
     *
     * @param string $text
     *   The link text.
     * @param string $route
     *   The name of the route.
     * @param array $parameters
     *   (optional) An associative array of route parameter names and values.
     * @param array $options
     *   (optional) An associative array of additional options. The 'absolute'
     *   option is forced to be TRUE.
     *
     * @return array
     *   A render array with a generated absolute link to the given route. If
     *   the user does not have permission for the route, or an exception occurs,
     *   such as a missing route or missing parameters, the render array is for
     *   the link text as a plain string instead.
     *
     * @see \Drupal\Core\Template\TwigExtension::getUrl()
     */
    public function getRouteLink(string $text, string $route, array $parameters = [], array $options = []) : array {
        assert($this->accessManager instanceof AccessManagerInterface, "The access manager hasn't been set up. Any configuration YAML file with a service directive dealing with the Twig configuration can cause this, most likely found in a recently installed or changed module.");
        $bubbles = new BubbleableMetadata();
        $bubbles->addCacheTags([
            'route_match',
        ]);
        try {
            $access_object = $this->accessManager
                ->checkNamedRoute($route, $parameters, NULL, TRUE);
            $bubbles->addCacheableDependency($access_object);
            if ($access_object->isAllowed()) {
                $options['absolute'] = TRUE;
                $url = Url::fromRoute($route, $parameters, $options);
                // Generate the URL to check for parameter problems and collect
                // cache metadata.
                $generated = $url->toString(TRUE);
                $bubbles->addCacheableDependency($generated);
                $build = [
                    '#title' => $text,
                    '#type' => 'link',
                    '#url' => $url,
                ];
            }
            else {
                // If the user doesn't have access, return the link text.
                $build = [
                    '#markup' => $text,
                ];
            }
        } catch (RouteNotFoundException|MissingMandatoryParametersException|InvalidParameterException $e) {
            // If the route had one of these exceptions, return the link text.
            $build = [
                '#markup' => $text,
            ];
        }
        $bubbles->applyTo($build);
        return $build;
    }
    
    /**
     * Returns a link to a help topic, or the title of the topic.
     *
     * @param string $topic_id
     *   The help topic ID.
     *
     * @return array
     *   A render array with a generated absolute link to the given topic. If
     *   the user does not have permission to view the topic, or an exception
     *   occurs, such as the topic not being defined due to a module not being
     *   installed, a default string is returned.
     *
     * @see \Drupal\Core\Template\TwigExtension::getUrl()
     */
    public function getTopicLink(string $topic_id) : array {
        assert($this->pluginManager instanceof HelpTopicPluginManagerInterface, "The plugin manager hasn't been set up. Any configuration YAML file with a service directive dealing with the Twig configuration can cause this, most likely found in a recently installed or changed module.");
        $bubbles = new BubbleableMetadata();
        $bubbles->addCacheableDependency($this->pluginManager);
        try {
            $plugin = $this->pluginManager
                ->createInstance($topic_id);
        } catch (PluginNotFoundException $e) {
            // Not a topic.
            $plugin = FALSE;
        }
        if ($plugin) {
            $parameters = [
                'id' => $topic_id,
            ];
            $route = 'help.help_topic';
            $build = $this->getRouteLink($plugin->getLabel(), $route, $parameters);
            $bubbles->addCacheableDependency($plugin);
        }
        else {
            $build = [
                '#markup' => $this->t('Missing help topic %topic', [
                    '%topic' => $topic_id,
                ]),
            ];
        }
        $bubbles->applyTo($build);
        return $build;
    }

}