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

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
  *