Deprecate not passing a BodyNode instance as the body of a ModuleNode constructor

CHANGELOG

@@ -1,6 +1,7 @@
 # 3.12.0 (2024-XX-XX)
 
  * Add support for integers in methods of `Twig\Node\Node` that take a Node name
+ * Deprecate not passing a `BodyNode` instance as the body of a `ModuleNode` or `MacroNode` constructor
  * Deprecate `OptimizerNodeVisitor::OPTIMIZE_TEXT_NODES`
  * Fix performance regression when `use_yield` is `false` (which is the default)
  * Improve compatibility when `use_yield` is `false` (as extensions still using `echo` will work as is)

doc/deprecated.rst

@@ -40,6 +40,9 @@ Nodes
   ``getNode()``, ``hasNode()``, ``setNode()``, ``removeNode()``, and
   ``deprecateNode()``.
 
+* Not passing a ``BodyNode`` instance as the body of a ``ModuleNode`` or
+  ``MacroNode`` constructor is deprecated as of Twig 3.12.
+
 * The second argument of the
   ``Twig\Node\Expression\CallExpression::compileArguments()`` method is
   deprecated.

src/Node/MacroNode.php

@@ -25,8 +25,15 @@ class MacroNode extends Node
 {
     public const VARARGS_NAME = 'varargs';
 
+    /**
+     * @param BodyNode $body
+     */
     public function __construct(string $name, Node $body, Node $arguments, int $lineno, ?string $tag = null)
     {
+        if (!$body instanceof BodyNode) {
+            trigger_deprecation('twig/twig', '3.12', sprintf('Not passing a "%s" instance as the "body" argument of the "%s" constructor is deprecated.', BodyNode::class, __CLASS__));
+        }
+
         foreach ($arguments as $argumentName => $argument) {
             if (self::VARARGS_NAME === $argumentName) {
                 throw new SyntaxError(\sprintf('The argument "%s" in macro "%s" cannot be defined because the variable "%s" is reserved for arbitrary arguments.', self::VARARGS_NAME, $name, self::VARARGS_NAME), $argument->getTemplateLine(), $argument->getSourceContext());

src/Node/ModuleNode.php

@@ -30,8 +30,15 @@ use Twig\Source;
 #[YieldReady]
 final class ModuleNode extends Node
 {
+    /**
+     * @param BodyNode $body
+     */
     public function __construct(Node $body, ?AbstractExpression $parent, Node $blocks, Node $macros, Node $traits, $embeddedTemplates, Source $source)
     {
+        if (!$body instanceof BodyNode) {
+            trigger_deprecation('twig/twig', '3.12', sprintf('Not passing a "%s" instance as the "body" argument of the "%s" constructor is deprecated.', BodyNode::class, __CLASS__));
+        }
+
         $nodes = [
             'body' => $body,
             'blocks' => $blocks,

tests/Node/MacroTest.php

@@ -13,6 +13,7 @@ namespace Twig\Tests\Node;
 
 use Twig\Environment;
 use Twig\Loader\ArrayLoader;
+use Twig\Node\BodyNode;
 use Twig\Node\Expression\ConstantExpression;
 use Twig\Node\Expression\NameExpression;
 use Twig\Node\MacroNode;
@@ -24,7 +25,7 @@ class MacroTest extends NodeTestCase
 {
     public function testConstructor()
     {
-        $body = new TextNode('foo', 1);
+        $body = new BodyNode([new TextNode('foo', 1)]);
         $arguments = new Node([new NameExpression('foo', 1)], [], 1);
         $node = new MacroNode('foo', $body, $arguments, 1);
 
@@ -42,7 +43,7 @@ class MacroTest extends NodeTestCase
             'bar' => new ConstantExpression('Foo', 1),
         ], [], 1);
 
-        $body = new TextNode('foo', 1);
+        $body = new BodyNode([new TextNode('foo', 1)]);
         $node = new MacroNode('foo', $body, $arguments, 1);
 
         $text[] = [$node, <<<EOF

tests/Node/ModuleTest.php

@@ -13,6 +13,7 @@ namespace Twig\Tests\Node;
 
 use Twig\Environment;
 use Twig\Loader\ArrayLoader;
+use Twig\Node\BodyNode;
 use Twig\Node\Expression\AssignNameExpression;
 use Twig\Node\Expression\ConditionalExpression;
 use Twig\Node\Expression\ConstantExpression;
@@ -28,7 +29,7 @@ class ModuleTest extends NodeTestCase
 {
     public function testConstructor()
     {
-        $body = new TextNode('foo', 1);
+        $body = new BodyNode([new TextNode('foo', 1)]);
         $parent = new ConstantExpression('layout.twig', 1);
         $blocks = new Node();
         $macros = new Node();
@@ -49,7 +50,7 @@ class ModuleTest extends NodeTestCase
 
         $tests = [];
 
-        $body = new TextNode('foo', 1);
+        $body = new BodyNode([new TextNode('foo', 1)]);
         $extends = null;
         $blocks = new Node();
         $macros = new Node();
@@ -125,7 +126,7 @@ EOF
 
         $import = new ImportNode(new ConstantExpression('foo.twig', 1), new AssignNameExpression('macro', 1), 2);
 
-        $body = new Node([$import]);
+        $body = new BodyNode([$import]);
         $extends = new ConstantExpression('layout.twig', 1);
 
         $node = new ModuleNode($body, $extends, $blocks, $macros, $traits, new Node([]), $source);
@@ -210,7 +211,7 @@ EOF
             , $twig, true];
 
         $set = new SetNode(false, new Node([new AssignNameExpression('foo', 4)]), new Node([new ConstantExpression('foo', 4)]), 4);
-        $body = new Node([$set]);
+        $body = new BodyNode([$set]);
         $extends = new ConditionalExpression(
             new ConstantExpression(true, 2),
             new ConstantExpression('foo', 2),

tests/NodeVisitor/SandboxTest.php

@@ -14,6 +14,7 @@ namespace Twig\Tests\NodeVisitor;
 use PHPUnit\Framework\TestCase;
 use Twig\Environment;
 use Twig\Loader\ArrayLoader;
+use Twig\Node\BodyNode;
 use Twig\Node\CheckToStringNode;
 use Twig\Node\Expression\NameExpression;
 use Twig\Node\ModuleNode;
@@ -30,11 +31,11 @@ class SandboxTest extends TestCase
         $env = new Environment(new ArrayLoader());
         $expr = new NameExpression('foo', 1);
         $expr->setAttribute('is_generator', true);
-        $node = new ModuleNode(new PrintNode($expr, 1), null, new Node(), new Node(), new Node(), new Node([]), new Source('foo', 'foo'));
+        $node = new ModuleNode(new BodyNode([new PrintNode($expr, 1)]), null, new Node(), new Node(), new Node(), new Node([]), new Source('foo', 'foo'));
         $traverser = new NodeTraverser($env, [new SandboxNodeVisitor($env)]);
         $node = $traverser->traverse($node);
 
-        $this->assertNotInstanceOf(CheckToStringNode::class, $node->getNode('body')->getNode('expr'));
+        $this->assertNotInstanceOf(CheckToStringNode::class, $node->getNode('body')->getNode(0)->getNode('expr'));
         $this->assertSame("// line 1\nyield from (\$context[\"foo\"] ?? null);\n", $env->compile($node->getNode('body')));
     }
 }