Merge branch '3.8.x' into 4.0.x

* 3.8.x:
  Add deprecation layer and upgrade path for QueryBuilder::reset*() methods

UPGRADE.md

@@ -921,6 +921,23 @@ The following methods have been removed.
 
 # Upgrade to 3.8
 
+## Deprecated reset methods from `QueryBuilder`
+
+`QueryBuilder::resetQueryParts()` has been deprecated.
+
+Resetting individual query parts through the generic `resetQueryPart()` method has been deprecated as well.
+However, several replacements have been put in place depending on the `$queryPartName` parameter:
+
+| `$queryPartName` | suggested replacement                      |
+|------------------|--------------------------------------------|
+| `'select'`       | Call `select()` with a new set of columns. |
+| `'distinct'`     | `distinct(false)`                          |
+| `'where'`        | `resetWhere()`                             |
+| `'groupBy'`      | `resetGroupBy()`                           |
+| `'having'`       | `resetHaving()`                            |
+| `'orderBy'`      | `resetOrderBy()`                           |
+| `'values'`       | Call `values()` with a new set of values.  |
+
 ## Deprecated getting query parts from `QueryBuilder`
 
 The usage of `QueryBuilder::getQueryPart()` and `::getQueryParts()` is deprecated. The query parts

src/Query/QueryBuilder.php

@@ -515,7 +515,7 @@ public function select(string ...$expressions): self
     }
 
     /**
-     * Adds DISTINCT to the query.
+     * Adds or removes DISTINCT to/from the query.
      *
      * <code>
      *     $qb = $conn->createQueryBuilder()
@@ -526,11 +526,10 @@ public function select(string ...$expressions): self
      *
      * @return $this This QueryBuilder instance.
      */
-    public function distinct(): self
+    public function distinct(bool $distinct = true): self
     {
-        $this->distinct = true;
-
-        $this->sql = null;
+        $this->distinct = $distinct;
+        $this->sql      = null;
 
         return $this;
     }
@@ -1139,6 +1138,45 @@ public function addOrderBy(string $sort, ?string $order = null): self
         return $this;
     }
 
+    /**
+     * Resets the WHERE conditions for the query.
+     *
+     * @return $this This QueryBuilder instance.
+     */
+    public function resetWhere(): self
+    {
+        $this->where = null;
+        $this->sql   = null;
+
+        return $this;
+    }
+
+    /**
+     * Resets the grouping for the query.
+     *
+     * @return $this This QueryBuilder instance.
+     */
+    public function resetGroupBy(): self
+    {
+        $this->groupBy = [];
+        $this->sql     = null;
+
+        return $this;
+    }
+
+    /**
+     * Resets the HAVING conditions for the query.
+     *
+     * @return $this This QueryBuilder instance.
+     */
+    public function resetHaving(): self
+    {
+        $this->having = null;
+        $this->sql    = null;
+
+        return $this;
+    }
+
     /**
      * Resets the ordering for the query.
      *

tests/Query/QueryBuilderTest.php

@@ -503,15 +503,76 @@ public function testSetFirstResult(): void
         self::assertEquals(10, $qb->getFirstResult());
     }
 
+    private function prepareQueryBuilderToReset(): QueryBuilder
+    {
+        $qb = (new QueryBuilder($this->conn))
+            ->select('u.*')
+            ->distinct()
+            ->from('users', 'u')
+            ->where('u.name = ?')
+            ->orderBy('u.name', 'ASC');
+
+        self::assertEquals('SELECT DISTINCT u.* FROM users u WHERE u.name = ? ORDER BY u.name ASC', (string) $qb);
+
+        return $qb;
+    }
+
+    public function testResetDistinct(): void
+    {
+        $qb = $this->prepareQueryBuilderToReset()->distinct(false);
+
+        self::assertEquals('SELECT u.* FROM users u WHERE u.name = ? ORDER BY u.name ASC', (string) $qb);
+    }
+
+    public function testResetWhere(): void
+    {
+        $qb = $this->prepareQueryBuilderToReset()->resetWhere();
+
+        self::assertEquals('SELECT DISTINCT u.* FROM users u ORDER BY u.name ASC', (string) $qb);
+    }
+
     public function testResetOrderBy(): void
     {
-        $qb = new QueryBuilder($this->conn);
+        $qb = $this->prepareQueryBuilderToReset()->resetOrderBy();
 
-        $qb->select('u.*')->from('users', 'u')->orderBy('u.name', 'ASC');
+        self::assertEquals('SELECT DISTINCT u.* FROM users u WHERE u.name = ?', (string) $qb);
+    }
+
+    private function prepareGroupedQueryBuilderToReset(): QueryBuilder
+    {
+        $qb = (new QueryBuilder($this->conn))
+            ->select('u.country', 'COUNT(*)')
+            ->from('users', 'u')
+            ->groupBy('u.country')
+            ->having('COUNT(*) > ?')
+            ->orderBy('COUNT(*)', 'DESC');
 
-        self::assertEquals('SELECT u.* FROM users u ORDER BY u.name ASC', (string) $qb);
-        $qb->resetOrderBy();
-        self::assertEquals('SELECT u.* FROM users u', (string) $qb);
+        self::assertEquals(
+            'SELECT u.country, COUNT(*) FROM users u GROUP BY u.country HAVING COUNT(*) > ? ORDER BY COUNT(*) DESC',
+            (string) $qb,
+        );
+
+        return $qb;
+    }
+
+    public function testResetHaving(): void
+    {
+        $qb = $this->prepareGroupedQueryBuilderToReset()->resetHaving();
+
+        self::assertEquals(
+            'SELECT u.country, COUNT(*) FROM users u GROUP BY u.country ORDER BY COUNT(*) DESC',
+            (string) $qb,
+        );
+    }
+
+    public function testGroupBy(): void
+    {
+        $qb = $this->prepareGroupedQueryBuilderToReset()->resetGroupBy();
+
+        self::assertEquals(
+            'SELECT u.country, COUNT(*) FROM users u HAVING COUNT(*) > ? ORDER BY COUNT(*) DESC',
+            (string) $qb,
+        );
     }
 
     public function testCreateNamedParameter(): void