Merge pull request #12541 from HypeMC/case-null

Allow `NULL` literal in `SELECT` and `CASE` expressions

Author: greg0ire

docs/en/reference/dql-doctrine-query-language.rst

@@ -617,7 +617,7 @@ You can also nest several DTO :
     $query = $em->createQuery('SELECT NEW CustomerDTO(c.name, e.email, NEW AddressDTO(a.street, a.city, a.zip)) FROM Customer c JOIN c.email e JOIN c.address a');
     $users = $query->getResult(); // array of CustomerDTO
 
-Note that you can only pass scalar expressions or other Data Transfer Objects to the constructor.
+Note that you can only pass scalar expressions, the ``NULL`` literal or other Data Transfer Objects to the constructor.
 
 If you use your data transfer objects for multiple queries, and you would rather not have to
 specify arguments that precede the ones you are really interested in, you can use named arguments.
@@ -1780,7 +1780,7 @@ Scalar and Type Expressions
 
 .. code-block:: php
 
-    ScalarExpression       ::= SimpleArithmeticExpression | StringPrimary | DatetimePrimary | StateFieldPathExpression | BooleanPrimary | CaseExpression | InstanceOfExpression
+    ScalarExpression       ::= SimpleArithmeticExpression | StringPrimary | DatetimePrimary | StateFieldPathExpression | BooleanPrimary | CaseExpression | InstanceOfExpression | "NULL"
     StringExpression       ::= StringPrimary | ResultVariable | "(" Subselect ")"
     StringPrimary          ::= StateFieldPathExpression | string | InputParameter | FunctionsReturningStrings | AggregateExpression | CaseExpression
     BooleanExpression      ::= BooleanPrimary | "(" Subselect ")"

phpstan-baseline.neon

@@ -2725,7 +2725,7 @@ parameters:
 			path: src/Query/SqlWalker.php
 
 		-
-			message: '#^Match arm comparison between 3 and 3 is always true\.$#'
+			message: '#^Match arm comparison between 4 and 4 is always true\.$#'
 			identifier: match.alwaysTrue
 			count: 1
 			path: src/Query/SqlWalker.php

src/Query/AST/Literal.php

@@ -11,6 +11,7 @@ class Literal extends Node
     final public const STRING  = 1;
     final public const BOOLEAN = 2;
     final public const NUMERIC = 3;
+    final public const NULL    = 4;
 
     /** @phpstan-param self::* $type */
     public function __construct(

src/Query/Parser.php

@@ -1951,7 +1951,7 @@ public function IndexBy(): AST\IndexBy
     /**
      * ScalarExpression ::= SimpleArithmeticExpression | StringPrimary | DatetimePrimary |
      *                      StateFieldPathExpression | BooleanPrimary | CaseExpression |
-     *                      InstanceOfExpression
+     *                      InstanceOfExpression | "NULL"
      *
      * @return mixed One of the possible expressions or subexpressions.
      */
@@ -1979,6 +1979,11 @@ public function ScalarExpression(): mixed
 
                 return new AST\Literal(AST\Literal::BOOLEAN, $this->lexer->token->value);
 
+            case $lookahead === TokenType::T_NULL:
+                $this->match(TokenType::T_NULL);
+
+                return new AST\Literal(AST\Literal::NULL, null);
+
             case $lookahead === TokenType::T_INPUT_PARAMETER:
                 return match (true) {
                     $this->isMathOperator($peek) => $this->SimpleArithmeticExpression(),
@@ -2199,6 +2204,11 @@ public function SelectExpression(): AST\SelectExpression
                 $expression = $identVariable = $this->IdentificationVariable();
                 break;
 
+            // ScalarExpression (NULL)
+            case $lookaheadType === TokenType::T_NULL:
+                $expression = $this->ScalarExpression();
+                break;
+
             // CaseExpression (CASE ... or NULLIF(...) or COALESCE(...))
             case $lookaheadType === TokenType::T_CASE:
             case $lookaheadType === TokenType::T_COALESCE:

src/Query/SqlWalker.php

@@ -2099,6 +2099,7 @@ public function walkLiteral(AST\Literal $literal): string
             AST\Literal::STRING => $this->conn->quote($literal->value),
             AST\Literal::BOOLEAN => (string) $this->conn->getDatabasePlatform()->convertBooleans(strtolower($literal->value) === 'true'),
             AST\Literal::NUMERIC => (string) $literal->value,
+            AST\Literal::NULL => 'NULL',
             default => throw QueryException::invalidLiteral($literal),
         };
     }

