From 20324a4f39adfb71861ba910252f73f19cf5f7ea Mon Sep 17 00:00:00 2001
From: Benjamin Morel <benjamin.morel@gmail.com>
Date: Mon, 27 Jan 2020 11:18:58 +0100
Subject: [PATCH] Add CompositeExpression::with(), deprecate add*()

---
 UPGRADE.md                                    |  5 ++++
 .../Query/Expression/CompositeExpression.php  | 23 +++++++++++++++++++
 lib/Doctrine/DBAL/Query/QueryBuilder.php      |  8 +++----
 .../Expression/CompositeExpressionTest.php    | 22 +++++++++++++++++-
 4 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/UPGRADE.md b/UPGRADE.md
index e6f03cfc34f..beed13b5732 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -4,6 +4,11 @@
 
 The usage of the `andX()` and `orX()` methods of the `ExpressionBuilder` class has been deprecated. Use `and()` and `or()` instead.
 
+## Deprecated `CompositeExpression` methods
+
+The usage of the `add()` and `addMultiple()` methods of the `CompositeExpression` class has been deprecated. Use `with()` instead, which returns a new instance.
+In the future, the `add*()` methods will be removed and the class will be effectively immutable.
+
 # Upgrade to 2.10
 
 ## Deprecated `Doctrine\DBAL\Event\ConnectionEventArgs` methods
diff --git a/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php b/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php
index 443d71bc37e..204a356c2f2 100644
--- a/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php
+++ b/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php
@@ -49,6 +49,8 @@ public function __construct($type, array $parts = [])
     /**
      * Adds multiple parts to composite expression.
      *
+     * @deprecated This class will be made immutable. Use with() instead.
+     *
      * @param self[]|string[] $parts
      *
      * @return \Doctrine\DBAL\Query\Expression\CompositeExpression
@@ -65,6 +67,8 @@ public function addMultiple(array $parts = [])
     /**
      * Adds an expression to composite expression.
      *
+     * @deprecated This class will be made immutable. Use with() instead.
+     *
      * @param mixed $part
      *
      * @return \Doctrine\DBAL\Query\Expression\CompositeExpression
@@ -84,6 +88,25 @@ public function add($part)
         return $this;
     }
 
+    /**
+     * Returns a new CompositeExpression with the given parts added.
+     *
+     * @param self|string $part
+     * @param self|string ...$parts
+     */
+    public function with($part, ...$parts) : self
+    {
+        $that = clone $this;
+
+        $that->parts[] = $part;
+
+        foreach ($parts as $part) {
+            $that->parts[] = $part;
+        }
+
+        return $that;
+    }
+
     /**
      * Retrieves the amount of expressions on composite expression.
      *
diff --git a/lib/Doctrine/DBAL/Query/QueryBuilder.php b/lib/Doctrine/DBAL/Query/QueryBuilder.php
index 587e26656ab..58d7062f0a7 100644
--- a/lib/Doctrine/DBAL/Query/QueryBuilder.php
+++ b/lib/Doctrine/DBAL/Query/QueryBuilder.php
@@ -823,7 +823,7 @@ public function andWhere($where)
         $where = $this->getQueryPart('where');
 
         if ($where instanceof CompositeExpression && $where->getType() === CompositeExpression::TYPE_AND) {
-            $where->addMultiple($args);
+            $where = $where->with(...$args);
         } else {
             array_unshift($args, $where);
             $where = new CompositeExpression(CompositeExpression::TYPE_AND, $args);
@@ -856,7 +856,7 @@ public function orWhere($where)
         $where = $this->getQueryPart('where');
 
         if ($where instanceof CompositeExpression && $where->getType() === CompositeExpression::TYPE_OR) {
-            $where->addMultiple($args);
+            $where = $where->with(...$args);
         } else {
             array_unshift($args, $where);
             $where = new CompositeExpression(CompositeExpression::TYPE_OR, $args);
@@ -998,7 +998,7 @@ public function andHaving($having)
         $having = $this->getQueryPart('having');
 
         if ($having instanceof CompositeExpression && $having->getType() === CompositeExpression::TYPE_AND) {
-            $having->addMultiple($args);
+            $having = $having->with(...$args);
         } else {
             array_unshift($args, $having);
             $having = new CompositeExpression(CompositeExpression::TYPE_AND, $args);
@@ -1021,7 +1021,7 @@ public function orHaving($having)
         $having = $this->getQueryPart('having');
 
         if ($having instanceof CompositeExpression && $having->getType() === CompositeExpression::TYPE_OR) {
-            $having->addMultiple($args);
+            $having = $having->with(...$args);
         } else {
             array_unshift($args, $having);
             $having = new CompositeExpression(CompositeExpression::TYPE_OR, $args);
diff --git a/tests/Doctrine/Tests/DBAL/Query/Expression/CompositeExpressionTest.php b/tests/Doctrine/Tests/DBAL/Query/Expression/CompositeExpressionTest.php
index 0a8492f795f..fd02e25f6f7 100644
--- a/tests/Doctrine/Tests/DBAL/Query/Expression/CompositeExpressionTest.php
+++ b/tests/Doctrine/Tests/DBAL/Query/Expression/CompositeExpressionTest.php
@@ -16,7 +16,7 @@ public function testCount() : void
 
         self::assertCount(1, $expr);
 
-        $expr->add('u.group_id = 2');
+        $expr = $expr->with('u.group_id = 2');
 
         self::assertCount(2, $expr);
     }
@@ -44,6 +44,26 @@ public function testAdd() : void
         self::assertCount(3, $expr);
     }
 
+    public function testWith() : void
+    {
+        $expr = new CompositeExpression(CompositeExpression::TYPE_OR, ['u.group_id = 1']);
+
+        self::assertCount(1, $expr);
+
+        // test immutability
+        $expr->with(new CompositeExpression(CompositeExpression::TYPE_OR, ['u.user_id = 1']));
+
+        self::assertCount(1, $expr);
+
+        $expr = $expr->with(new CompositeExpression(CompositeExpression::TYPE_OR, ['u.user_id = 1']));
+
+        self::assertCount(2, $expr);
+
+        $expr = $expr->with('u.user_id = 1');
+
+        self::assertCount(3, $expr);
+    }
+
     /**
      * @param string[]|CompositeExpression[] $parts
      *