Add CompositeExpression::with(), deprecate add*()

Author: BenMorel

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

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.
      *

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);

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
      *