[FEATURE] Make code extension work out-of-the box

* Add default templates
* Use it for our own documentation
* Treat rest and unknown language as "text"
* Use warnings for unknown languages and supply debugging information
* As i also want to use the debugInformation for our third-party highlighter, I introduced a new global into twig which only
  contains the array. This way third party packages do not have to know about the RenderContext.

Author: linawolf

packages/guides-code/resources/template/html/body/code/highlighted-code.html.twig

@@ -0,0 +1 @@
+{{ node.value|highlight(node.language) }}

packages/guides-code/src/Code/DependencyInjection/CodeExtension.php

@@ -12,12 +12,13 @@
 use Symfony\Component\Config\FileLocator;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Extension\Extension;
+use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
 use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
 
 use function assert;
 use function dirname;
 
-class CodeExtension extends Extension implements ConfigurationInterface
+class CodeExtension extends Extension implements ConfigurationInterface, PrependExtensionInterface
 {
     public function getConfigTreeBuilder(): TreeBuilder
     {
@@ -70,4 +71,11 @@ public function getConfiguration(array $config, ContainerBuilder $container): Co
     {
         return $this;
     }
+
+    public function prepend(ContainerBuilder $container): void
+    {
+        $container->prependExtensionConfig('guides', [
+            'base_template_paths' => [dirname(__DIR__, 3) . '/resources/template/html'],
+        ]);
+    }
 }

packages/guides-code/src/Code/Highlighter/HighlightPhpHighlighter.php

@@ -8,6 +8,7 @@
 use Psr\Log\LoggerInterface;
 use Throwable;
 
+use function array_merge;
 use function assert;
 use function is_string;
 use function preg_replace;
@@ -32,9 +33,10 @@ public function __construct(
     ) {
     }
 
-    public function __invoke(string $language, string $code): HighlightResult
+    /** @param $debugInformation array<string, string|null> */
+    public function __invoke(string $language, string $code, array $debugInformation): HighlightResult
     {
-        if ($language === 'text') {
+        if ($language === 'text' || $language === '' || $language === 'rest') {
             // Highlighter escapes correctly the code, we need to manually escape only for "text" code
             $code = $this->escapeForbiddenCharactersInsideCodeBlock($code);
 
@@ -49,9 +51,9 @@ public function __invoke(string $language, string $code): HighlightResult
 
             return new HighlightResult($highlightLanguage, $highlightValue);
         } catch (Throwable $e) {
-            $this->logger->error(
+            $this->logger->warning(
                 <<<'MESSAGE'
-                Error highlighting {language} code block!
+                Highlighting {language} code-block failed
 
                 Code:
 
@@ -61,11 +63,11 @@ public function __invoke(string $language, string $code): HighlightResult
 
                 {exception}
                 MESSAGE,
-                [
+                array_merge($debugInformation, [
                     'language' => $language,
                     'code' => $code,
                     'exception' => $e,
-                ],
+                ]),
             );
 
             return new HighlightResult($language, $code);

packages/guides-code/src/Code/Highlighter/Highlighter.php

@@ -6,5 +6,6 @@
 
 interface Highlighter
 {
-    public function __invoke(string $language, string $code): HighlightResult;
+    /** @param array<string, string|null> $debugInformation */
+    public function __invoke(string $language, string $code, array $debugInformation): HighlightResult;
 }

packages/guides-code/src/Code/Twig/CodeExtension.php

@@ -8,6 +8,8 @@
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFilter;
 
+use function is_array;
+
 class CodeExtension extends AbstractExtension
 {
     public function __construct(
@@ -21,12 +23,18 @@ public function __construct(
     public function getFilters(): array
     {
         return [
-            new TwigFilter('highlight', $this->highlight(...), ['is_safe' => ['html']]),
+            new TwigFilter('highlight', $this->highlight(...), ['is_safe' => ['html'], 'needs_context' => true]),
         ];
     }
 
-    public function highlight(string $code, string $language = 'text'): string
+    /** @param array<string, mixed> $context */
+    public function highlight(array $context, string $code, string $language = 'text'): string
     {
-        return ($this->highlighter)($language, $code)->code;
+        $debugInformation = $context['debugInformation'] ?? [];
+        if (!is_array($debugInformation)) {
+            $debugInformation = [];
+        }
+
+        return ($this->highlighter)($language, $code, $debugInformation)->code;
     }
 }

packages/guides-code/tests/unit/Highlighter/HighlightPhpHighlighterTest.php

@@ -23,7 +23,7 @@ public function testItEscapesCharactersForbiddenInPreTags(): void
                   (__)\       )\/\
                       ||----w |
                       ||     ||
-        TXT);
+        TXT, []);
         self::assertSame(<<<'TXT'
         &lt; I'm an expert in my field. &gt;
           ---------------------------
@@ -46,7 +46,7 @@ public function testItIsIdempotent(): void
                   (__)\       )\/\
                       ||----w |
                       ||     ||
-        TXT);
+        TXT, []);
         self::assertSame(<<<'TXT'
         &lt; I'm an expert in my field. &gt;
           ---------------------------
@@ -65,10 +65,10 @@ public function testItCatchesAndLogsExceptions(): void
         $highlight = new HighlightPhpHighlighter($highlighter, $logger);
 
         $highlighter->method('highlight')->willThrowException(new Exception('test'));
-        $highlight('php', 'echo "Hello world";');
+        $highlight('php', 'echo "Hello world";', []);
 
-        self::assertTrue($logger->hasErrorRecords(), 'An error should be logged');
-        self::assertTrue($logger->hasErrorThatPasses(static function (array $record): bool {
+        self::assertTrue($logger->hasWarningRecords(), 'An error should be logged');
+        self::assertTrue($logger->hasWarningThatPasses(static function (array $record): bool {
             return isset($record['context']['exception'], $record['context']['code'])
                 && $record['context']['code'] === 'echo "Hello world";';
         }));
@@ -88,6 +88,6 @@ public function testItUnderstandsAliases(): void
             ->with('php', '#[Attribute]')
             ->willReturn((object) ['language' => 'php', 'value' => '<span class="hljs-attribute">#[Attribute]</span>']);
 
-        $highlight('attribute', '#[Attribute]');
+        $highlight('attribute', '#[Attribute]', []);
     }
 }

packages/guides/resources/template/html/body/code.html.twig

@@ -9,5 +9,7 @@
     {%- endif -%}
     <pre{% if node.classes %} class="{{ node.classesString }}"{% endif %}><code class="language-{{ node.language }}{{ node.startingLineNumber ? ' line-numbers' }}"
                 {%- if node.startingLineNumber %} data-start="{{ node.startingLineNumber }}"{% endif -%}
-                {%- if node.emphasizeLines %} data-emphasize-lines="{{ node.emphasizeLines }}"{% endif -%}>{{ node.value }}</code></pre>
+                {%- if node.emphasizeLines %} data-emphasize-lines="{{ node.emphasizeLines }}"{% endif -%}>
+    {%- include "body/code/highlighted-code.html.twig" -%}
+        </code></pre>
 {%- endif -%}

packages/guides/resources/template/html/body/code/highlighted-code.html.twig

@@ -0,0 +1 @@
+{{ node.value }}

packages/guides/src/Twig/TwigTemplateRenderer.php

@@ -28,6 +28,7 @@ public function renderTemplate(RenderContext $context, string $template, array $
     {
         $twig = $this->environmentBuilder->getTwigEnvironment();
         $twig->addGlobal('env', $context);
+        $twig->addGlobal('debugInformation', $context->getLoggerInformation());
 
         return $twig->render($template, $params);
     }