From 1ee4210ba9f81b7bafe66a3dd7253ed91ee46575 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien@potencier.org>
Date: Fri, 23 Aug 2024 19:44:16 +0200
Subject: [PATCH] Deprecate node names that are not strings or integers

---
 CHANGELOG          |  1 +
 doc/deprecated.rst |  5 +++++
 src/Node/Node.php  | 26 ++++++++++++++++++++++----
 3 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index 30e00839f..627423370 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,5 +1,6 @@
 # 3.12.0 (2024-XX-XX)
 
+ * Add support for integers in methods of `Twig\Node\Node` that take a Node name
  * 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)
diff --git a/doc/deprecated.rst b/doc/deprecated.rst
index 8320a2290..f5fa4a77e 100644
--- a/doc/deprecated.rst
+++ b/doc/deprecated.rst
@@ -35,6 +35,11 @@ Extensions
 Nodes
 -----
 
+* The following ``Twig\Node\Node`` methods will take a string or an integer
+  (instead of just a string) in Twig 4.0 for their "name" argument:
+  ``getNode()``, ``hasNode()``, ``setNode()``, ``removeNode()``, and
+  ``deprecateNode()``.
+
 * The second argument of the
   ``Twig\Node\Expression\CallExpression::compileArguments()`` method is
   deprecated.
diff --git a/src/Node/Node.php b/src/Node/Node.php
index 770cdaf43..b23906056 100644
--- a/src/Node/Node.php
+++ b/src/Node/Node.php
@@ -24,6 +24,9 @@ use Twig\Source;
 #[YieldReady]
 class Node implements \Countable, \IteratorAggregate
 {
+    /**
+     * @var array<string|int, Node>
+     */
     protected $nodes;
     protected $attributes;
     protected $lineno;
@@ -36,10 +39,10 @@ class Node implements \Countable, \IteratorAggregate
     private $attributeNameDeprecations = [];
 
     /**
-     * @param array  $nodes      An array of named nodes
-     * @param array  $attributes An array of attributes (should not be nodes)
-     * @param int    $lineno     The line number
-     * @param string $tag        The tag name associated with the Node
+     * @param array<string|int, Node> $nodes      An array of named nodes
+     * @param array                   $attributes An array of attributes (should not be nodes)
+     * @param int                     $lineno     The line number
+     * @param string                  $tag        The tag name associated with the Node
      */
     public function __construct(array $nodes = [], array $attributes = [], int $lineno = 0, ?string $tag = null)
     {
@@ -158,11 +161,17 @@ class Node implements \Countable, \IteratorAggregate
         unset($this->attributes[$name]);
     }
 
+    /**
+     * @param string|int $name
+     */
     public function hasNode(string $name): bool
     {
         return isset($this->nodes[$name]);
     }
 
+    /**
+     * @param string|int $name
+     */
     public function getNode(string $name): self
     {
         if (!isset($this->nodes[$name])) {
@@ -182,6 +191,9 @@ class Node implements \Countable, \IteratorAggregate
         return $this->nodes[$name];
     }
 
+    /**
+     * @param string|int $name
+     */
     public function setNode(string $name, self $node): void
     {
         $triggerDeprecation = \func_num_args() > 2 ? func_get_arg(2) : true;
@@ -200,11 +212,17 @@ class Node implements \Countable, \IteratorAggregate
         $this->nodes[$name] = $node;
     }
 
+    /**
+     * @param string|int $name
+     */
     public function removeNode(string $name): void
     {
         unset($this->nodes[$name]);
     }
 
+    /**
+     * @param string|int $name
+     */
     public function deprecateNode(string $name, NameDeprecation $dep): void
     {
         $this->nodeNameDeprecations[$name] = $dep;