Add CTE support to select in QueryBuilder

docs/en/reference/query-builder.rst

@@ -368,6 +368,39 @@ or QueryBuilder instances to one of the following methods:
         ->orderBy('field', 'DESC')
         ->setMaxResults(100);
 
+Common Table Expressions
+~~~~~~~~~~~
+
+To define Common Table Expressions (CTEs) that can be used in select query.
+
+* ``with(string $name, string|QueryBuilder $queryBuilder, ?array $columns = null)``
+
+.. code-block:: php
+
+    <?php
+
+    $cteQueryBuilder1
+        ->select('id')
+        ->from('table_a')
+        ->where('id = :id')
+        ->setParameter('id', 1);
+
+    $cteQueryBuilder2
+        ->select('id')
+        ->from('table_b');
+
+    $queryBuilder
+        ->with('cte_a', $cteQueryBuilder1)
+        ->with('cte_b', $cteQueryBuilder2)
+        ->select('id')
+        ->from('cte_b', 'b')
+        ->join('b', 'cte_a', 'a', 'a.id = b.id');
+
+Multiple CTEs can be defined by calling the with method multiple times.
+
+Parameters used in a CTE should be defined directly in the QueryBuilder of the CTE.
+This way, the CTE builders are naturally composable.
+
 Building Expressions
 --------------------
 

src/Platforms/AbstractPlatform.php

@@ -31,6 +31,7 @@
 use Doctrine\DBAL\SQL\Builder\DefaultUnionSQLBuilder;
 use Doctrine\DBAL\SQL\Builder\SelectSQLBuilder;
 use Doctrine\DBAL\SQL\Builder\UnionSQLBuilder;
+use Doctrine\DBAL\SQL\Builder\WithSQLBuilder;
 use Doctrine\DBAL\SQL\Parser;
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types;
@@ -802,6 +803,11 @@ public function createUnionSQLBuilder(): UnionSQLBuilder
         return new DefaultUnionSQLBuilder($this);
     }
 
+    public function createWithSQLBuilder(): WithSQLBuilder
+    {
+        return new WithSQLBuilder();
+    }
+
     /**
      * @internal
      *

src/Platforms/MySQL80Platform.php

@@ -7,6 +7,7 @@
 use Doctrine\DBAL\Platforms\Keywords\KeywordList;
 use Doctrine\DBAL\Platforms\Keywords\MySQL80Keywords;
 use Doctrine\DBAL\SQL\Builder\SelectSQLBuilder;
+use Doctrine\DBAL\SQL\Builder\WithSQLBuilder;
 use Doctrine\Deprecations\Deprecation;
 
 /**
@@ -32,4 +33,9 @@ public function createSelectSQLBuilder(): SelectSQLBuilder
     {
         return AbstractPlatform::createSelectSQLBuilder();
     }
+
+    public function createWithSQLBuilder(): WithSQLBuilder
+    {
+        return AbstractPlatform::createWithSQLBuilder();
+    }
 }

src/Platforms/MySQLPlatform.php

@@ -4,9 +4,11 @@
 
 namespace Doctrine\DBAL\Platforms;
 
+use Doctrine\DBAL\Platforms\Exception\NotSupported;
 use Doctrine\DBAL\Platforms\Keywords\KeywordList;
 use Doctrine\DBAL\Platforms\Keywords\MySQLKeywords;
 use Doctrine\DBAL\Schema\Index;
+use Doctrine\DBAL\SQL\Builder\WithSQLBuilder;
 use Doctrine\DBAL\Types\BlobType;
 use Doctrine\DBAL\Types\TextType;
 use Doctrine\Deprecations\Deprecation;
@@ -35,6 +37,11 @@ public function getDefaultValueDeclarationSQL(array $column): string
         return parent::getDefaultValueDeclarationSQL($column);
     }
 
+    public function createWithSQLBuilder(): WithSQLBuilder
+    {
+        throw NotSupported::new(__METHOD__);
+    }
+
     /**
      * {@inheritDoc}
      */

src/Query/CommonTableExpression.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Query;
+
+use function count;
+use function sprintf;
+
+/** @internal */
+final class CommonTableExpression
+{
+    /** @param string[]|null $columns */
+    public function __construct(
+        public readonly string $name,
+        public readonly string|QueryBuilder $query,
+        public readonly ?array $columns,
+    ) {
+        if ($columns !== null && count($columns) === 0) {
+            throw new QueryException(sprintf('Columns defined in CTE "%s" should not be an empty array.', $name));
+        }
+    }
+}

src/Query/QueryBuilder.php

@@ -160,6 +160,13 @@
      */
     private array $unionParts = [];
 
