From 5d20e3cec0643789ec728b2d15a288784b63fd24 Mon Sep 17 00:00:00 2001
From: Benjamin Eberlei <kontakt@beberlei.de>
Date: Sun, 7 Mar 2021 00:10:35 +0100
Subject: [PATCH] [GH-3844] Add deprecation message for
 CompositeExpression::add/addMultiple

---
 .../Query/Expression/CompositeExpression.php  | 41 +++++++++++++++----
 .../Expression/CompositeExpressionTest.php    |  8 ++++
 2 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php b/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php
index 596e9fb3afc..ae4ad818532 100644
--- a/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php
+++ b/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php
@@ -3,6 +3,7 @@
 namespace Doctrine\DBAL\Query\Expression;
 
 use Countable;
+use Doctrine\Deprecations\Deprecation;
 
 use function array_merge;
 use function count;
@@ -43,11 +44,21 @@ class CompositeExpression implements Countable
      * @param string          $type  Instance type of composite expression.
      * @param self[]|string[] $parts Composition of expressions to be joined on composite expression.
      */
-    public function __construct($type, array $parts = [])
+    public function __construct($type, array $parts = [], bool $internalFlagCalledByFactory = false)
     {
         $this->type = $type;
 
-        $this->addMultiple($parts);
+        $this->addMultiple($parts, $internalFlagCalledByFactory);
+
+        if ($internalFlagCalledByFactory) {
+            return;
+        }
+
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/3864',
+            'Do not use CompositeExpression constructor directly, use static and() and or() factory methods.'
+        );
     }
 
     /**
@@ -56,7 +67,7 @@ public function __construct($type, array $parts = [])
      */
     public static function and($part, ...$parts): self
     {
-        return new self(self::TYPE_AND, array_merge([$part], $parts));
+        return new self(self::TYPE_AND, array_merge([$part], $parts), true);
     }
 
     /**
@@ -65,7 +76,7 @@ public static function and($part, ...$parts): self
      */
     public static function or($part, ...$parts): self
     {
-        return new self(self::TYPE_OR, array_merge([$part], $parts));
+        return new self(self::TYPE_OR, array_merge([$part], $parts), true);
     }
 
     /**
@@ -77,10 +88,18 @@ public static function or($part, ...$parts): self
      *
      * @return CompositeExpression
      */
-    public function addMultiple(array $parts = [])
+    public function addMultiple(array $parts = [], bool $internalFlagCalledByConstructor = false)
     {
+        if ($internalFlagCalledByConstructor === false) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/issues/3844',
+                'CompositeExpression::addMultiple() is deprecated, use CompositeExpression::with() instead.'
+            );
+        }
+
         foreach ($parts as $part) {
-            $this->add($part);
+            $this->add($part, true);
         }
 
         return $this;
@@ -95,8 +114,16 @@ public function addMultiple(array $parts = [])
      *
      * @return CompositeExpression
      */
-    public function add($part)
+    public function add($part, bool $internalFlagCalledByAddMultiple = false)
     {
+        if ($internalFlagCalledByAddMultiple === false) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/issues/3844',
+                'CompositeExpression::add() is deprecated, use CompositeExpression::with() instead.'
+            );
+        }
+
         if (empty($part)) {
             return $this;
         }
diff --git a/tests/Doctrine/Tests/DBAL/Query/Expression/CompositeExpressionTest.php b/tests/Doctrine/Tests/DBAL/Query/Expression/CompositeExpressionTest.php
index c1daefa4d35..6762d4a58fc 100644
--- a/tests/Doctrine/Tests/DBAL/Query/Expression/CompositeExpressionTest.php
+++ b/tests/Doctrine/Tests/DBAL/Query/Expression/CompositeExpressionTest.php
@@ -3,10 +3,13 @@
 namespace Doctrine\Tests\DBAL\Query\Expression;
 
 use Doctrine\DBAL\Query\Expression\CompositeExpression;
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use Doctrine\Tests\DbalTestCase;
 
 class CompositeExpressionTest extends DbalTestCase
 {
+    use VerifyDeprecations;
+
     public function testCount(): void
     {
         $expr = CompositeExpression::or('u.group_id = 1');
@@ -20,6 +23,9 @@ public function testCount(): void
 
     public function testAdd(): void
     {
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/dbal/pull/3864');
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/dbal/issues/3844');
+
         $expr = CompositeExpression::or('u.group_id = 1');
 
         self::assertCount(1, $expr);
@@ -68,6 +74,8 @@ public function testWith(): void
      */
     public function testCompositeUsageAndGeneration(string $type, array $parts, string $expects): void
     {
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/dbal/pull/3864');
+
         $expr = new CompositeExpression($type, $parts);
 
         self::assertEquals($expects, (string) $expr);