Add CTE support to select in QueryBuilder

src/Platforms/AbstractPlatform.php

@@ -2034,6 +2034,16 @@ public function supportsColumnCollation(): bool
         return false;
     }
 
+    /**
+     * Does this platform support column common table expressions?
+     *
+     * @internal The method should be only used from within the {@see AbstractPlatform} class hierarchy.
+     */
+    public function supportsCTEs(): bool
+    {
+        return false;
+    }
+
     /**
      * Gets the format string, as accepted by the date() function, that describes
      * the format of a stored datetime value of this platform.

src/Platforms/DB2Platform.php

@@ -592,6 +592,12 @@ public function supportsSavepoints(): bool
         return false;
     }
 
+    /** @internal The method should be only used from within the {@see AbstractPlatform} class hierarchy. */
+    public function supportsCTEs(): bool
+    {
+        return true;
+    }
+
     /** @deprecated */
     protected function createReservedKeywordsList(): KeywordList
     {

src/Platforms/MariaDBPlatform.php

@@ -159,6 +159,12 @@ public function getColumnDeclarationSQL(string $name, array $column): string
         return parent::getColumnDeclarationSQL($name, $column);
     }
 
+    /** @internal The method should be only used from within the {@see AbstractPlatform} class hierarchy. */
+    public function supportsCTEs(): bool
+    {
+        return true;
+    }
+
     /** @deprecated */
     protected function createReservedKeywordsList(): KeywordList
     {

src/Platforms/MySQL80Platform.php

@@ -32,4 +32,10 @@ public function createSelectSQLBuilder(): SelectSQLBuilder
     {
         return AbstractPlatform::createSelectSQLBuilder();
     }
+
+    /** @internal The method should be only used from within the {@see AbstractPlatform} class hierarchy. */
+    public function supportsCTEs(): bool
+    {
+        return true;
+    }
 }

src/Platforms/MySQL84Platform.php

@@ -27,4 +27,10 @@ protected function createReservedKeywordsList(): KeywordList
 
         return new MySQL84Keywords();
     }
+
+    /** @internal The method should be only used from within the {@see AbstractPlatform} class hierarchy. */
+    public function supportsCTEs(): bool
+    {
+        return true;
+    }
 }

src/Platforms/OraclePlatform.php

@@ -739,6 +739,12 @@ public function supportsReleaseSavepoints(): bool
         return false;
     }
 
+    /** @internal The method should be only used from within the {@see AbstractPlatform} class hierarchy. */
+    public function supportsCTEs(): bool
+    {
+        return true;
+    }
+
     public function getTruncateTableSQL(string $tableName, bool $cascade = false): string
     {
         $tableIdentifier = new Identifier($tableName);

src/Platforms/PostgreSQLPlatform.php

@@ -142,6 +142,12 @@ public function supportsCommentOnStatement(): bool
         return true;
     }
 
+    /** @internal The method should be only used from within the {@see AbstractPlatform} class hierarchy. */
+    public function supportsCTEs(): bool
+    {
+        return true;
+    }
+
     /** @internal The method should be only used from within the {@see AbstractSchemaManager} class hierarchy. */
     public function getListDatabasesSQL(): string
     {

src/Platforms/SQLServerPlatform.php

@@ -131,6 +131,12 @@ public function supportsSequences(): bool
         return true;
     }
 
+    /** @internal The method should be only used from within the {@see AbstractPlatform} class hierarchy. */
+    public function supportsCTEs(): bool
+    {
+        return true;
+    }
+
     public function getAlterSequenceSQL(Sequence $sequence): string
     {
         return 'ALTER SEQUENCE ' . $sequence->getQuotedName($this) .

src/Platforms/SQLitePlatform.php

@@ -413,6 +413,12 @@ public function supportsInlineColumnComments(): bool
         return true;
     }
 