+    /**
+     * The common table expression parts.
+     *
+     * @var CommonTableExpression[]
+     */
+    private array $commonTableExpressions = [];
+
     /**
      * The query cache profile used for caching results.
      */
@@ -302,14 +309,47 @@
      */
     public function executeQuery(): Result
     {
+        [$params, $types] = $this->buildParametersAndTypes();
+
         return $this->connection->executeQuery(
             $this->getSQL(),
-            $this->params,
-            $this->types,
+            $params,
+            $types,
             $this->resultCacheProfile,
         );
     }
 
+    /**
+     * Build then return parameters and types for the query.
+     *
+     * @return array{
+     *     list<mixed>|array<string, mixed>,
+     *     WrapperParameterTypeArray,
+     * } The parameters and types for the query.
+     */
+    private function buildParametersAndTypes(): array
+    {
+        $cteParams = $cteParamTypes = [];
+
+        foreach ($this->commonTableExpressions as $cte) {
+            if (! $cte->query instanceof self) {
+                continue;
+            }
+
+            $cteParams     = array_merge($cteParams, $cte->query->params);
+            $cteParamTypes = array_merge($cteParamTypes, $cte->query->types);
+        }
+
+        if (count($cteParams) === 0) {
+            return [$this->params, $this->types];
+        }
+
+        return [
+            array_merge($cteParams, $this->params),
+            array_merge($cteParamTypes, $this->types),
+        ];
+    }
+
     /**
      * Executes an SQL statement and returns the number of affected rows.
      *
@@ -557,6 +597,36 @@
         return $this;
     }
 
+    /**
+     * Add a Common Table Expression to be used for a select query.
+     *
+     * <code>
+     *     // WITH cte_name AS (SELECT id AS column1 FROM table_a)
+     *     $qb = $conn->createQueryBuilder()
+     *         ->with('cte_name', 'SELECT id AS column1 FROM table_a');
+     *
+     *     // WITH cte_name(column1) AS (SELECT id AS column1 FROM table_a)
+     *     $qb = $conn->createQueryBuilder()
+     *         ->with('cte_name', 'SELECT id AS column1 FROM table_a', ['column1']);
+     * </code>
+     *
+     * @param string        $name    The name of the CTE
+     * @param string[]|null $columns The optional columns list to select in the CTE.
+     *                               If not provided, the columns are inferred from the CTE.
+     *
+     * @return $this This QueryBuilder instance.
+     *
+     * @throws QueryException Setting an empty array as columns is not allowed.
+     */
+    public function with(string $name, string|QueryBuilder $part, ?array $columns = null): self
+    {
+        $this->commonTableExpressions[] = new CommonTableExpression($name, $part, $columns);
+
+        $this->sql = null;
+
+        return $this;
+    }
+
     /**
      * Specifies an item that is to be returned in the query result.
      * Replaces any previously specified selections, if any.
@@ -1266,7 +1336,15 @@
             throw new QueryException('No SELECT expressions given. Please use select() or addSelect().');
         }
 
-        return $this->connection->getDatabasePlatform()
+        $databasePlatform = $this->connection->getDatabasePlatform();
+        $selectParts      = [];
+        if (count($this->commonTableExpressions) > 0) {
+            $selectParts[] = $databasePlatform
+                ->createWithSQLBuilder()
+                ->buildSQL(...$this->commonTableExpressions);
+        }
+
+        $selectParts[] = $databasePlatform
             ->createSelectSQLBuilder()
             ->buildSQL(
                 new SelectQuery(
@@ -1281,6 +1359,8 @@
                     $this->forUpdate,
                 ),
             );
+
+        return implode(' ', $selectParts);
     }
 
     /**

src/SQL/Builder/WithSQLBuilder.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\SQL\Builder;
+
+use Doctrine\DBAL\Query\CommonTableExpression;
+
+use function array_merge;
+use function count;
+use function implode;
+
+final class WithSQLBuilder
+{
+    public function buildSQL(CommonTableExpression $firstExpression, CommonTableExpression ...$otherExpressions): string
+    {
+        $cteParts = [];
+
+        foreach (array_merge([$firstExpression], $otherExpressions) as $part) {
+            $ctePart = [$part->name];
+            if ($part->columns !== null && count($part->columns) > 0) {
+                $ctePart[] = '(' . implode(', ', $part->columns) . ')';
+            }
+
+            $ctePart[]  = ' AS (' . $part->query . ')';
+            $cteParts[] = implode('', $ctePart);
+        }
+
+        return 'WITH ' . implode(', ', $cteParts);
+    }
+}