Rename macro variable AST nodes

CHANGELOG

@@ -6,6 +6,7 @@
  * Fix array access with a `Stringable` key coercing the key to string for `ArrayAccess` objects that use object keys (such as `SplObjectStorage`)
  * Fix duplicated macro argument names triggering a PHP fatal error instead of a `SyntaxError`
  * Deprecate defining a macro more than once in the same template
+ * Deprecate `TemplateVariable` and `AssignTemplateVariable`; use `MacroVariable` and `AssignMacroVariable` instead
 
 # 3.28.0 (2026-07-03)
 

doc/deprecated.rst

@@ -180,6 +180,11 @@ Nodes
 * The ``MethodCallExpression`` class is deprecated as of Twig 3.15, use
   ``MacroReferenceExpression`` instead.
 
+* The ``Twig\Node\Expression\Variable\TemplateVariable`` and
+  ``Twig\Node\Expression\Variable\AssignTemplateVariable`` classes are
+  deprecated as of Twig 3.29; use ``MacroVariable`` and
+  ``AssignMacroVariable`` instead.
+
 * The ``Twig\Node\Expression\TempNameExpression`` class is deprecated as of
   Twig 3.15; use ``Twig\Node\Expression\Variable\LocalVariable`` instead.
 

src/ExpressionParser/Infix/DotExpressionParser.php

@@ -23,7 +23,7 @@ use Twig\Node\Expression\ConstantExpression;
 use Twig\Node\Expression\GetAttrExpression;
 use Twig\Node\Expression\MacroReferenceExpression;
 use Twig\Node\Expression\NameExpression;
-use Twig\Node\Expression\Variable\TemplateVariable;
+use Twig\Node\Expression\Variable\MacroVariable;
 use Twig\Parser;
 use Twig\Template;
 use Twig\Token;
@@ -77,11 +77,11 @@ final class DotExpressionParser extends AbstractExpressionParser implements Infi
             && \is_string($name = $attribute->getAttribute('value'))
             && preg_match('#^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$#D', $name)
         ) {
-            return new MacroReferenceExpression(new TemplateVariable($expr->getAttribute('name'), $expr->getTemplateLine()), 'macro_'.$name, $arguments, $expr->getTemplateLine());
+            return new MacroReferenceExpression(new MacroVariable($expr->getAttribute('name'), $expr->getTemplateLine()), 'macro_'.$name, $arguments, $expr->getTemplateLine());
         }
 
         if ($isMacroTarget && !$attribute instanceof ConstantExpression) {
-            return new MacroReferenceExpression(new TemplateVariable($expr->getAttribute('name'), $expr->getTemplateLine()), $attribute, $arguments, $expr->getTemplateLine());
+            return new MacroReferenceExpression(new MacroVariable($expr->getAttribute('name'), $expr->getTemplateLine()), $attribute, $arguments, $expr->getTemplateLine());
         }
 
         return new GetAttrExpression($expr, $attribute, $arguments, $type, $lineno, $nullSafe);

src/Node/Expression/MacroReferenceExpression.php

@@ -13,7 +13,7 @@ namespace Twig\Node\Expression;
 
 use Twig\Compiler;
 use Twig\Node\CoercesChildrenToStringInterface;
-use Twig\Node\Expression\Variable\TemplateVariable;
+use Twig\Node\Expression\Variable\MacroVariable;
 
 /**
  * Represents a macro call node.
@@ -30,7 +30,7 @@ class MacroReferenceExpression extends AbstractExpression implements SupportDefi
      *                                        call, an expression resolving to the macro name (without the
      *                                        "macro_" prefix, which is added at runtime)
      */
