Add Node::replace() method.

Author: drupol

spec/loophp/phptree/Node/ValueNodeSpec.php

@@ -146,6 +146,31 @@ public function it_can_remove(): void
             ->shouldReturn(0);
     }
 
+    public function it_can_replace_a_node_with_another_one()
+    {
+        $this
+            ->beConstructedWith('root');
+
+        $node1 = new ValueNode('A');
+        $node2 = new ValueNode('B');
+        $node3 = new ValueNode('C');
+
+        $this
+            ->add($node1, $node2, $node3);
+
+        $node4 = new ValueNode('D');
+
+        $this
+            ->offsetGet(0)
+            ->replace($node4);
+
+        $this->shouldHaveSameTextExport('[root[D][B][C]]');
+
+        $this
+            ->replace($node4)
+            ->shouldReturn(null);
+    }
+
     public function it_is_initializable(): void
     {
         $this

src/Node/Node.php

@@ -313,6 +313,27 @@ static function ($child) use ($nodes) {
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function replace(NodeInterface $node): ?NodeInterface
+    {
+        if (null === $parent = $this->getParent()) {
+            return null;
+        }
+
+        // Find the key of the current node in the parent.
+        foreach ($parent->children() as $key => $child) {
+            if ($this === $child) {
+                $parent[$key] = $node;
+
+                return $parent;
+            }
+        }
+
+        return $this;
+    }
+
     /**
      * {@inheritdoc}
      */

src/Node/NodeInterface.php

@@ -161,6 +161,19 @@ public function level(int $level): Traversable;
      */
     public function remove(NodeInterface ...$node): NodeInterface;
 
+    /**
+     * Replace a node with another one and return the parent.
+     *
+     * It may also return null if the replace failed.
+     *
+     * @param \loophp\phptree\Node\NodeInterface $node
+     *   The replacement node.
+     *
+     * @return \loophp\phptree\Node\NodeInterface|null
+     *   The node parent if successful, null otherwise.
+     */
+    public function replace(NodeInterface $node): ?NodeInterface;
+
     /**
      * Set the parent.
      *