Expose the escaping strategy a template was compiled with

CHANGELOG

@@ -3,6 +3,7 @@
  * Fix `IntlExtension` letting the pattern derived from a date formatter prototype override an explicit locale
  * Fix `IntlExtension` not honoring the locale of a date formatter prototype configured with no date and time styles
  * Speed up macro calls
+ * Add `TemplateWrapper::getDefaultEscapeStrategy()` to know the escaping strategy a template was compiled with
  * Report a clear error when `random`, `reverse`, `shuffle`, and `split` receive a string that is not valid UTF-8
  * Fix the deprecation about omitting parentheses when calling a macro being reported twice for the same call
  * Add the macro name to the deprecation about omitting parentheses when calling a macro

doc/api.rst

@@ -48,6 +48,22 @@ returns a ``\Twig\TemplateWrapper`` instance::
 
     $template = $twig->load('index.html.twig');
 
+.. versionadded:: 3.30
+
+    The ``TemplateWrapper::getDefaultEscapeStrategy()`` method was introduced in
+    Twig 3.30.
+
+The wrapper tells which escaping strategy the body of the template was compiled
+with (``false`` when the template is not autoescaped)::
+
+    $strategy = $template->getDefaultEscapeStrategy();
+
+.. caution::
+
+    This describes the template's own source, not its output: ``autoescape``,
+    ``escape``, and anything rendered by a parent, embedded, or included
+    template can use another strategy.
+
 Rendering Templates
 -------------------
 

src/Node/ModuleNode.php

@@ -73,6 +73,7 @@ final class ModuleNode extends Node implements CoercesChildrenToStringInterface
         parent::__construct($nodes, [
             'index' => null,
             'embedded_templates' => $embeddedTemplates,
+            'strategy' => false,
         ], 1);
 
         // populate the template name of all node children
@@ -121,6 +122,8 @@ final class ModuleNode extends Node implements CoercesChildrenToStringInterface
 
         $this->compileIsTraitable($compiler);
 
+        $this->compileGetDefaultEscapeStrategy($compiler);
+
         $this->compileDebugInfo($compiler);
 
         $this->compileGetSourceContext($compiler);
@@ -462,6 +465,26 @@ final class ModuleNode extends Node implements CoercesChildrenToStringInterface
         ;
     }
 
