Add rudimentary UNION support to the QueryBuilder

The `UNION` operator is used to combine the result-set
of two or more `SELECT` statements, which all database
vendors supports with usual specialities for each.

Still, there is a common shared subset which works for
all of them:

```
    SELECT column_name(s) FROM table1
    WHERE ...

    UNION <ALL | DISTINCT>

    SELECT column_name(s) FROM table2
    WHERE ...

    ORDER BY ...
    LIMIT x OFFSET y
```

with shared common requirements:

* Each `SELECT` must return the same fields
  in number, naming and order.

* Each `SELECT` **must not** have `ORDER BY`,
  expect MySQL allowing it to be used as sub
  query expression encapsulated in parentheses.

Taking the shared requirements and working behaviour,
it is possible to provide a generic support to the
QueryBuilder with a minimalistic surface addition now,
and following methods are added:

* `union(string|QueryBuilder ...$unionParts)` and
  `addUnion(string|QueryBuilder ...$unionParts)` to
   create a `UNION` query retrieving unique rows
* `unionAll(string|QueryBuilder ...$unionParts)` and
  `addUnionAll(string|QueryBuilder ...$unionParts) to
   create a `UNION ALL` query retrieving eventually
   duplicated rows.

This follows the generic logic as `select(...)` and
`addSelect(...)` along with introducing new internal
`QueryType::UNION_DISTINCT` and `QueryType::UNION_ALL`
enum cases.

Additional to the consideration to allow SQL strings
and QueryBuilder for `union()`, `unionAll(), `addUnion()`
and `addUnionAll()` and minimize the direct handling
of miss-configuration to the number of provided parts
and let other issues like the field (order, count, naming)
or not allowed order by handling to the database itself.
With that, vendor specific implementation can be done if
required.

Technically, the SQL build process is dispatched to a
`DefaultUnionSQLBuilder` along with an `UnionSQLBuilder`
interface, which also allows application to implement
custom behaviour if required.

Example:

```php
$platform = $connection->getDatabasePlatform();
$qb       = $>connection->createQueryBuilder();
$select10 = $platform->getDummySelectSQL('2 as field_one');
$select20 = $platform->getDummySelectSQL('1 as field_one');
$qb->union($select10,    /*$select11, $select12, ... */)
   ->addUnion($select20, /*$select21, $select22, ... */)
   ->setMaxResults(1)
   ->setFirstResult(1)
   ->orderBy('field_one', 'ASC');
$rows = $qb->executeQuery()->fetchAllAssociative();
```

Unit and functional tests are added to demonstrate the
implementation and cover it for future changes.

Resolves: #6368

docs/en/reference/query-builder.rst

@@ -315,6 +315,53 @@ user-input:
         ->setParameter(0, $userInputLastLogin)
     ;
 
+UNION-Clause
+~~~~~~~~~~~~
+
+To combine multiple ``SELECT`` queries into one result-set you can pass SQL Part strings
+or QueryBuilder instances to one of the following methods:
+
+* ``union('SELECT 1 as field', $partQueryBuilder)``
+* ``addUnion('SELECT 1 as field', $partQueryBuilder)``
+* ``unionAll('SELECT 1 as field', $partQueryBuilder)``
+* ``addUnionAll('SELECT 1 as field', $partQueryBuilder)``
+
+.. code-block:: php
+
+    <?php
+
+    $queryBuilder
+        ->union('SELECT 1 AS field', 'SELECT 2 AS field')
+        ->addUnion('SELECT 3 AS field', 'SELECT 3 as field')
+    ;
+
+    $queryBuilder
+        ->unionAll('SELECT 1 AS field', 'SELECT 2 AS field')
+        ->addUnionAll('SELECT 3 AS field', 'SELECT 3 as field')
+    ;
+
+    $subQueryBuilder1
+        ->select('id AS field')
+        ->from('a_table');
+    $subQueryBuilder2
+        ->select('id AS field')
+        ->from('a_table');
+    $queryBuilder
+        ->union($subQueryBuilder1)
+        ->addUnion($subQueryBuilder2)
+    ;
+
+    $subQueryBuilder1
+        ->select('id AS field')
+        ->from('a_table');
+    $subQueryBuilder2
+        ->select('id AS field')
+        ->from('a_table');
+    $queryBuilder
+        ->unionAll($subQueryBuilder1)
+        ->addUnionAll($subQueryBuilder2)
+    ;
+
 Building Expressions
 --------------------
 