+    /** @internal The method should be only used from within the {@see AbstractPlatform} class hierarchy. */
+    public function supportsCTEs(): bool
+    {
+        return true;
+    }
+
     public function getTruncateTableSQL(string $tableName, bool $cascade = false): string
     {
         $tableIdentifier = new Identifier($tableName);

src/Query/QueryBuilder.php

@@ -25,6 +25,7 @@
 use function count;
 use function implode;
 use function is_object;
+use function sprintf;
 use function substr;
 
 /**
@@ -160,6 +161,13 @@ class QueryBuilder
      */
     private array $unionParts = [];
 
+    /**
+     * The common table expression parts.
+     *
+     * @var array<string, self>
+     */
+    private array $with = [];
+
     /**
      * The query cache profile used for caching results.
      */
@@ -342,7 +350,7 @@ public function getSQL(): string
             QueryType::INSERT => $this->getSQLForInsert(),
             QueryType::DELETE => $this->getSQLForDelete(),
             QueryType::UPDATE => $this->getSQLForUpdate(),
-            QueryType::SELECT => $this->getSQLForSelect(),
+            QueryType::SELECT => $this->getSQLForCTEs() . $this->getSQLForSelect(),
             QueryType::UNION  => $this->getSQLForUnion(),
         };
     }
@@ -1259,6 +1267,34 @@ public function resetOrderBy(): self
         return $this;
     }
 
+    /**
+     * Adds a CTE to a select query.
+     *
+     * @param string $name         The name of the CTE.
+     * @param self   $queryBuilder The query builder to use within the CTE.
+     *
+     * @return $this This QueryBuilder instance.
+     */
+    public function with(string $name, self $queryBuilder): self
+    {
+        if (! $this->connection->getDatabasePlatform()->supportsCTEs()) {
+            throw new QueryException('CTEs are not supported by this database platform.');
+        }
+
+        if ($queryBuilder->hasCTEs()) {
+            throw new QueryException('CTEs cannot be nested.');
+        }
+
+        $this->with[$name] = $queryBuilder;
+
+        return $this;
+    }
+
+    private function hasCTEs(): bool
+    {
+        return 0 < count($this->with);
+    }
+
     /** @throws Exception */
     private function getSQLForSelect(): string
     {
@@ -1283,6 +1319,20 @@ private function getSQLForSelect(): string
             );
     }
 
