Merge branch 'release/2.0.21'

Author: rhukster

CHANGELOG.md

@@ -1,3 +1,10 @@
+# v2.0.21
+## 08/22/2026
+
+1. [](#bugfix)
+    * Form fields no longer print their HTML attributes as text above the field, a problem the Twig update in 2.0.20 introduced on every form [#4256](https://github.com/getgrav/grav/issues/4256)
+    * A custom text escaper registered by a plugin now works again, instead of stopping the page with an error the first time a template used it
+
 # v2.0.20
 ## 08/21/2026
 

composer.lock

@@ -9,7 +9,7 @@
 
 // Some standard defines
 define("GRAV", true);
-define("GRAV_VERSION", "2.0.20");
+define("GRAV_VERSION", "2.0.21");
 define("GRAV_SCHEMA", "1.8.0_2026-06-09_0");
 define("GRAV_TESTING", false);
 

system/defines.php

@@ -9,6 +9,7 @@
 
 namespace Grav\Common\Twig;
 
+use Closure;
 use Grav\Common\Debugger;
 use Grav\Common\Grav;
 use Grav\Common\Config\Config;
@@ -28,6 +29,8 @@
 use Grav\Common\Utils;
 use RocketTheme\Toolbox\ResourceLocator\UniformResourceLocator;
 use RocketTheme\Toolbox\Event\Event;
+use ReflectionException;
+use ReflectionFunction;
 use RuntimeException;
 use Twig\Cache\FilesystemCache;
 use Twig\DeferredExtension\DeferredExtension;
@@ -891,14 +894,26 @@ public function setAutoescape($state)
      * - Twig 2.x/3.x (< 3.9): Uses EscaperExtension::setEscaper()
      * - Twig 3.9+: Uses EscaperRuntime::setEscaper()
      *
+     * The callable may take either the historic Grav signature,
+     * function($twig, $string, $charset), or the Twig 3.9+ runtime signature,
+     * function($string, $charset). Both keep working wherever this runs.
+     *
      * @param string $strategy The escaper strategy name (e.g., 'yaml', 'json')
-     * @param callable $callable The escaper callable: function($twig, $string, $charset)
+     * @param callable $callable The escaper callable
      * @return void
      */
     public function setEscaper(string $strategy, callable $callable): void
     {
-        // Twig 3.9+ moved setEscaper to EscaperRuntime
+        // Twig 3.9+ moved setEscaper to EscaperRuntime, which calls the escaper
+        // with ($string, $charset) and not the ($twig, $string, $charset) this
+        // method has always documented. Adapt rather than break the callers.
         if (class_exists(EscaperRuntime::class)) {
+            $twig = $this->twig;
+            if ($this->escaperExpectsEnvironment($callable)) {
+                $original = $callable;
+                $callable = static fn ($string, $charset) => $original($twig, $string, $charset);
+            }
+
             $this->twig->getRuntime(EscaperRuntime::class)->setEscaper($strategy, $callable);
             return;
         }
@@ -913,4 +928,23 @@ public function setEscaper(string $strategy, callable $callable): void
         $this->twig->getExtension(CoreExtension::class)->setEscaper($strategy, $callable);
     }
 
+    /**
+     * Whether an escaper callable takes the Twig environment as its first
+     * argument. Anything declaring three or more parameters does; two-parameter
+     * and variadic callables are passed straight through.
+     *
+     * @param callable $callable
+     * @return bool
+     */
+    protected function escaperExpectsEnvironment(callable $callable): bool
+    {
+        try {
+            $reflection = new ReflectionFunction(Closure::fromCallable($callable));
+        } catch (ReflectionException $e) {
+            return false;
+        }
+
+        return $reflection->getNumberOfParameters() >= 3;
+    }
+
 }

system/src/Grav/Common/Twig/Twig.php

@@ -125,9 +125,11 @@ public function set(string $t): string { $this->title = $t; return ''; }
 
     public function testDeferredBlockInsideConditionalChildOverrideRenders(): void
     {
-        // Exercises the Grav-specific Parser::filterBodyNodes() patch that
-        // treats IfNode as "transparent" for block-definition nesting,
-        // so that a child can re-declare a parent's block from inside {% if %}.
+        // Exercises the Grav-specific Parser::cleanupTransparentBodyNodes()
+        // patch that treats IfNode as "transparent" for block-definition
+        // nesting, so that a child can re-declare a parent's block from
+        // inside {% if %}. Here the `if` is one node among others at the root
+        // of the child; see the sibling test for the whole-body shape.
         $parent = <<<'TWIG'
         <head>{% block head deferred %}default{% endblock %}</head>
         <body>{{ assets.add('/x.css') }}{% block body %}b{% endblock %}</body>
@@ -147,6 +149,43 @@ public function testDeferredBlockInsideConditionalChildOverrideRenders(): void
         $out = $env->render('child.twig');
 
         self::assertStringContainsString('<links><link rel="stylesheet" href="/x.css"></links>', $out);
+        // The definition must not ALSO render where it was declared.
+        self::assertSame(1, substr_count($out, '<links>'));
+    }
+
+    /**
+     * Regression coverage for getgrav/grav#4256.
+     *
+     * The child wraps its whole body — the `extends` tag included — in a
+     * single `{% if %}`, the shape the form plugin's field template uses. The
+     * body cleanup used to miss that case, so the deferred definition was
+     * rendered where it was declared as well as in the parent's slot, ahead of
+     * even the `<head>` the parent opens with.
+     */
+    public function testDeferredBlockUnderAnIfWrappingTheWholeChildBody(): void
+    {
+        $parent = <<<'TWIG'
+        <head>{% block head deferred %}DEFAULT{% endblock %}</head><body>{{ assets.add('/x.css') }}{% block body %}b{% endblock %}</body>
+        TWIG;
+
+        $child = <<<'TWIG'
+        {% if true %}
+        {% extends 'parent.twig' %}
+        {% block head deferred %}<links>{{ assets.render() }}</links>{% endblock %}
+        {% endif %}
+        TWIG;
+
+        $env = $this->env(
+            ['parent.twig' => $parent, 'child.twig' => $child],
+            ['assets' => $this->assets()]
+        );
+        $out = $env->render('child.twig');
+
+        self::assertSame(
+            '<head><links><link rel="stylesheet" href="/x.css"></links></head><body>b</body>',
+            trim($out)
+        );
+        self::assertStringNotContainsString('DEFAULT', $out);
     }
 
     public function testChildOverridesDeferredParentBlock(): void

tests/unit/Grav/Common/Twig/DeferredExtensionTest.php

@@ -0,0 +1,124 @@
+<?php
+
+use Twig\Environment;
+use Twig\Loader\ArrayLoader;
+
+/**
+ * Regression coverage for getgrav/grav#4256.
+ *
+ * Twig's own parser refuses a `block` definition nested under an `if`, so the
+ * getgrav/Twig fork carries a patch that makes `if` transparent when a child
+ * template's body is cleaned up. Grav themes and plugins rely on it: the form
+ * plugin's forms/default/field.html.twig wraps its whole body — the `extends`
+ * tag included — in a single `{% if not field.validate.ignore %}`.
+ *
+ * Upstream 3.27 replaced the recursive Parser::filterBodyNodes() with the flat
+ * Parser::cleanupBodyForChildTemplates(), and re-homing the fork patch onto it
+ * lost the case where that `if` IS the body rather than one node inside it. The
+ * block definitions were then rendered in place as well as through the parent,
+ * so every form field printed its attributes as text above the field.
+ *
+ * These tests pin the parser behaviour the fork has to keep providing. They are
+ * deliberately free of Grav bootstrapping so they stay a reliable canary for the
+ * vendored Twig itself.
+ */
+class TwigConditionalBlockTest extends \PHPUnit\Framework\TestCase
+{
+    /**
+     * @param array<string, string> $templates
+     * @return string
+     */
+    protected function render(array $templates, string $name = 'child.twig'): string
+    {
+        $twig = new Environment(new ArrayLoader($templates), [
+            'autoescape' => 'html',
+            'cache' => false,
+            'debug' => true,
+        ]);
+
+        return $twig->render($name);
+    }
+
+    /**
+     * The whole child body is one `if`, with `extends` inside it. This is the
+     * shape the form plugin uses, and the one #4256 broke.
+     */
+    public function testBlocksUnderAnIfWrappingTheWholeBodyAreNotRenderedInPlace()
+    {
+        $output = $this->render([
+            'layout.twig' => '<div {% block outer %}{% endblock %}><input {% block inner %}{% endblock %} /></div>',
+            'child.twig' => <<<TWIG
+{% if true %}
+{% extends "layout.twig" %}
+{% block outer %}data-a="1"{% endblock %}
+{% block inner %}class="c"{% endblock %}
+{% endif %}
+TWIG,
+        ]);
+
+        $this->assertSame('<div data-a="1"><input class="c" /></div>', trim($output));
+    }
+
+    /**
+     * The same shape one level deeper: a grandchild overriding a block and
+     * calling parent(), as forms/fields/text/text.html.twig does.
+     */
+    public function testParentResolvesThroughAConditionalChildTemplate()
+    {
+        $output = $this->render([
+            'layout.twig' => '<input {% block attrs %}{% endblock %} />',
+            'middle.twig' => <<<TWIG
+{% if true %}
+{% extends "layout.twig" %}
+{% block attrs %}class="c"{% endblock %}
+{% endif %}
+TWIG,
+            'child.twig' => <<<TWIG
+{% extends "middle.twig" %}
+{% block attrs %}type="text" {{ parent() }}{% endblock %}
+TWIG,
+        ]);
+
+        $this->assertSame('<input type="text" class="c" />', trim($output));
+    }
+
+    /**
+     * The condition only decides whether the definition also renders in place;
+     * the override itself is registered at compile time either way. A false
+     * condition must therefore still override the parent, and still not leak.
+     */
+    public function testAFalseConditionStillRegistersTheOverrideWithoutRenderingInPlace()
+    {
+        $output = $this->render([
+            'layout.twig' => '[{% block content %}DEFAULT{% endblock %}]',
+            'child.twig' => <<<TWIG
+{% extends "layout.twig" %}
+{% if false %}
+{% block content %}OVERRIDE{% endblock %}
+{% endif %}
+TWIG,
+        ]);
+
+        $this->assertSame('[OVERRIDE]', trim($output));
+    }
+
+    /**
+     * The pre-existing case: the `if` is one node among others at the root of
+     * the child. Guards against a fix for the above regressing this direction.
+     */
+    public function testBlocksUnderAnIfAlongsideOtherRootNodesAreNotRenderedInPlace()
+    {
+        $output = $this->render([
+            'layout.twig' => '[{% block first %}{% endblock %}][{% block second %}{% endblock %}]',
+            'child.twig' => <<<TWIG
+{% extends "layout.twig" %}
+{% block first %}FOO{% endblock %}
+{% if true %}
+{% block second %}BAR{% endblock %}
+{% endif %}
+TWIG,
+        ]);
+
+        $this->assertSame('[FOO][BAR]', trim($output));
+    }
+}