src/Platforms/AbstractPlatform.php

@@ -27,7 +27,9 @@
 use Doctrine\DBAL\Schema\TableDiff;
 use Doctrine\DBAL\Schema\UniqueConstraint;
 use Doctrine\DBAL\SQL\Builder\DefaultSelectSQLBuilder;
+use Doctrine\DBAL\SQL\Builder\DefaultUnionSQLBuilder;
 use Doctrine\DBAL\SQL\Builder\SelectSQLBuilder;
+use Doctrine\DBAL\SQL\Builder\UnionSQLBuilder;
 use Doctrine\DBAL\SQL\Parser;
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types;
@@ -770,6 +772,11 @@ public function createSelectSQLBuilder(): SelectSQLBuilder
         return new DefaultSelectSQLBuilder($this, 'FOR UPDATE', 'SKIP LOCKED');
     }
 
+    public function createUnionSQLBuilder(): UnionSQLBuilder
+    {
+        return new DefaultUnionSQLBuilder($this);
+    }
+
     /**
      * @internal
      *
@@ -2210,6 +2217,11 @@ public function columnsEqual(Column $column1, Column $column2): bool
         return $column1->getComment() === $column2->getComment();
     }
 
+    public function getUnionPartSQL(string $subQuery): string
+    {
+        return sprintf('(%s)', $subQuery);
+    }
+
     /**
      * Creates the schema manager that can be used to inspect and change the underlying
      * database schema according to the dialect of the platform.

src/Query/QueryBuilder.php

@@ -153,6 +153,13 @@ class QueryBuilder
      */
     private array $values = [];
 
+    /**
+     * The QueryBuilder for the union parts.
+     *
+     * @var Union[]
+     */
+    private array $unionParts = [];
+
     /**
      * The query cache profile used for caching results.
      */
@@ -336,6 +343,7 @@ public function getSQL(): string
             QueryType::DELETE => $this->getSQLForDelete(),
             QueryType::UPDATE => $this->getSQLForUpdate(),
             QueryType::SELECT => $this->getSQLForSelect(),
+            QueryType::UNION  => $this->getSQLForUnion(),
         };
     }
 
@@ -501,6 +509,50 @@ public function forUpdate(ConflictResolutionMode $conflictResolutionMode = Confl
         return $this;
     }
 