+    protected function compileGetDefaultEscapeStrategy(Compiler $compiler): void
+    {
+        if (false === $strategy = $this->getAttribute('strategy')) {
+            return;
+        }
+
+        $compiler
+            ->write("/**\n")
+            ->write(" * @codeCoverageIgnore\n")
+            ->write(" */\n")
+            ->write("public function getDefaultEscapeStrategy(): string|false\n", "{\n")
+            ->indent()
+            ->write('return ')
+            ->repr($strategy)
+            ->raw(";\n")
+            ->outdent()
+            ->write("}\n\n")
+        ;
+    }
+
     protected function compileDebugInfo(Compiler $compiler): void
     {
         $compiler

src/NodeVisitor/EscaperNodeVisitor.php

@@ -52,6 +52,8 @@ final class EscaperNodeVisitor implements NodeVisitorInterface
             if ($env->hasExtension(EscaperExtension::class) && $defaultStrategy = $env->getExtension(EscaperExtension::class)->getDefaultStrategy($node->getTemplateName())) {
                 $this->defaultStrategy = $defaultStrategy;
             }
+            // the compiled template exposes the strategy it was compiled with
+            $node->setAttribute('strategy', \is_string($this->defaultStrategy) ? $this->defaultStrategy : false);
             $this->safeVars = [];
             $this->blocks = [];
         } elseif ($node instanceof AutoEscapeNode) {

src/Template.php

@@ -67,6 +67,20 @@ abstract class Template
      */
     abstract public function getSourceContext(): Source;
 
+    /**
+     * Returns the escaping strategy the template body was compiled with.
+     *
+     * This describes the template's own source, not its output: `autoescape`,
+     * `escape`, and anything rendered by a parent, embedded, or included
+     * template can use another strategy.
+     *
+     * @return string|false The strategy name or false when the template is not autoescaped
+     */
+    public function getDefaultEscapeStrategy(): string|false
+    {
+        return false;
+    }
+
     /**
      * Returns the parent template.
      *

src/TemplateWrapper.php

@@ -96,6 +96,20 @@ final class TemplateWrapper
         return $this->template->getTemplateName();
     }
 
+    /**
+     * Returns the escaping strategy the template body was compiled with.
+     *
+     * This describes the template's own source, not its output: `autoescape`,
+     * `escape`, and anything rendered by a parent, embedded, or included
+     * template can use another strategy.
+     *
+     * @return string|false The strategy name or false when the template is not autoescaped
+     */
+    public function getDefaultEscapeStrategy(): string|false
+    {
+        return $this->template->getDefaultEscapeStrategy();
+    }
+
     /**
      * @internal
      */

tests/TemplateEscapeStrategyTest.php

@@ -0,0 +1,124 @@
+<?php
+
+/*
+ * This file is part of Twig.
+ *
+ * (c) Fabien Potencier
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Twig\Tests;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+use Twig\Environment;
+use Twig\Loader\ArrayLoader;
+use Twig\Source;
+use Twig\Template;
+
+class TemplateEscapeStrategyTest extends TestCase
+{
+    /**
+     * @dataProvider provideTemplates
+     */
+    #[DataProvider('provideTemplates')]
+    public function testCompiledTemplatesExposeTheirStrategy(string|false $expected, string $name, string|false $autoescape): void
+    {
+        $twig = new Environment(new ArrayLoader([
+            $name => '{{ value }}',
+        ]), ['autoescape' => $autoescape, 'cache' => false]);
+
+        $this->assertSame($expected, $twig->load($name)->getDefaultEscapeStrategy());
+    }
+
+    public static function provideTemplates()
+    {
+        // compiled class names derive from the template name alone, so reusing a name across cases would silently reuse the first compiled class
+        return [
+            ['html', 'guessed_html.html.twig', 'name'],
+            ['js', 'guessed_js.js.twig', 'name'],
+            [false, 'guessed_none.txt.twig', 'name'],
+            ['html', 'forced_html.js.twig', 'html'],
+            [false, 'disabled.html.twig', false],
+        ];
+    }
+
+    /**
+     * @dataProvider provideAutoescapeTags
+     */
+    #[DataProvider('provideAutoescapeTags')]
+    public function testAnAutoescapeTagDoesNotChangeTheStrategyOfTheTemplate(string $name, string $tag): void
+    {
+        $twig = new Environment(new ArrayLoader([
+            $name => "{% autoescape $tag %}{{ value }}{% endautoescape %}",
+        ]), ['autoescape' => 'name', 'cache' => false]);
+
+        $this->assertSame('html', $twig->load($name)->getDefaultEscapeStrategy());
+    }
+
+    public static function provideAutoescapeTags()
+    {
+        return [
+            ['another_strategy.html.twig', "'js'"],
+            ['no_escaping.html.twig', 'false'],
+        ];
+    }
+
+    public function testTheStrategyDescribesTheBodyAndNotWhatTheTemplateRenders(): void
+    {
+        $twig = new Environment(new ArrayLoader([
+            'inherits.html.twig' => "{% extends 'inherited.txt.twig' %}",
+            'inherited.txt.twig' => '{{ value }}',
+        ]), ['autoescape' => 'name', 'cache' => false]);
+
+        $template = $twig->load('inherits.html.twig');
+
+        $this->assertSame('html', $template->getDefaultEscapeStrategy());
+        $this->assertSame('<b>', $template->render(['value' => '<b>']));
+    }
+
+    public function testEmbeddedTemplatesExposeTheStrategyOfTheirTemplate(): void
+    {
+        $twig = new Environment(new ArrayLoader([
+            'index.js.twig' => "{% embed 'layout.html.twig' %}{% block content %}{{ value }}{% endblock %}{% endembed %}",
+            'layout.html.twig' => '{% block content %}{% endblock %}',
+        ]), ['autoescape' => 'name', 'cache' => false]);
+
+        $compiled = $twig->compileSource(new Source($twig->getLoader()->getSourceContext('index.js.twig')->getCode(), 'index.js.twig'));
+
+        $this->assertSame(2, substr_count($compiled, 'public function getDefaultEscapeStrategy(): string|false'));
+        $this->assertSame(2, substr_count($compiled, 'return "js";'));
+    }
+
+    public function testTemplatesCompiledBeforeTheStrategyWasExposedReportNoStrategy(): void
+    {
+        $twig = new Environment(new ArrayLoader(['index.html.twig' => '{{ value }}']), ['autoescape' => 'name', 'cache' => false]);
+
+        $this->assertFalse((new TemplateWithoutStrategy($twig))->getDefaultEscapeStrategy());
+    }
+}
+
+class TemplateWithoutStrategy extends Template
+{
+    public function getTemplateName(): string
+    {
+        return 'index.html.twig';
+    }
+
+    public function getDebugInfo(): array
+    {
+        return [];
+    }
+
+    public function getSourceContext(): Source
+    {
+        return new Source('', $this->getTemplateName());
+    }
+
+    protected function doDisplay(array $context, array $blocks = []): iterable
+    {
+        yield '';
+    }
+}

tests/TemplateWrapperTest.php

@@ -43,6 +43,13 @@ class TemplateWrapperTest extends TestCase
         $wrapper->unwrap(new Environment(new ArrayLoader()));
     }
 
+    public function testGetDefaultEscapeStrategy(): void
+    {
+        $twig = new Environment(new ArrayLoader(['index.js.twig' => 'content']), ['autoescape' => 'name']);
+
+        $this->assertSame('js', $twig->load('index.js.twig')->getDefaultEscapeStrategy());
+    }
+
     public function testHasGetBlocks(): void
     {
         $twig = new Environment(new ArrayLoader([