tests/Tests/ORM/Functional/NewOperatorTest.php

@@ -266,6 +266,47 @@ public function testShouldSupportLiteralExpression(): void
         self::assertEquals(123, $result[2]->phonenumbers);
     }
 
+    public function testShouldSupportNullLiteralExpression(): void
+    {
+        $dql = "
+            SELECT
+                new Doctrine\Tests\Models\CMS\CmsUserDTO(
+                    u.name,
+                    'fabio.bat.silva@gmail.com',
+                    null,
+                    123
+                )
+            FROM
+                Doctrine\Tests\Models\CMS\CmsUser u
+            ORDER BY
+                u.name";
+
+        $query  = $this->_em->createQuery($dql);
+        $result = $query->getResult();
+
+        self::assertCount(3, $result);
+
+        self::assertInstanceOf(CmsUserDTO::class, $result[0]);
+        self::assertInstanceOf(CmsUserDTO::class, $result[1]);
+        self::assertInstanceOf(CmsUserDTO::class, $result[2]);
+
+        self::assertEquals($this->fixtures[0]->name, $result[0]->name);
+        self::assertEquals($this->fixtures[1]->name, $result[1]->name);
+        self::assertEquals($this->fixtures[2]->name, $result[2]->name);
+
+        self::assertEquals('fabio.bat.silva@gmail.com', $result[0]->email);
+        self::assertEquals('fabio.bat.silva@gmail.com', $result[1]->email);
+        self::assertEquals('fabio.bat.silva@gmail.com', $result[2]->email);
+
+        self::assertNull($result[0]->address);
+        self::assertNull($result[1]->address);
+        self::assertNull($result[2]->address);
+
+        self::assertEquals(123, $result[0]->phonenumbers);
+        self::assertEquals(123, $result[1]->phonenumbers);
+        self::assertEquals(123, $result[2]->phonenumbers);
+    }
+
     public function testShouldSupportCaseExpression(): void
     {
         $dql = "

tests/Tests/ORM/Query/LanguageRecognitionTest.php

@@ -640,6 +640,36 @@ public function testCaseSupportContainingCoalesceExpression(): void
         $this->assertValidDQL("select COALESCE(NULLIF(u.name, ''), u.username) as Display FROM Doctrine\Tests\Models\CMS\CmsUser u");
     }
 
+    public function testSelectClauseSupportsNullLiteral(): void
+    {
+        $this->assertValidDQL('SELECT u.name, NULL FROM Doctrine\Tests\Models\CMS\CmsUser u');
+    }
+
+    public function testSelectClauseSupportsAliasedNullLiteral(): void
+    {
+        $this->assertValidDQL('SELECT NULL AS nil FROM Doctrine\Tests\Models\CMS\CmsUser u');
+    }
+
+    public function testSubselectSupportsNullLiteral(): void
+    {
+        $this->assertValidDQL('SELECT u.name FROM Doctrine\Tests\Models\CMS\CmsUser u WHERE u.id IN (SELECT NULL FROM Doctrine\Tests\Models\CMS\CmsUser u2)');
+    }
+
+    public function testGeneralCaseSupportsNullLiteralInThenAndElseClauses(): void
+    {
+        $this->assertValidDQL('SELECT CASE WHEN u.id > 10 THEN NULL ELSE NULL END FROM Doctrine\Tests\Models\CMS\CmsUser u');
+    }
+
+    public function testSimpleCaseSupportsNullLiteralInThenAndElseClauses(): void
+    {
+        $this->assertValidDQL("SELECT CASE u.name WHEN 'admin' THEN NULL ELSE NULL END FROM Doctrine\Tests\Models\CMS\CmsUser u");
+    }
+
+    public function testCoalesceSupportsNullLiteral(): void
+    {
+        $this->assertValidDQL('SELECT COALESCE(NULL, u.name) FROM Doctrine\Tests\Models\CMS\CmsUser u');
+    }
+
     #[Group('DDC-1858')]
     public function testHavingSupportIsNullExpression(): void
     {
@@ -670,6 +700,11 @@ public function testNewLiteralWithSubselectExpression(): void
         $this->assertValidDQL('SELECT new ' . __NAMESPACE__ . "\\DummyStruct(u.id, 'foo', (SELECT 1 FROM Doctrine\Tests\Models\CMS\CmsUser su), true) FROM Doctrine\Tests\Models\CMS\CmsUser u");
     }
 
