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\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 @@ public function parse(Parser $parser, AbstractExpression $expr, Token $token): A
             && \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 @@
 
 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 @@ public function __clone()
     {
         // 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());
-    }
-
-    public function compile(Compiler $compiler): void
-    {
-        /** @var TemplateVariable $var */
-        $var = $this->nodes['var'];
-
-        $compiler
-            ->addDebugInfo($this)
-            ->write('$macros[')
-            ->string($var->getName($compiler))
-            ->raw('] = ')
-        ;
+        trigger_deprecation('twig/twig', '3.29', 'The "%s" class is deprecated, use "%s" instead.', self::class, AssignMacroVariable::class);
 
-        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 @@
 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 @@
 #[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\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 @@ public function embedTemplate(ModuleNode $template): void
         $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 @@ public function parse(Token $token): Node
 
         $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 @@ public function parse(Token $token): Node
         $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);