+    private function getSQLForCTEs(): string
+    {
+        if (! $this->hasCTEs()) {
+            return '';
+        }
+
+        $cte = [];
+        foreach ($this->with as $name => $queryBuilder) {
+            $cte[] = sprintf('%s AS (%s)', $name, $queryBuilder->getSQL());
+        }
+
+        return 'WITH ' . implode(', ', $cte) . ' ';
+    }
+
     /**
      * @return array<string, string>
      *

tests/Functional/Query/QueryBuilderTest.php

@@ -4,6 +4,7 @@
 
 namespace Doctrine\DBAL\Tests\Functional\Query;
 
+use Doctrine\DBAL\ArrayParameterType;
 use Doctrine\DBAL\DriverManager;
 use Doctrine\DBAL\Exception;
 use Doctrine\DBAL\ParameterType;
@@ -14,6 +15,7 @@
 use Doctrine\DBAL\Platforms\MySQLPlatform;
 use Doctrine\DBAL\Platforms\SQLitePlatform;
 use Doctrine\DBAL\Query\ForUpdate\ConflictResolutionMode;
+use Doctrine\DBAL\Query\QueryException;
 use Doctrine\DBAL\Query\UnionType;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Tests\FunctionalTestCase;
@@ -332,6 +334,67 @@ public function testUnionAndAddUnionWorksWithQueryBuilderPartsAndReturnsExpected
         self::assertSame($expectedRows, $qb->executeQuery()->fetchAllAssociative());
     }
 
+    public function testNotSupportedCTE(): void
+    {
+        if ($this->connection->getDatabasePlatform()->supportsCTEs()) {
+            self::markTestSkipped('The database platform does support CTE.');
+        }
+
+        $qb = $this->connection->createQueryBuilder();
+
+        $cteQueryBuilder1 = $this->connection->createQueryBuilder();
+        $cteQueryBuilder1->select('id')
+            ->from('for_update');
+
+        self::expectException(QueryException::class);
+        self::expectExceptionMessage('CTEs are not supported by this database platform.');
+
+        $qb->with('filtered_for_update', $cteQueryBuilder1);
+    }
+
+    public function testWithNamedParameterCTE(): void
+    {
+        if (! $this->connection->getDatabasePlatform()->supportsCTEs()) {
+            self::markTestSkipped('The database platform does not support CTE.');
+        }
+
+        $expectedRows = $this->prepareExpectedRows([['id' => 1]]);
+        $qb           = $this->connection->createQueryBuilder();
+
+        $cteQueryBuilder1 = $this->connection->createQueryBuilder();
+        $cteQueryBuilder1->select('id')
+            ->from('for_update')
+            ->where($qb->expr()->eq('id', $qb->createNamedParameter(1, ParameterType::INTEGER)));
+
+        $qb->with('filtered_for_update', $cteQueryBuilder1)
+            ->select('id')
+            ->from('filtered_for_update');
+
+        self::assertSame($expectedRows, $qb->executeQuery()->fetchAllAssociative());
+    }
+
+    public function testWithPositionalParameterCTE(): void
+    {
+        if (! $this->connection->getDatabasePlatform()->supportsCTEs()) {
+            self::markTestSkipped('The database platform does not support CTE.');
+        }
+
+        $expectedRows = $this->prepareExpectedRows([['id' => 1]]);
+        $qb           = $this->connection->createQueryBuilder();
+
+        $cteQueryBuilder1 = $this->connection->createQueryBuilder();
+        $cteQueryBuilder1->select('id')
+            ->from('for_update')
+            ->where($qb->expr()->in('id', $qb->createPositionalParameter([1, 2], ArrayParameterType::INTEGER)));
+
+        $qb->with('filtered_for_update', $cteQueryBuilder1)
+            ->select('id')
+            ->from('filtered_for_update')
+            ->where($qb->expr()->eq('id', $qb->createPositionalParameter(1, ParameterType::INTEGER)));
+
+        self::assertSame($expectedRows, $qb->executeQuery()->fetchAllAssociative());
+    }
+
     /**
      * @param array<array<string, int>> $rows
      *

tests/Query/QueryBuilderTest.php

@@ -48,6 +48,8 @@ protected function setUp(): void
             ->willReturn(new DefaultSelectSQLBuilder($platform, null, null));
         $platform->method('createUnionSQLBuilder')
             ->willReturn(new DefaultUnionSQLBuilder($platform));
+        $platform->method('supportsCTEs')
+            ->willReturn(true);
 
         $this->conn->method('getDatabasePlatform')
             ->willReturn($platform);
@@ -850,6 +852,46 @@ public function testSelectAllWithoutTableAlias(): void
         self::assertEquals('SELECT * FROM users', (string) $qb);
     }
 
+    public function testSelectWithCTE(): void
+    {
+        $qbWith = new QueryBuilder($this->conn);
+        $qbWith->select('id', 'name')
+            ->from('users')
+            ->where('name LIKE :name');
+
+        $qb = new QueryBuilder($this->conn);
+        $qb->with('filtered_users', $qbWith)
+            ->select('*')
+            ->from('filtered_users', 'fu');
+
+        self::assertEquals(
+            'WITH filtered_users AS (SELECT id, name FROM users WHERE name LIKE :name)'
+            . ' SELECT * FROM filtered_users fu',
+            $qb->getSQL(),
+        );
+    }
+
+    public function testSelectNestedCTE(): void
+    {
+        $qbNested = new QueryBuilder($this->conn);
+        $qbNested->select('*')
+            ->from('country');
+
+        $qbWith = new QueryBuilder($this->conn);
+        $qbWith->select('id', 'name')
+            ->with('countries', $qbNested)
+            ->from('users')
+            ->where('name LIKE :name');
+
+        self::expectException(QueryException::class);
+        self::expectExceptionMessage('CTEs cannot be nested.');
+
+        $qb = new QueryBuilder($this->conn);
+        $qb->with('filtered_users', $qbWith)
+            ->select('*')
+            ->from('filtered_users', 'fu');
+    }
+
     public function testGetParameterType(): void
     {
         $qb = new QueryBuilder($this->conn);