Add CTE support to select in QueryBuilder

docs/en/reference/query-builder.rst

@@ -368,6 +368,26 @@ or QueryBuilder instances to one of the following methods:
         ->orderBy('field', 'DESC')
         ->setMaxResults(100);
 
+WITH-Clause
+~~~~~~~~~~~
+
+To define Common Table Expressions (CTEs) that can be used in select query.
+
+* ``with(string $name, string|QueryBuilder $queryBuilder, array $columns = [])``
+
+.. code-block:: php
+
+    <?php
+
+    $queryBuilder
+        ->with('cte_a', 'SELECT id FROM table_a')
+        ->with('cte_b', 'SELECT id FROM table_b')
+        ->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.
+
 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 @@
     {
         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 @@
         return parent::getDefaultValueDeclarationSQL($column);
     }
 
+    public function createWithSQLBuilder(): WithSQLBuilder
+    {
+        throw NotSupported::new(__METHOD__);
+    }
+
     /**
      * {@inheritDoc}
      */

src/Query/QueryBuilder.php

@@ -160,6 +160,13 @@
      */
     private array $unionParts = [];
 
+    /**
+     * The common table expression parts.
+     *
+     * @var With[]
+     */
+    private array $withParts = [];
+
     /**
      * The query cache profile used for caching results.
      */
@@ -302,14 +309,51 @@
      */
     public function executeQuery(): Result
     {
+        [$params, $types] = $this->boundParameters();
+
         return $this->connection->executeQuery(
             $this->getSQL(),
-            $this->params,
-            $this->types,
+            $params,
+            $types,
             $this->resultCacheProfile,
         );
     }
 
+    /**
+     * Retrieve parameters and types bound to all queries (optional CTEs and main query).
+     *
+     * @return array{
+     *     list<mixed>|array<string, mixed>,
+     *     WrapperParameterTypeArray,
+     * } The parameters and types bound to the CTE queries merged with those bound to the main query.
+     */
+    private function boundParameters(): array
+    {
+        if (count($this->withParts) === 0) {
+            return [$this->params, $this->types];
+        }
+
+        $cteParams = $cteParamsTypes = [];
+
+        foreach ($this->withParts as $withPart) {
+            if (! $withPart->query instanceof self) {
+                continue;
+            }
+
+            $cteParams      = array_merge($cteParams, $withPart->query->params);
+            $cteParamsTypes = array_merge($cteParamsTypes, $withPart->query->types);
+        }
+
+        if (count($cteParams) === 0) {
+            return [$this->params, $this->types];
+        }
+
+        return [
+            array_merge($cteParams, $this->params),
+            array_merge($cteParamsTypes, $this->types),
+        ];
+    }
+
     /**
      * Executes an SQL statement and returns the number of affected rows.
      *
@@ -557,6 +601,33 @@
         return $this;
     }
 
+    /**
+     * Add a Common Table Expression to be used for a select query.
+     *
+     * <code>
+     *     // WITH cte_name AS (SELECT 1 AS column1)
+     *     $qb = $conn->createQueryBuilder()
+     *         ->with('cte_name', 'SELECT 1 AS column1');
+     *
+     *     // WITH cte_name(column1) AS (SELECT 1 AS column1)
+     *     $qb = $conn->createQueryBuilder()
+     *         ->with('cte_name', 'SELECT 1 AS column1', ['column1']);
+     * </code>
+     *
+     * @param string   $name    The name of the CTE
+     * @param string[] $columns The optional columns list to select in the CTE.
+     *
+     * @return $this This QueryBuilder instance.
+     */
+    public function with(string $name, string|QueryBuilder $part, array $columns = []): self
+    {
+        $this->withParts[] = new With($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 +1337,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->withParts) > 0) {
+            $selectParts[] = $databasePlatform
+                ->createWithSQLBuilder()
+                ->buildSQL(...$this->withParts);
+        }
+
+        $selectParts[] = $databasePlatform
             ->createSelectSQLBuilder()
             ->buildSQL(
                 new SelectQuery(
@@ -1281,6 +1360,8 @@
                     $this->forUpdate,
                 ),
             );
+
+        return implode(' ', $selectParts);
     }
 
     /**

src/Query/With.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Query;
+
+/** @internal */
+final class With
+{
+    /** @param string[] $columns */
+    public function __construct(
+        public readonly string $name,
+        public readonly string|QueryBuilder $query,
+        public readonly array $columns = [],
+    ) {
+    }
+}

src/SQL/Builder/WithSQLBuilder.php

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