-    public function __construct(TemplateVariable $template, string|AbstractExpression $name, AbstractExpression $arguments, int $lineno)
+    public function __construct(MacroVariable $template, string|AbstractExpression $name, AbstractExpression $arguments, int $lineno)
     {
         $nodes = ['template' => $template, 'arguments' => $arguments];
         $attributes = ['name' => null];
@@ -55,7 +55,7 @@ class MacroReferenceExpression extends AbstractExpression implements SupportDefi
     {
         // The template node must not be deep-cloned because its name is
         // lazily generated during compilation and must stay in sync with
-        // the AssignTemplateVariable that populates the $macros array.
+        // the AssignMacroVariable that populates the $macros array.
         $template = $this->nodes['template'];
         parent::__clone();
         $this->nodes['template'] = $template;

src/Node/Expression/Variable/AssignMacroVariable.php

@@ -0,0 +1,44 @@
+<?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\Node\Expression\Variable;
+
+use Twig\Compiler;
+use Twig\Node\Expression\AbstractExpression;
+
+class AssignMacroVariable extends AbstractExpression
+{
+    public function __construct(MacroVariable $var, bool $global = true)
+    {
+        parent::__construct(['var' => $var], ['global' => $global], $var->getTemplateLine());
+    }
+
+    public function compile(Compiler $compiler): void
+    {
+        /** @var MacroVariable $var */
+        $var = $this->nodes['var'];
+
+        $compiler
+            ->addDebugInfo($this)
+            ->write('$macros[')
+            ->string($var->getName($compiler))
+            ->raw('] = ')
+        ;
+
+        if ($this->getAttribute('global')) {
+            $compiler
+                ->raw('$this->macros[')
+                ->string($var->getName($compiler))
+                ->raw('] = ')
+            ;
+        }
+    }
+}

src/Node/Expression/Variable/AssignTemplateVariable.php

@@ -11,34 +11,15 @@
 
 namespace Twig\Node\Expression\Variable;
 
-use Twig\Compiler;
-use Twig\Node\Expression\AbstractExpression;
-
-final class AssignTemplateVariable extends AbstractExpression
+/**
+ * @deprecated since Twig 3.29, use AssignMacroVariable instead
+ */
+final class AssignTemplateVariable extends AssignMacroVariable
 {
     public function __construct(TemplateVariable $var, bool $global = true)
     {
-        parent::__construct(['var' => $var], ['global' => $global], $var->getTemplateLine());
-    }
+        trigger_deprecation('twig/twig', '3.29', 'The "%s" class is deprecated, use "%s" instead.', self::class, AssignMacroVariable::class);
 
-    public function compile(Compiler $compiler): void
-    {
-        /** @var TemplateVariable $var */
-        $var = $this->nodes['var'];
-
-        $compiler
-            ->addDebugInfo($this)
-            ->write('$macros[')
-            ->string($var->getName($compiler))
-            ->raw('] = ')
-        ;
-
-        if ($this->getAttribute('global')) {
-            $compiler
-                ->raw('$this->macros[')
-                ->string($var->getName($compiler))
-                ->raw('] = ')
-            ;
-        }
+        parent::__construct($var, $global);
     }
 }

src/Node/Expression/Variable/MacroVariable.php

@@ -0,0 +1,42 @@
+<?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\Node\Expression\Variable;
+
+use Twig\Compiler;
+use Twig\Node\Expression\TempNameExpression;
+
+class MacroVariable extends TempNameExpression
+{
+    public function getName(Compiler $compiler): string
+    {
+        if (null === $this->getAttribute('name')) {
+            $this->setAttribute('name', $compiler->getVarName());
+        }
+
+        return $this->getAttribute('name');
+    }
+
+    public function compile(Compiler $compiler): void
+    {
+        $name = $this->getName($compiler);
+
+        if ('_self' === $name) {
+            $compiler->raw('$this');
+        } else {
+            $compiler
+                ->raw('$macros[')
+                ->string($name)
+                ->raw(']')
+            ;
+        }
+    }
+}

src/Node/Expression/Variable/TemplateVariable.php

@@ -11,32 +11,17 @@
 
 namespace Twig\Node\Expression\Variable;
 
-use Twig\Compiler;
-use Twig\Node\Expression\TempNameExpression;
-
-class TemplateVariable extends TempNameExpression
+/**
+ * @deprecated since Twig 3.29, use MacroVariable instead
+ */
+class TemplateVariable extends MacroVariable
 {
-    public function getName(Compiler $compiler): string
+    public function __construct(string|int|null $name, int $lineno)
     {
-        if (null === $this->getAttribute('name')) {
-            $this->setAttribute('name', $compiler->getVarName());
+        if (self::class === static::class) {
+            trigger_deprecation('twig/twig', '3.29', 'The "%s" class is deprecated, use "%s" instead.', self::class, MacroVariable::class);
         }
 
-        return $this->getAttribute('name');
-    }
-
-    public function compile(Compiler $compiler): void
-    {
-        $name = $this->getName($compiler);
-
-        if ('_self' === $name) {
-            $compiler->raw('$this');
-        } else {
-            $compiler
-                ->raw('$macros[')
-                ->string($name)
-                ->raw(']')
-            ;
-        }
+        parent::__construct($name, $lineno);
     }
 }

src/Node/ImportNode.php

@@ -14,8 +14,9 @@ namespace Twig\Node;
 use Twig\Attribute\YieldReady;
 use Twig\Compiler;
 use Twig\Node\Expression\AbstractExpression;
-use Twig\Node\Expression\Variable\AssignTemplateVariable;
+use Twig\Node\Expression\Variable\AssignMacroVariable;
 use Twig\Node\Expression\Variable\ContextVariable;
+use Twig\Node\Expression\Variable\MacroVariable;
 
 /**
  * Represents an import node.
@@ -25,16 +26,16 @@ use Twig\Node\Expression\Variable\ContextVariable;
 #[YieldReady]
 class ImportNode extends Node implements CoercesChildrenToStringInterface
 {
-    public function __construct(AbstractExpression $expr, AbstractExpression|AssignTemplateVariable $var, int $lineno)
+    public function __construct(AbstractExpression $expr, AbstractExpression|AssignMacroVariable $var, int $lineno)
     {
         if (\func_num_args() > 3) {
             trigger_deprecation('twig/twig', '3.15', \sprintf('Passing more than 3 arguments to "%s()" is deprecated.', __METHOD__));
         }
 
-        if (!$var instanceof AssignTemplateVariable) {
-            trigger_deprecation('twig/twig', '3.15', \sprintf('Passing a "%s" instance as the second argument of "%s" is deprecated, pass a "%s" instead.', $var::class, __CLASS__, AssignTemplateVariable::class));
+        if (!$var instanceof AssignMacroVariable) {
+            trigger_deprecation('twig/twig', '3.15', \sprintf('Passing a "%s" instance as the second argument of "%s" is deprecated, pass a "%s" instead.', $var::class, __CLASS__, AssignMacroVariable::class));
 
-            $var = new AssignTemplateVariable($var->getAttribute('name'), $lineno);
+            $var = new AssignMacroVariable(new MacroVariable($var->getAttribute('name'), $lineno));
         }
 
         parent::__construct(['expr' => $expr, 'var' => $var], [], $lineno);

src/Parser.php

@@ -24,8 +24,8 @@ use Twig\Node\BlockReferenceNode;
 use Twig\Node\BodyNode;
 use Twig\Node\EmptyNode;
 use Twig\Node\Expression\AbstractExpression;
-use Twig\Node\Expression\Variable\AssignTemplateVariable;
-use Twig\Node\Expression\Variable\TemplateVariable;
+use Twig\Node\Expression\Variable\AssignMacroVariable;
+use Twig\Node\Expression\Variable\MacroVariable;
 use Twig\Node\MacroNode;
 use Twig\Node\ModuleNode;
 use Twig\Node\Node;
@@ -329,19 +329,19 @@ class Parser
         $this->embeddedTemplates[] = $template;
     }
 
-    public function addImportedSymbol(string $type, string $alias, ?string $name = null, AbstractExpression|AssignTemplateVariable|null $internalRef = null): void
+    public function addImportedSymbol(string $type, string $alias, ?string $name = null, AbstractExpression|AssignMacroVariable|null $internalRef = null): void
     {
-        if ($internalRef && !$internalRef instanceof AssignTemplateVariable) {
-            trigger_deprecation('twig/twig', '3.15', 'Not passing a "%s" instance as an internal reference is deprecated ("%s" given).', __METHOD__, AssignTemplateVariable::class, $internalRef::class);
+        if ($internalRef && !$internalRef instanceof AssignMacroVariable) {
+            trigger_deprecation('twig/twig', '3.15', 'Not passing a "%s" instance as an internal reference is deprecated ("%s" given).', __METHOD__, AssignMacroVariable::class, $internalRef::class);
 
-            $internalRef = new AssignTemplateVariable(new TemplateVariable($internalRef->getAttribute('name'), $internalRef->getTemplateLine()), $internalRef->getAttribute('global'));
+            $internalRef = new AssignMacroVariable(new MacroVariable($internalRef->getAttribute('name'), $internalRef->getTemplateLine()), $internalRef->getAttribute('global'));
         }
 
         $this->importedSymbols[0][$type][$alias] = ['name' => $name, 'node' => $internalRef];
     }
 
     /**
-     * @return array{name: string, node: AssignTemplateVariable|null}|null
+     * @return array{name: string, node: AssignMacroVariable|null}|null
      */
     public function getImportedSymbol(string $type, string $alias)
     {

src/TokenParser/FromTokenParser.php

@@ -12,8 +12,8 @@
 namespace Twig\TokenParser;
 
 use Twig\Node\Expression\Variable\AssignContextVariable;
-use Twig\Node\Expression\Variable\AssignTemplateVariable;
-use Twig\Node\Expression\Variable\TemplateVariable;
+use Twig\Node\Expression\Variable\AssignMacroVariable;
+use Twig\Node\Expression\Variable\MacroVariable;
 use Twig\Node\ImportNode;
 use Twig\Node\Node;
 use Twig\Token;
@@ -52,7 +52,7 @@ final class FromTokenParser extends AbstractTokenParser
 
         $stream->expect(Token::BLOCK_END_TYPE);
 
-        $internalRef = new AssignTemplateVariable(new TemplateVariable(null, $token->getLine()), $this->parser->isMainScope());
+        $internalRef = new AssignMacroVariable(new MacroVariable(null, $token->getLine()), $this->parser->isMainScope());
         $node = new ImportNode($macro, $internalRef, $token->getLine());
 
         foreach ($targets as $name => $alias) {

src/TokenParser/ImportTokenParser.php

@@ -11,8 +11,8 @@
 
 namespace Twig\TokenParser;
 
-use Twig\Node\Expression\Variable\AssignTemplateVariable;
-use Twig\Node\Expression\Variable\TemplateVariable;
+use Twig\Node\Expression\Variable\AssignMacroVariable;
+use Twig\Node\Expression\Variable\MacroVariable;
 use Twig\Node\ImportNode;
 use Twig\Node\Node;
 use Twig\Token;
@@ -31,7 +31,7 @@ final class ImportTokenParser extends AbstractTokenParser
         $macro = $this->parser->parseExpression();
         $this->parser->getStream()->expect(Token::NAME_TYPE, 'as');
         $name = $this->parser->getStream()->expect(Token::NAME_TYPE)->getValue();
-        $var = new AssignTemplateVariable(new TemplateVariable($name, $token->getLine()), $this->parser->isMainScope());
+        $var = new AssignMacroVariable(new MacroVariable($name, $token->getLine()), $this->parser->isMainScope());
         $this->parser->getStream()->expect(Token::BLOCK_END_TYPE);
         $this->parser->addImportedSymbol('template', $name);
 

tests/Node/Expression/MacroReferenceTest.php

@@ -12,12 +12,14 @@
 namespace Twig\Tests\Node\Expression;
 
 use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Group;
 use PHPUnit\Framework\TestCase;
 use Twig\Environment;
 use Twig\Loader\ArrayLoader;
 use Twig\Node\Expression\ArrayExpression;
 use Twig\Node\Expression\MacroReferenceExpression;
 use Twig\Node\Expression\Variable\ContextVariable;
+use Twig\Node\Expression\Variable\MacroVariable;
 use Twig\Node\Expression\Variable\TemplateVariable;
 
 class MacroReferenceTest extends TestCase
@@ -31,7 +33,7 @@ class MacroReferenceTest extends TestCase
         $this->expectException(\LogicException::class);
         $this->expectExceptionMessage(\sprintf('Macro name "%s" is not a valid PHP identifier.', $name));
 
-        new MacroReferenceExpression(new TemplateVariable('foo', 1), $name, new ArrayExpression([], 1), 1);
+        new MacroReferenceExpression(new MacroVariable('foo', 1), $name, new ArrayExpression([], 1), 1);
     }
 
     public static function provideInvalidMacroNames(): iterable
@@ -44,9 +46,32 @@ class MacroReferenceTest extends TestCase
         yield 'contains NUL byte' => ["foo\x00bar"];
     }
 
+    #[Group('legacy')]
+    public function testConstructorAcceptsDeprecatedTemplateVariable(): void
+    {
+        $deprecations = [];
+        set_error_handler(static function (int $type, string $message) use (&$deprecations): bool {
+            if (\E_USER_DEPRECATED === $type) {
+                $deprecations[] = $message;
+
+                return true;
+            }
+
+            return false;
+        });
+        try {
+            $node = new MacroReferenceExpression(new TemplateVariable('foo', 1), 'macro_foo', new ArrayExpression([], 1), 1);
+        } finally {
+            restore_error_handler();
+        }
+
+        $this->assertInstanceOf(TemplateVariable::class, $node->getNode('template'));
+        $this->assertSame(['Since twig/twig 3.29: The "Twig\\Node\\Expression\\Variable\\TemplateVariable" class is deprecated, use "Twig\\Node\\Expression\\Variable\\MacroVariable" instead.'], $deprecations);
+    }
+
     public function testConstructorAcceptsAnExpressionAsName(): void
     {
-        $node = new MacroReferenceExpression(new TemplateVariable('foo', 1), new ContextVariable('name', 1), new ArrayExpression([], 1), 1);
+        $node = new MacroReferenceExpression(new MacroVariable('foo', 1), new ContextVariable('name', 1), new ArrayExpression([], 1), 1);
 
         $this->assertTrue($node->hasNode('name'));
         $this->assertNull($node->getAttribute('name'));
@@ -58,7 +83,7 @@ class MacroReferenceTest extends TestCase
         $compiler = new \Twig\Compiler($env);
 
         $node = new MacroReferenceExpression(
-            new TemplateVariable('mac', 1),
+            new MacroVariable('mac', 1),
             new ContextVariable('name', 1),
             new ArrayExpression([], 1),
             1,

tests/Node/ImportTest.php

@@ -20,8 +20,11 @@ namespace Twig\Tests\Node;
  * file that was distributed with this source code.
  */
 
+use PHPUnit\Framework\Attributes\Group;
 use Twig\Node\Expression\ConstantExpression;
+use Twig\Node\Expression\Variable\AssignMacroVariable;
 use Twig\Node\Expression\Variable\AssignTemplateVariable;
+use Twig\Node\Expression\Variable\MacroVariable;
 use Twig\Node\Expression\Variable\TemplateVariable;
 use Twig\Node\ImportNode;
 use Twig\Test\NodeTestCase;
@@ -31,18 +34,44 @@ class ImportTest extends NodeTestCase
     public function testConstructor(): void
     {
         $macro = new ConstantExpression('foo.twig', 1);
-        $node = new ImportNode($macro, new AssignTemplateVariable(new TemplateVariable('macro', 1), true), 1);
+        $node = new ImportNode($macro, new AssignMacroVariable(new MacroVariable('macro', 1), true), 1);
 
         $this->assertEquals($macro, $node->getNode('expr'));
         $this->assertEquals('macro', $node->getNode('var')->getNode('var')->getAttribute('name'));
     }
 
+    #[Group('legacy')]
+    public function testConstructorAcceptsDeprecatedAssignTemplateVariable(): void
+    {
+        $deprecations = [];
+        set_error_handler(static function (int $type, string $message) use (&$deprecations): bool {
+            if (\E_USER_DEPRECATED === $type) {
+                $deprecations[] = $message;
+
+                return true;
+            }
+
+            return false;
+        });
+        try {
+            $node = new ImportNode(new ConstantExpression('foo.twig', 1), new AssignTemplateVariable(new TemplateVariable('macro', 1), true), 1);
+        } finally {
+            restore_error_handler();
+        }
+
+        $this->assertInstanceOf(AssignTemplateVariable::class, $node->getNode('var'));
+        $this->assertSame([
+            'Since twig/twig 3.29: The "Twig\\Node\\Expression\\Variable\\TemplateVariable" class is deprecated, use "Twig\\Node\\Expression\\Variable\\MacroVariable" instead.',
+            'Since twig/twig 3.29: The "Twig\\Node\\Expression\\Variable\\AssignTemplateVariable" class is deprecated, use "Twig\\Node\\Expression\\Variable\\AssignMacroVariable" instead.',
+        ], $deprecations);
+    }
+
     public static function provideTests(): iterable
     {
         $tests = [];
 
         $macro = new ConstantExpression('foo.twig', 1);
-        $node = new ImportNode($macro, new AssignTemplateVariable(new TemplateVariable('macro', 1), true), 1);
+        $node = new ImportNode($macro, new AssignMacroVariable(new MacroVariable('macro', 1), true), 1);
 
         $tests[] = [$node, <<<EOF
 // line 1

tests/Node/ModuleTest.php

@@ -28,8 +28,8 @@ use Twig\Node\EmptyNode;
 use Twig\Node\Expression\ConstantExpression;
 use Twig\Node\Expression\Ternary\ConditionalTernary;
 use Twig\Node\Expression\Variable\AssignContextVariable;
-use Twig\Node\Expression\Variable\AssignTemplateVariable;
-use Twig\Node\Expression\Variable\TemplateVariable;
+use Twig\Node\Expression\Variable\AssignMacroVariable;
+use Twig\Node\Expression\Variable\MacroVariable;
 use Twig\Node\ImportNode;
 use Twig\Node\ModuleNode;
 use Twig\Node\Nodes;
@@ -164,7 +164,7 @@ class __TwigTemplate_%x extends Template
 }
 EOF, $twig, true];
 
-        $import = new ImportNode(new ConstantExpression('foo.twig', 1), new AssignTemplateVariable(new TemplateVariable('macro', 2), true), 2);
+        $import = new ImportNode(new ConstantExpression('foo.twig', 1), new AssignMacroVariable(new MacroVariable('macro', 2), true), 2);
 
         $body = new BodyNode([$import]);
         $extends = new ConstantExpression('layout.twig', 1);