+    /**
+     * Specifies union parts to be used to build a UNION query.
+     * Replaces any previously specified parts.
+     *
+     * <code>
+     *     $qb = $conn->createQueryBuilder()
+     *         ->union('SELECT 1 AS field1', 'SELECT 2 AS field1');
+     * </code>
+     *
+     * @return $this
+     */
+    public function union(string|QueryBuilder $part): self
+    {
+        $this->type = QueryType::UNION;
+
+        $this->unionParts = [new Union($part)];
+
+        $this->sql = null;
+
+        return $this;
+    }
+
+    /**
+     * Add parts to be used to build a UNION query.
+     *
+     * <code>
+     *     $qb = $conn->createQueryBuilder()
+     *         ->union('SELECT 1 AS field1')
+     *         ->addUnion('SELECT 2 AS field1', 'SELECT 3 AS field1')
+     * </code>
+     *
+     * @return $this
+     */
+    public function addUnion(string|QueryBuilder $part, UnionType $type): self
+    {
+        $this->type = QueryType::UNION;
+
+        $this->unionParts[] = new Union($part, $type);
+
+        $this->sql = null;
+
+        return $this;
+    }
+
     /**
      * Specifies an item that is to be returned in the query result.
      * Replaces any previously specified selections, if any.
@@ -1309,6 +1361,31 @@ private function getSQLForDelete(): string
         return $query;
     }
 
+    /**
+     * Converts this instance into a UNION string in SQL.
+     */
+    private function getSQLForUnion(): string
+    {
+        $countUnions = count($this->unionParts);
+        if ($countUnions < 2) {
+            $message = $countUnions === 0
+                ? 'No UNION parts given. Please use union(), unionAll, addUnion or addUnionAll().'
+                : 'Insufficient UNION parts give, need at least 2. Please use addUnion() or addUnionAll() to add more.';
+
+            throw new QueryException($message);
+        }
+
+        return $this->connection->getDatabasePlatform()
+            ->createUnionSQLBuilder()
+            ->buildSQL(
+                new UnionQuery(
+                    $this->unionParts,
+                    $this->orderBy,
+                    new Limit($this->maxResults, $this->firstResult),
+                ),
+            );
+    }
+
     /**
      * Gets a string representation of this QueryBuilder which corresponds to
      * the final SQL query being constructed.

src/Query/QueryType.php

@@ -11,4 +11,5 @@ enum QueryType
     case DELETE;
     case UPDATE;
     case INSERT;
+    case UNION;
 }

src/Query/Union.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Query;
+
+/** @internal */
+final class Union
+{
+    public function __construct(
+        public readonly string|QueryBuilder $query,
+        public readonly ?UnionType          $type = null,
+    ) {
+    }
+}

src/Query/UnionQuery.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Query;
+
+final class UnionQuery
+{
+    /**
+     * @internal This class should be instantiated only by {@link QueryBuilder}.
+     *
+     * @param Union[]   $unionParts
+     * @param string[]  $orderBy
+     */
+    public function __construct(
+        private readonly array $unionParts,
+        private readonly array $orderBy,
+        private readonly Limit $limit,
+    ) {
+    }
+
+    /** @return Union[] */
+    public function getUnionParts(): array
+    {
+        return $this->unionParts;
+    }
+
+    /** @return string[] */
+    public function getOrderBy(): array
+    {
+        return $this->orderBy;
+    }
+
+    public function getLimit(): Limit
+    {
+        return $this->limit;
+    }
+}

src/Query/UnionType.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Query;
+
+/** @internal */
+enum UnionType
+{
+    case ALL;
+    case DISTINCT;
+}

src/SQL/Builder/DefaultUnionSQLBuilder.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\SQL\Builder;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Query\UnionQuery;
+
+use Doctrine\DBAL\Query\UnionType;
+use function count;
+use function implode;
+
+final class DefaultUnionSQLBuilder implements UnionSQLBuilder
+{
+    public function __construct(
+        private readonly AbstractPlatform $platform,
+    ) {
+    }
+
+    public function buildSQL(UnionQuery $query): string
+    {
+        $parts = [];
+        foreach ($query->getUnionParts() as $union) {
+            if ($union->type !== []) {
+                $parts[] = match ($union->type) {
+                    UnionType::ALL => 'UNION ALL',
+                    UnionType::DISTINCT => 'UNION',
+                };
+            }
+
+            $parts[] = $this->platform->getUnionPartSQL($union->query);
+        }
+
+        $orderBy = $query->getOrderBy();
+        if (count($orderBy) > 0) {
+            $parts[] = 'ORDER BY ' . implode(', ', $orderBy);
+        }
+
+        $sql   = implode(' ', $parts);
+        $limit = $query->getLimit();
+
+        if ($limit->isDefined()) {
+            $sql = $this->platform->modifyLimitQuery($sql, $limit->getMaxResults(), $limit->getFirstResult());
+        }
+
+        return $sql;
+    }
+}

src/SQL/Builder/UnionSQLBuilder.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\SQL\Builder;
+
+use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\Query\UnionQuery;
+
+interface UnionSQLBuilder
+{
+    /** @throws Exception */
+    public function buildSQL(UnionQuery $query): string;
+}