+    public function testNewNullLiteralExpression(): void
+    {
+        $this->assertValidDQL('SELECT new ' . __NAMESPACE__ . "\\DummyStruct(u.id, 'foo', null, true) FROM Doctrine\Tests\Models\CMS\CmsUser u");
+    }
+
     public function testStringPrimaryAcceptsAggregateExpression(): void
     {
         $this->assertValidDQL(

tests/Tests/ORM/Query/SelectSqlGenerationTest.php

@@ -1277,6 +1277,46 @@ public function testSimpleCaseWithMultipleWhenClauseInSubselect(): void
         );
     }
 
+    public function testNullLiteralInSelectClause(): void
+    {
+        $this->assertSqlGeneration(
+            'SELECT g.id, NULL FROM Doctrine\Tests\Models\CMS\CmsGroup g',
+            'SELECT c0_.id AS id_0, NULL AS sclr_1 FROM cms_groups c0_',
+        );
+    }
+
+    public function testAliasedNullLiteralInSelectClause(): void
+    {
+        $this->assertSqlGeneration(
+            'SELECT g.id, NULL AS nil FROM Doctrine\Tests\Models\CMS\CmsGroup g',
+            'SELECT c0_.id AS id_0, NULL AS sclr_1 FROM cms_groups c0_',
+        );
+    }
+
+    public function testNullLiteralInSubselect(): void
+    {
+        $this->assertSqlGeneration(
+            'SELECT g.id FROM Doctrine\Tests\Models\CMS\CmsGroup g WHERE g.id IN (SELECT NULL FROM Doctrine\Tests\Models\CMS\CmsGroup g2)',
+            'SELECT c0_.id AS id_0 FROM cms_groups c0_ WHERE c0_.id IN (SELECT NULL AS sclr_1 FROM cms_groups c1_)',
+        );
+    }
+
+    public function testGeneralCaseWithNullLiteralInElseClause(): void
+    {
+        $this->assertSqlGeneration(
+            'SELECT g.id, COUNT(CASE WHEN ((g.id / 2) > 18) THEN 1 ELSE NULL END) AS test FROM Doctrine\Tests\Models\CMS\CmsGroup g GROUP BY g.id',
+            'SELECT c0_.id AS id_0, COUNT(CASE WHEN ((c0_.id / 2) > 18) THEN 1 ELSE NULL END) AS sclr_1 FROM cms_groups c0_ GROUP BY c0_.id',
+        );
+    }
+
+    public function testSimpleCaseWithNullLiteralInThenClause(): void
+    {
+        $this->assertSqlGeneration(
+            "SELECT g.id, CASE g.name WHEN 'admin' THEN NULL ELSE 1 END AS test FROM Doctrine\Tests\Models\CMS\CmsGroup g",
+            "SELECT c0_.id AS id_0, CASE c0_.name WHEN 'admin' THEN NULL ELSE 1 END AS sclr_1 FROM cms_groups c0_",
+        );
+    }
+
     #[Group('DDC-1696')]
     public function testSimpleCaseWithStringPrimary(): void
     {
@@ -1708,6 +1748,11 @@ public function testSupportsNewOperator(): void
             'SELECT new Doctrine\Tests\Models\CMS\CmsUserDTO(a.id, (SELECT 1 FROM Doctrine\Tests\Models\CMS\CmsUser su), a.country, a.city), new Doctrine\Tests\Models\CMS\CmsAddressDTO(u.name, e.email) FROM Doctrine\Tests\Models\CMS\CmsUser u JOIN u.email e JOIN u.address a ORDER BY u.name',
             'SELECT c0_.id AS sclr_0, (SELECT 1 AS sclr_2 FROM cms_users c1_) AS sclr_1, c0_.country AS sclr_3, c0_.city AS sclr_4, c2_.name AS sclr_5, c3_.email AS sclr_6 FROM cms_users c2_ INNER JOIN cms_emails c3_ ON c2_.email_id = c3_.id INNER JOIN cms_addresses c0_ ON c2_.id = c0_.user_id ORDER BY c2_.name ASC',
         );
+
+        $this->assertSqlGeneration(
+            'SELECT new Doctrine\Tests\Models\CMS\CmsUserDTO(u.name, e.email, NULL, 123) FROM Doctrine\Tests\Models\CMS\CmsUser u JOIN u.email e',
+            'SELECT c0_.name AS sclr_0, c1_.email AS sclr_1, NULL AS sclr_2, 123 AS sclr_3 FROM cms_users c0_ INNER JOIN cms_emails c1_ ON c0_.email_id = c1_.id',
+        );
     }
 
     #[Group('DDC-2234')]