1. <?php
3. declare(strict_types=1);
5. namespace Doctrine\ORM\Query;
7. use Doctrine\Common\Lexer\Token;
8. use Doctrine\Deprecations\Deprecation;
9. use Doctrine\ORM\EntityManagerInterface;
10. use Doctrine\ORM\Mapping\ClassMetadata;
11. use Doctrine\ORM\Query;
12. use Doctrine\ORM\Query\AST\Functions;
13. use LogicException;
14. use ReflectionClass;
16. use function array_intersect;
17. use function array_search;
18. use function assert;
19. use function class_exists;
20. use function count;
21. use function explode;
22. use function implode;
23. use function in_array;
24. use function interface_exists;
25. use function is_string;
26. use function sprintf;
27. use function str_contains;
28. use function strlen;
29. use function strpos;
30. use function strrpos;
31. use function strtolower;
32. use function substr;
34. /**
35.  * An LL(*) recursive-descent parser for the context-free grammar of the Doctrine Query Language.
36.  * Parses a DQL query, reports any errors in it, and generates an AST.
37.  *
38.  * @psalm-import-type AssociationMapping from ClassMetadata
39.  * @psalm-type DqlToken = Token<Lexer::T_*, string>
40.  * @psalm-type QueryComponent = array{
41.  *                 metadata?: ClassMetadata<object>,
42.  *                 parent?: string|null,
43.  *                 relation?: AssociationMapping|null,
44.  *                 map?: string|null,
45.  *                 resultVariable?: AST\Node|string,
46.  *                 nestingLevel: int,
47.  *                 token: DqlToken,
48.  *             }
49.  */
50. class Parser
51. {
52.     /**
53.      * @readonly Maps BUILT-IN string function names to AST class names.
54.      * @psalm-var array<string, class-string<Functions\FunctionNode>>
55.      */
56.     private static $stringFunctions = [
57.         'concat'    => Functions\ConcatFunction::class,
58.         'substring' => Functions\SubstringFunction::class,
59.         'trim'      => Functions\TrimFunction::class,
60.         'lower'     => Functions\LowerFunction::class,
61.         'upper'     => Functions\UpperFunction::class,
62.         'identity'  => Functions\IdentityFunction::class,
63.     ];
65.     /**
66.      * @readonly Maps BUILT-IN numeric function names to AST class names.
67.      * @psalm-var array<string, class-string<Functions\FunctionNode>>
68.      */
69.     private static $numericFunctions = [
70.         'length'    => Functions\LengthFunction::class,
71.         'locate'    => Functions\LocateFunction::class,
72.         'abs'       => Functions\AbsFunction::class,
73.         'sqrt'      => Functions\SqrtFunction::class,
74.         'mod'       => Functions\ModFunction::class,
75.         'size'      => Functions\SizeFunction::class,
76.         'date_diff' => Functions\DateDiffFunction::class,
77.         'bit_and'   => Functions\BitAndFunction::class,
78.         'bit_or'    => Functions\BitOrFunction::class,
80.         // Aggregate functions
81.         'min'       => Functions\MinFunction::class,
82.         'max'       => Functions\MaxFunction::class,
83.         'avg'       => Functions\AvgFunction::class,
84.         'sum'       => Functions\SumFunction::class,
85.         'count'     => Functions\CountFunction::class,
86.     ];
88.     /**
89.      * @readonly Maps BUILT-IN datetime function names to AST class names.
90.      * @psalm-var array<string, class-string<Functions\FunctionNode>>
91.      */
92.     private static $datetimeFunctions = [
93.         'current_date'      => Functions\CurrentDateFunction::class,
94.         'current_time'      => Functions\CurrentTimeFunction::class,
95.         'current_timestamp' => Functions\CurrentTimestampFunction::class,
96.         'date_add'          => Functions\DateAddFunction::class,
97.         'date_sub'          => Functions\DateSubFunction::class,
98.     ];
100.     /*
101.      * Expressions that were encountered during parsing of identifiers and expressions
102.      * and still need to be validated.
103.      */
105.     /** @psalm-var list<array{token: DqlToken|null, expression: mixed, nestingLevel: int}> */
106.     private $deferredIdentificationVariables = [];
108.     /** @psalm-var list<array{token: DqlToken|null, expression: AST\PartialObjectExpression, nestingLevel: int}> */
109.     private $deferredPartialObjectExpressions = [];
111.     /** @psalm-var list<array{token: DqlToken|null, expression: AST\PathExpression, nestingLevel: int}> */
112.     private $deferredPathExpressions = [];
114.     /** @psalm-var list<array{token: DqlToken|null, expression: mixed, nestingLevel: int}> */
115.     private $deferredResultVariables = [];
117.     /** @psalm-var list<array{token: DqlToken|null, expression: AST\NewObjectExpression, nestingLevel: int}> */
118.     private $deferredNewObjectExpressions = [];
120.     /**
121.      * The lexer.
122.      *
123.      * @var Lexer
124.      */
125.     private $lexer;
127.     /**
128.      * The parser result.
129.      *
130.      * @var ParserResult
131.      */
132.     private $parserResult;
134.     /**
135.      * The EntityManager.
136.      *
137.      * @var EntityManagerInterface
138.      */
139.     private $em;
141.     /**
142.      * The Query to parse.
143.      *
144.      * @var Query
145.      */
146.     private $query;
148.     /**
149.      * Map of declared query components in the parsed query.
150.      *
151.      * @psalm-var array<string, QueryComponent>
152.      */
153.     private $queryComponents = [];
155.     /**
156.      * Keeps the nesting level of defined ResultVariables.
157.      *
158.      * @var int
159.      */
160.     private $nestingLevel = 0;
162.     /**
163.      * Any additional custom tree walkers that modify the AST.
164.      *
165.      * @psalm-var list<class-string<TreeWalker>>
166.      */
167.     private $customTreeWalkers = [];
169.     /**
170.      * The custom last tree walker, if any, that is responsible for producing the output.
171.      *
172.      * @var class-string<SqlWalker>|null
173.      */
174.     private $customOutputWalker;
176.     /** @psalm-var array<string, AST\SelectExpression> */
177.     private $identVariableExpressions = [];
179.     /**
180.      * Creates a new query parser object.
181.      *
182.      * @param Query $query The Query to parse.
183.      */
184.     public function __construct(Query $query)
185.     {
186.         $this->query        = $query;
187.         $this->em           = $query->getEntityManager();
188.         $this->lexer        = new Lexer((string) $query->getDQL());
189.         $this->parserResult = new ParserResult();
190.     }
192.     /**
193.      * Sets a custom tree walker that produces output.
194.      * This tree walker will be run last over the AST, after any other walkers.
195.      *
196.      * @param string $className
197.      * @psalm-param class-string<SqlWalker> $className
198.      *
199.      * @return void
200.      */
201.     public function setCustomOutputTreeWalker($className)
202.     {
203.         $this->customOutputWalker = $className;
204.     }
206.     /**
207.      * Adds a custom tree walker for modifying the AST.
208.      *
209.      * @param string $className
210.      * @psalm-param class-string<TreeWalker> $className
211.      *
212.      * @return void
213.      */
214.     public function addCustomTreeWalker($className)
215.     {
216.         $this->customTreeWalkers[] = $className;
217.     }
219.     /**
220.      * Gets the lexer used by the parser.
221.      *
222.      * @return Lexer
223.      */
224.     public function getLexer()
225.     {
226.         return $this->lexer;
227.     }
229.     /**
230.      * Gets the ParserResult that is being filled with information during parsing.
231.      *
232.      * @return ParserResult
233.      */
234.     public function getParserResult()
235.     {
236.         return $this->parserResult;
237.     }
239.     /**
240.      * Gets the EntityManager used by the parser.
241.      *
242.      * @return EntityManagerInterface
243.      */
244.     public function getEntityManager()
245.     {
246.         return $this->em;
247.     }
249.     /**
250.      * Parses and builds AST for the given Query.
251.      *
252.      * @return AST\SelectStatement|AST\UpdateStatement|AST\DeleteStatement
253.      */
254.     public function getAST()
255.     {
256.         // Parse & build AST
257.         $AST = $this->QueryLanguage();
259.         // Process any deferred validations of some nodes in the AST.
260.         // This also allows post-processing of the AST for modification purposes.
261.         $this->processDeferredIdentificationVariables();
263.         if ($this->deferredPartialObjectExpressions) {
264.             $this->processDeferredPartialObjectExpressions();
265.         }
267.         if ($this->deferredPathExpressions) {
268.             $this->processDeferredPathExpressions();
269.         }
271.         if ($this->deferredResultVariables) {
272.             $this->processDeferredResultVariables();
273.         }
275.         if ($this->deferredNewObjectExpressions) {
276.             $this->processDeferredNewObjectExpressions($AST);
277.         }
279.         $this->processRootEntityAliasSelected();
281.         // TODO: Is there a way to remove this? It may impact the mixed hydration resultset a lot!
282.         $this->fixIdentificationVariableOrder($AST);
284.         return $AST;
285.     }
287.     /**
288.      * Attempts to match the given token with the current lookahead token.
289.      *
290.      * If they match, updates the lookahead token; otherwise raises a syntax
291.      * error.
292.      *
293.      * @param Lexer::T_* $token The token type.
294.      *
295.      * @return void
296.      *
297.      * @throws QueryException If the tokens don't match.
298.      */
299.     public function match($token)
300.     {
301.         $lookaheadType = $this->lexer->lookahead->type ?? null;
303.         // Short-circuit on first condition, usually types match
304.         if ($lookaheadType === $token) {
305.             $this->lexer->moveNext();
307.             return;
308.         }
310.         // If parameter is not identifier (1-99) must be exact match
311.         if ($token < Lexer::T_IDENTIFIER) {
312.             $this->syntaxError($this->lexer->getLiteral($token));
313.         }
315.         // If parameter is keyword (200+) must be exact match
316.         if ($token > Lexer::T_IDENTIFIER) {
317.             $this->syntaxError($this->lexer->getLiteral($token));
318.         }
320.         // If parameter is T_IDENTIFIER, then matches T_IDENTIFIER (100) and keywords (200+)
321.         if ($token === Lexer::T_IDENTIFIER && $lookaheadType < Lexer::T_IDENTIFIER) {
322.             $this->syntaxError($this->lexer->getLiteral($token));
323.         }
325.         $this->lexer->moveNext();
326.     }
328.     /**
329.      * Frees this parser, enabling it to be reused.
330.      *
331.      * @param bool $deep     Whether to clean peek and reset errors.
332.      * @param int  $position Position to reset.
333.      *
334.      * @return void
335.      */
336.     public function free($deep = false, $position = 0)
337.     {
338.         // WARNING! Use this method with care. It resets the scanner!
339.         $this->lexer->resetPosition($position);
341.         // Deep = true cleans peek and also any previously defined errors
342.         if ($deep) {
343.             $this->lexer->resetPeek();
344.         }
346.         $this->lexer->token     = null;
347.         $this->lexer->lookahead = null;
348.     }
350.     /**
351.      * Parses a query string.
352.      *
353.      * @return ParserResult
354.      */
355.     public function parse()
356.     {
357.         $AST = $this->getAST();
359.         $customWalkers = $this->query->getHint(Query::HINT_CUSTOM_TREE_WALKERS);
360.         if ($customWalkers !== false) {
361.             $this->customTreeWalkers = $customWalkers;
362.         }
364.         $customOutputWalker = $this->query->getHint(Query::HINT_CUSTOM_OUTPUT_WALKER);
365.         if ($customOutputWalker !== false) {
366.             $this->customOutputWalker = $customOutputWalker;
367.         }
369.         // Run any custom tree walkers over the AST
370.         if ($this->customTreeWalkers) {
371.             $treeWalkerChain = new TreeWalkerChain($this->query, $this->parserResult, $this->queryComponents);
373.             foreach ($this->customTreeWalkers as $walker) {
374.                 $treeWalkerChain->addTreeWalker($walker);
375.             }
377.             switch (true) {
378.                 case $AST instanceof AST\UpdateStatement:
379.                     $treeWalkerChain->walkUpdateStatement($AST);
380.                     break;
382.                 case $AST instanceof AST\DeleteStatement:
383.                     $treeWalkerChain->walkDeleteStatement($AST);
384.                     break;
386.                 case $AST instanceof AST\SelectStatement:
387.                 default:
388.                     $treeWalkerChain->walkSelectStatement($AST);
389.             }
391.             $this->queryComponents = $treeWalkerChain->getQueryComponents();
392.         }
394.         $outputWalkerClass = $this->customOutputWalker ?: SqlWalker::class;
395.         $outputWalker      = new $outputWalkerClass($this->query, $this->parserResult, $this->queryComponents);
397.         // Assign an SQL executor to the parser result
398.         $this->parserResult->setSqlExecutor($outputWalker->getExecutor($AST));
400.         return $this->parserResult;
401.     }
403.     /**
404.      * Fixes order of identification variables.
405.      *
406.      * They have to appear in the select clause in the same order as the
407.      * declarations (from ... x join ... y join ... z ...) appear in the query
408.      * as the hydration process relies on that order for proper operation.
409.      *
410.      * @param AST\SelectStatement|AST\DeleteStatement|AST\UpdateStatement $AST
411.      */
412.     private function fixIdentificationVariableOrder(AST\Node $AST): void
413.     {
414.         if (count($this->identVariableExpressions) <= 1) {
415.             return;
416.         }
418.         assert($AST instanceof AST\SelectStatement);
420.         foreach ($this->queryComponents as $dqlAlias => $qComp) {
421.             if (! isset($this->identVariableExpressions[$dqlAlias])) {
422.                 continue;
423.             }
425.             $expr = $this->identVariableExpressions[$dqlAlias];
426.             $key  = array_search($expr, $AST->selectClause->selectExpressions, true);
428.             unset($AST->selectClause->selectExpressions[$key]);
430.             $AST->selectClause->selectExpressions[] = $expr;
431.         }
432.     }
434.     /**
435.      * Generates a new syntax error.
436.      *
437.      * @param string       $expected Expected string.
438.      * @param mixed[]|null $token    Got token.
439.      * @psalm-param DqlToken|null $token
440.      *
441.      * @return void
442.      * @psalm-return no-return
443.      *
444.      * @throws QueryException
445.      */
446.     public function syntaxError($expected = '', $token = null)
447.     {
448.         if ($token === null) {
449.             $token = $this->lexer->lookahead;
450.         }
452.         $tokenPos = $token->position ?? '-1';
454.         $message  = sprintf('line 0, col %d: Error: ', $tokenPos);
455.         $message .= $expected !== '' ? sprintf('Expected %s, got ', $expected) : 'Unexpected ';
456.         $message .= $this->lexer->lookahead === null ? 'end of string.' : sprintf("'%s'", $token->value);
458.         throw QueryException::syntaxError($message, QueryException::dqlError($this->query->getDQL() ?? ''));
459.     }
461.     /**
462.      * Generates a new semantical error.
463.      *
464.      * @param string       $message Optional message.
465.      * @param mixed[]|null $token   Optional token.
466.      * @psalm-param DqlToken|null $token
467.      *
468.      * @return void
469.      * @psalm-return no-return
470.      *
471.      * @throws QueryException
472.      */
473.     public function semanticalError($message = '', $token = null)
474.     {
475.         if ($token === null) {
476.             $token = $this->lexer->lookahead ?? new Token('fake token', 42, 0);
477.         }
479.         // Minimum exposed chars ahead of token
480.         $distance = 12;
482.         // Find a position of a final word to display in error string
483.         $dql    = $this->query->getDQL();
484.         $length = strlen($dql);
485.         $pos    = $token->position + $distance;
486.         $pos    = strpos($dql, ' ', $length > $pos ? $pos : $length);
487.         $length = $pos !== false ? $pos - $token->position : $distance;
489.         $tokenPos = $token->position > 0 ? $token->position : '-1';
490.         $tokenStr = substr($dql, $token->position, $length);
492.         // Building informative message
493.         $message = 'line 0, col ' . $tokenPos . " near '" . $tokenStr . "': Error: " . $message;
495.         throw QueryException::semanticalError($message, QueryException::dqlError($this->query->getDQL()));
496.     }
498.     /**
499.      * Peeks beyond the matched closing parenthesis and returns the first token after that one.
500.      *
501.      * @param bool $resetPeek Reset peek after finding the closing parenthesis.
502.      *
503.      * @return mixed[]
504.      * @psalm-return DqlToken|null
505.      */
506.     private function peekBeyondClosingParenthesis(bool $resetPeek = true)
507.     {
508.         $token        = $this->lexer->peek();
509.         $numUnmatched = 1;
511.         while ($numUnmatched > 0 && $token !== null) {
512.             switch ($token->type) {
513.                 case Lexer::T_OPEN_PARENTHESIS:
514.                     ++$numUnmatched;
515.                     break;
517.                 case Lexer::T_CLOSE_PARENTHESIS:
518.                     --$numUnmatched;
519.                     break;
521.                 default:
522.                     // Do nothing
523.             }
525.             $token = $this->lexer->peek();
526.         }
528.         if ($resetPeek) {
529.             $this->lexer->resetPeek();
530.         }
532.         return $token;
533.     }
535.     /**
536.      * Checks if the given token indicates a mathematical operator.
537.      *
538.      * @psalm-param DqlToken|null $token
539.      */
540.     private function isMathOperator($token): bool
541.     {
542.         return $token !== null && in_array($token->type, [Lexer::T_PLUS, Lexer::T_MINUS, Lexer::T_DIVIDE, Lexer::T_MULTIPLY], true);
543.     }
545.     /**
546.      * Checks if the next-next (after lookahead) token starts a function.
547.      *
548.      * @return bool TRUE if the next-next tokens start a function, FALSE otherwise.
549.      */
550.     private function isFunction(): bool
551.     {
552.         assert($this->lexer->lookahead !== null);
553.         $lookaheadType = $this->lexer->lookahead->type;
554.         $peek          = $this->lexer->peek();
556.         $this->lexer->resetPeek();
558.         return $lookaheadType >= Lexer::T_IDENTIFIER && $peek !== null && $peek->type === Lexer::T_OPEN_PARENTHESIS;
559.     }
561.     /**
562.      * Checks whether the given token type indicates an aggregate function.
563.      *
564.      * @psalm-param Lexer::T_* $tokenType
565.      *
566.      * @return bool TRUE if the token type is an aggregate function, FALSE otherwise.
567.      */
568.     private function isAggregateFunction(int $tokenType): bool
569.     {
570.         return in_array(
571.             $tokenType,
572.             [Lexer::T_AVG, Lexer::T_MIN, Lexer::T_MAX, Lexer::T_SUM, Lexer::T_COUNT],
573.             true
574.         );
575.     }
577.     /**
578.      * Checks whether the current lookahead token of the lexer has the type T_ALL, T_ANY or T_SOME.
579.      */
580.     private function isNextAllAnySome(): bool
581.     {
582.         assert($this->lexer->lookahead !== null);
584.         return in_array(
585.             $this->lexer->lookahead['type'],
586.             [Lexer::T_ALL, Lexer::T_ANY, Lexer::T_SOME],
587.             true
588.         );
589.     }
591.     /**
592.      * Validates that the given <tt>IdentificationVariable</tt> is semantically correct.
593.      * It must exist in query components list.
594.      */
595.     private function processDeferredIdentificationVariables(): void
596.     {
597.         foreach ($this->deferredIdentificationVariables as $deferredItem) {
598.             $identVariable = $deferredItem['expression'];
600.             // Check if IdentificationVariable exists in queryComponents
601.             if (! isset($this->queryComponents[$identVariable])) {
602.                 $this->semanticalError(
603.                     sprintf("'%s' is not defined.", $identVariable),
604.                     $deferredItem['token']
605.                 );
606.             }
608.             $qComp = $this->queryComponents[$identVariable];
610.             // Check if queryComponent points to an AbstractSchemaName or a ResultVariable
611.             if (! isset($qComp['metadata'])) {
612.                 $this->semanticalError(
613.                     sprintf("'%s' does not point to a Class.", $identVariable),
614.                     $deferredItem['token']
615.                 );
616.             }
618.             // Validate if identification variable nesting level is lower or equal than the current one
619.             if ($qComp['nestingLevel'] > $deferredItem['nestingLevel']) {
620.                 $this->semanticalError(
621.                     sprintf("'%s' is used outside the scope of its declaration.", $identVariable),
622.                     $deferredItem['token']
623.                 );
624.             }
625.         }
626.     }
628.     /**
629.      * Validates that the given <tt>NewObjectExpression</tt>.
630.      */
631.     private function processDeferredNewObjectExpressions(AST\SelectStatement $AST): void
632.     {
633.         foreach ($this->deferredNewObjectExpressions as $deferredItem) {
634.             $expression    = $deferredItem['expression'];
635.             $token         = $deferredItem['token'];
636.             $className     = $expression->className;
637.             $args          = $expression->args;
638.             $fromClassName = $AST->fromClause->identificationVariableDeclarations[0]->rangeVariableDeclaration->abstractSchemaName ?? null;
640.             // If the namespace is not given then assumes the first FROM entity namespace
641.             if (! str_contains($className, '\\') && ! class_exists($className) && is_string($fromClassName) && str_contains($fromClassName, '\\')) {
642.                 $namespace = substr($fromClassName, 0, strrpos($fromClassName, '\\'));
643.                 $fqcn      = $namespace . '\\' . $className;
645.                 if (class_exists($fqcn)) {
646.                     $expression->className = $fqcn;
647.                     $className             = $fqcn;
648.                 }
649.             }
651.             if (! class_exists($className)) {
652.                 $this->semanticalError(sprintf('Class "%s" is not defined.', $className), $token);
653.             }
655.             $class = new ReflectionClass($className);
657.             if (! $class->isInstantiable()) {
658.                 $this->semanticalError(sprintf('Class "%s" can not be instantiated.', $className), $token);
659.             }
661.             if ($class->getConstructor() === null) {
662.                 $this->semanticalError(sprintf('Class "%s" has not a valid constructor.', $className), $token);
663.             }
665.             if ($class->getConstructor()->getNumberOfRequiredParameters() > count($args)) {
666.                 $this->semanticalError(sprintf('Number of arguments does not match with "%s" constructor declaration.', $className), $token);
667.             }
668.         }
669.     }
671.     /**
672.      * Validates that the given <tt>PartialObjectExpression</tt> is semantically correct.
673.      * It must exist in query components list.
674.      */
675.     private function processDeferredPartialObjectExpressions(): void
676.     {
677.         foreach ($this->deferredPartialObjectExpressions as $deferredItem) {
678.             $expr  = $deferredItem['expression'];
679.             $class = $this->getMetadataForDqlAlias($expr->identificationVariable);
681.             foreach ($expr->partialFieldSet as $field) {
682.                 if (isset($class->fieldMappings[$field])) {
683.                     continue;
684.                 }
686.                 if (
687.                     isset($class->associationMappings[$field]) &&
688.                     $class->associationMappings[$field]['isOwningSide'] &&
689.                     $class->associationMappings[$field]['type'] & ClassMetadata::TO_ONE
690.                 ) {
691.                     continue;
692.                 }
694.                 $this->semanticalError(sprintf(
695.                     "There is no mapped field named '%s' on class %s.",
696.                     $field,
697.                     $class->name
698.                 ), $deferredItem['token']);
699.             }
701.             if (array_intersect($class->identifier, $expr->partialFieldSet) !== $class->identifier) {
702.                 $this->semanticalError(
703.                     'The partial field selection of class ' . $class->name . ' must contain the identifier.',
704.                     $deferredItem['token']
705.                 );
706.             }
707.         }
708.     }
710.     /**
711.      * Validates that the given <tt>ResultVariable</tt> is semantically correct.
712.      * It must exist in query components list.
713.      */
714.     private function processDeferredResultVariables(): void
715.     {
716.         foreach ($this->deferredResultVariables as $deferredItem) {
717.             $resultVariable = $deferredItem['expression'];
719.             // Check if ResultVariable exists in queryComponents
720.             if (! isset($this->queryComponents[$resultVariable])) {
721.                 $this->semanticalError(
722.                     sprintf("'%s' is not defined.", $resultVariable),
723.                     $deferredItem['token']
724.                 );
725.             }
727.             $qComp = $this->queryComponents[$resultVariable];
729.             // Check if queryComponent points to an AbstractSchemaName or a ResultVariable
730.             if (! isset($qComp['resultVariable'])) {
731.                 $this->semanticalError(
732.                     sprintf("'%s' does not point to a ResultVariable.", $resultVariable),
733.                     $deferredItem['token']
734.                 );
735.             }
737.             // Validate if identification variable nesting level is lower or equal than the current one
738.             if ($qComp['nestingLevel'] > $deferredItem['nestingLevel']) {
739.                 $this->semanticalError(
740.                     sprintf("'%s' is used outside the scope of its declaration.", $resultVariable),
741.                     $deferredItem['token']
742.                 );
743.             }
744.         }
745.     }
747.     /**
748.      * Validates that the given <tt>PathExpression</tt> is semantically correct for grammar rules:
749.      *
750.      * AssociationPathExpression             ::= CollectionValuedPathExpression | SingleValuedAssociationPathExpression
751.      * SingleValuedPathExpression            ::= StateFieldPathExpression | SingleValuedAssociationPathExpression
752.      * StateFieldPathExpression              ::= IdentificationVariable "." StateField
753.      * SingleValuedAssociationPathExpression ::= IdentificationVariable "." SingleValuedAssociationField
754.      * CollectionValuedPathExpression        ::= IdentificationVariable "." CollectionValuedAssociationField
755.      */
756.     private function processDeferredPathExpressions(): void
757.     {
758.         foreach ($this->deferredPathExpressions as $deferredItem) {
759.             $pathExpression = $deferredItem['expression'];
761.             $class = $this->getMetadataForDqlAlias($pathExpression->identificationVariable);
763.             $field = $pathExpression->field;
764.             if ($field === null) {
765.                 $field = $pathExpression->field = $class->identifier[0];
766.             }
768.             // Check if field or association exists
769.             if (! isset($class->associationMappings[$field]) && ! isset($class->fieldMappings[$field])) {
770.                 $this->semanticalError(
771.                     'Class ' . $class->name . ' has no field or association named ' . $field,
772.                     $deferredItem['token']
773.                 );
774.             }
776.             $fieldType = AST\PathExpression::TYPE_STATE_FIELD;
778.             if (isset($class->associationMappings[$field])) {
779.                 $assoc = $class->associationMappings[$field];
781.                 $fieldType = $assoc['type'] & ClassMetadata::TO_ONE
782.                     ? AST\PathExpression::TYPE_SINGLE_VALUED_ASSOCIATION
783.                     : AST\PathExpression::TYPE_COLLECTION_VALUED_ASSOCIATION;
784.             }
786.             // Validate if PathExpression is one of the expected types
787.             $expectedType = $pathExpression->expectedType;
789.             if (! ($expectedType & $fieldType)) {
790.                 // We need to recognize which was expected type(s)
791.                 $expectedStringTypes = [];
793.                 // Validate state field type
794.                 if ($expectedType & AST\PathExpression::TYPE_STATE_FIELD) {
795.                     $expectedStringTypes[] = 'StateFieldPathExpression';
796.                 }
798.                 // Validate single valued association (*-to-one)
799.                 if ($expectedType & AST\PathExpression::TYPE_SINGLE_VALUED_ASSOCIATION) {
800.                     $expectedStringTypes[] = 'SingleValuedAssociationField';
801.                 }
803.                 // Validate single valued association (*-to-many)
804.                 if ($expectedType & AST\PathExpression::TYPE_COLLECTION_VALUED_ASSOCIATION) {
805.                     $expectedStringTypes[] = 'CollectionValuedAssociationField';
806.                 }
808.                 // Build the error message
809.                 $semanticalError  = 'Invalid PathExpression. ';
810.                 $semanticalError .= count($expectedStringTypes) === 1
811.                     ? 'Must be a ' . $expectedStringTypes[0] . '.'
812.                     : implode(' or ', $expectedStringTypes) . ' expected.';
814.                 $this->semanticalError($semanticalError, $deferredItem['token']);
815.             }
817.             // We need to force the type in PathExpression
818.             $pathExpression->type = $fieldType;
819.         }
820.     }
822.     private function processRootEntityAliasSelected(): void
823.     {
824.         if (! count($this->identVariableExpressions)) {
825.             return;
826.         }
828.         foreach ($this->identVariableExpressions as $dqlAlias => $expr) {
829.             if (isset($this->queryComponents[$dqlAlias]) && ! isset($this->queryComponents[$dqlAlias]['parent'])) {
830.                 return;
831.             }
832.         }
834.         $this->semanticalError('Cannot select entity through identification variables without choosing at least one root entity alias.');
835.     }
837.     /**
838.      * QueryLanguage ::= SelectStatement | UpdateStatement | DeleteStatement
839.      *
840.      * @return AST\SelectStatement|AST\UpdateStatement|AST\DeleteStatement
841.      */
842.     public function QueryLanguage()
843.     {
844.         $statement = null;
846.         $this->lexer->moveNext();
848.         switch ($this->lexer->lookahead->type ?? null) {
849.             case Lexer::T_SELECT:
850.                 $statement = $this->SelectStatement();
851.                 break;
853.             case Lexer::T_UPDATE:
854.                 $statement = $this->UpdateStatement();
855.                 break;
857.             case Lexer::T_DELETE:
858.                 $statement = $this->DeleteStatement();
859.                 break;
861.             default:
862.                 $this->syntaxError('SELECT, UPDATE or DELETE');
863.                 break;
864.         }
866.         // Check for end of string
867.         if ($this->lexer->lookahead !== null) {
868.             $this->syntaxError('end of string');
869.         }
871.         return $statement;
872.     }
874.     /**
875.      * SelectStatement ::= SelectClause FromClause [WhereClause] [GroupByClause] [HavingClause] [OrderByClause]
876.      *
877.      * @return AST\SelectStatement
878.      */
879.     public function SelectStatement()
880.     {
881.         $selectStatement = new AST\SelectStatement($this->SelectClause(), $this->FromClause());
883.         $selectStatement->whereClause   = $this->lexer->isNextToken(Lexer::T_WHERE) ? $this->WhereClause() : null;
884.         $selectStatement->groupByClause = $this->lexer->isNextToken(Lexer::T_GROUP) ? $this->GroupByClause() : null;
885.         $selectStatement->havingClause  = $this->lexer->isNextToken(Lexer::T_HAVING) ? $this->HavingClause() : null;
886.         $selectStatement->orderByClause = $this->lexer->isNextToken(Lexer::T_ORDER) ? $this->OrderByClause() : null;
888.         return $selectStatement;
889.     }
891.     /**
892.      * UpdateStatement ::= UpdateClause [WhereClause]
893.      *
894.      * @return AST\UpdateStatement
895.      */
896.     public function UpdateStatement()
897.     {
898.         $updateStatement = new AST\UpdateStatement($this->UpdateClause());
900.         $updateStatement->whereClause = $this->lexer->isNextToken(Lexer::T_WHERE) ? $this->WhereClause() : null;
902.         return $updateStatement;
903.     }
905.     /**
906.      * DeleteStatement ::= DeleteClause [WhereClause]
907.      *
908.      * @return AST\DeleteStatement
909.      */
910.     public function DeleteStatement()
911.     {
912.         $deleteStatement = new AST\DeleteStatement($this->DeleteClause());
914.         $deleteStatement->whereClause = $this->lexer->isNextToken(Lexer::T_WHERE) ? $this->WhereClause() : null;
916.         return $deleteStatement;
917.     }
919.     /**
920.      * IdentificationVariable ::= identifier
921.      *
922.      * @return string
923.      */
924.     public function IdentificationVariable()
925.     {
926.         $this->match(Lexer::T_IDENTIFIER);
928.         assert($this->lexer->token !== null);
929.         $identVariable = $this->lexer->token->value;
931.         $this->deferredIdentificationVariables[] = [
932.             'expression'   => $identVariable,
933.             'nestingLevel' => $this->nestingLevel,
934.             'token'        => $this->lexer->token,
935.         ];
937.         return $identVariable;
938.     }
940.     /**
941.      * AliasIdentificationVariable = identifier
942.      *
943.      * @return string
944.      */
945.     public function AliasIdentificationVariable()
946.     {
947.         $this->match(Lexer::T_IDENTIFIER);
949.         assert($this->lexer->token !== null);
950.         $aliasIdentVariable = $this->lexer->token->value;
951.         $exists             = isset($this->queryComponents[$aliasIdentVariable]);
953.         if ($exists) {
954.             $this->semanticalError(
955.                 sprintf("'%s' is already defined.", $aliasIdentVariable),
956.                 $this->lexer->token
957.             );
958.         }
960.         return $aliasIdentVariable;
961.     }
963.     /**
964.      * AbstractSchemaName ::= fully_qualified_name | aliased_name | identifier
965.      *
966.      * @return string
967.      */
968.     public function AbstractSchemaName()
969.     {
970.         if ($this->lexer->isNextToken(Lexer::T_FULLY_QUALIFIED_NAME)) {
971.             $this->match(Lexer::T_FULLY_QUALIFIED_NAME);
972.             assert($this->lexer->token !== null);
974.             return $this->lexer->token->value;
975.         }
977.         if ($this->lexer->isNextToken(Lexer::T_IDENTIFIER)) {
978.             $this->match(Lexer::T_IDENTIFIER);
979.             assert($this->lexer->token !== null);
981.             return $this->lexer->token['value'];
982.         }
984.         $this->match(Lexer::T_ALIASED_NAME);
986.         assert($this->lexer->token !== null);
988.         Deprecation::trigger(
989.             'doctrine/orm',
990.             'https://github.com/doctrine/orm/issues/8818',
991.             'Short namespace aliases such as "%s" are deprecated and will be removed in Doctrine ORM 3.0.',
992.             $this->lexer->token['value']
993.         );
995.         [$namespaceAlias, $simpleClassName] = explode(':', $this->lexer->token['value']);
997.         return $this->em->getConfiguration()->getEntityNamespace($namespaceAlias) . '\\' . $simpleClassName;
998.     }
1000.     /**
1001.      * Validates an AbstractSchemaName, making sure the class exists.
1002.      *
1003.      * @param string $schemaName The name to validate.
1004.      *
1005.      * @throws QueryException if the name does not exist.
1006.      */
1007.     private function validateAbstractSchemaName(string $schemaName): void
1008.     {
1009.         assert($this->lexer->token !== null);
1010.         if (! (class_exists($schemaName, true) || interface_exists($schemaName, true))) {
1011.             $this->semanticalError(
1012.                 sprintf("Class '%s' is not defined.", $schemaName),
1013.                 $this->lexer->token
1014.             );
1015.         }
1016.     }
1018.     /**
1019.      * AliasResultVariable ::= identifier
1020.      *
1021.      * @return string
1022.      */
1023.     public function AliasResultVariable()
1024.     {
1025.         $this->match(Lexer::T_IDENTIFIER);
1027.         assert($this->lexer->token !== null);
1028.         $resultVariable = $this->lexer->token->value;
1029.         $exists         = isset($this->queryComponents[$resultVariable]);
1031.         if ($exists) {
1032.             $this->semanticalError(
1033.                 sprintf("'%s' is already defined.", $resultVariable),
1034.                 $this->lexer->token
1035.             );
1036.         }
1038.         return $resultVariable;
1039.     }
1041.     /**
1042.      * ResultVariable ::= identifier
1043.      *
1044.      * @return string
1045.      */
1046.     public function ResultVariable()
1047.     {
1048.         $this->match(Lexer::T_IDENTIFIER);
1050.         assert($this->lexer->token !== null);
1051.         $resultVariable = $this->lexer->token->value;
1053.         // Defer ResultVariable validation
1054.         $this->deferredResultVariables[] = [
1055.             'expression'   => $resultVariable,
1056.             'nestingLevel' => $this->nestingLevel,
1057.             'token'        => $this->lexer->token,
1058.         ];
1060.         return $resultVariable;
1061.     }
1063.     /**
1064.      * JoinAssociationPathExpression ::= IdentificationVariable "." (CollectionValuedAssociationField | SingleValuedAssociationField)
1065.      *
1066.      * @return AST\JoinAssociationPathExpression
1067.      */
1068.     public function JoinAssociationPathExpression()
1069.     {
1070.         $identVariable = $this->IdentificationVariable();
1072.         if (! isset($this->queryComponents[$identVariable])) {
1073.             $this->semanticalError(
1074.                 'Identification Variable ' . $identVariable . ' used in join path expression but was not defined before.'
1075.             );
1076.         }
1078.         $this->match(Lexer::T_DOT);
1079.         $this->match(Lexer::T_IDENTIFIER);
1081.         assert($this->lexer->token !== null);
1082.         $field = $this->lexer->token->value;
1084.         // Validate association field
1085.         $class = $this->getMetadataForDqlAlias($identVariable);
1087.         if (! $class->hasAssociation($field)) {
1088.             $this->semanticalError('Class ' . $class->name . ' has no association named ' . $field);
1089.         }
1091.         return new AST\JoinAssociationPathExpression($identVariable, $field);
1092.     }
1094.     /**
1095.      * Parses an arbitrary path expression and defers semantical validation
1096.      * based on expected types.
1097.      *
1098.      * PathExpression ::= IdentificationVariable {"." identifier}*
1099.      *
1100.      * @param int $expectedTypes
1101.      * @psalm-param int-mask-of<AST\PathExpression::TYPE_*> $expectedTypes
1102.      *
1103.      * @return AST\PathExpression
1104.      */
1105.     public function PathExpression($expectedTypes)
1106.     {
1107.         $identVariable = $this->IdentificationVariable();
1108.         $field         = null;
1110.         assert($this->lexer->token !== null);
1111.         if ($this->lexer->isNextToken(Lexer::T_DOT)) {
1112.             $this->match(Lexer::T_DOT);
1113.             $this->match(Lexer::T_IDENTIFIER);
1115.             $field = $this->lexer->token->value;
1117.             while ($this->lexer->isNextToken(Lexer::T_DOT)) {
1118.                 $this->match(Lexer::T_DOT);
1119.                 $this->match(Lexer::T_IDENTIFIER);
1120.                 $field .= '.' . $this->lexer->token->value;
1121.             }
1122.         }
1124.         // Creating AST node
1125.         $pathExpr = new AST\PathExpression($expectedTypes, $identVariable, $field);
1127.         // Defer PathExpression validation if requested to be deferred
1128.         $this->deferredPathExpressions[] = [
1129.             'expression'   => $pathExpr,
1130.             'nestingLevel' => $this->nestingLevel,
1131.             'token'        => $this->lexer->token,
1132.         ];
1134.         return $pathExpr;
1135.     }
1137.     /**
1138.      * AssociationPathExpression ::= CollectionValuedPathExpression | SingleValuedAssociationPathExpression
1139.      *
1140.      * @return AST\PathExpression
1141.      */
1142.     public function AssociationPathExpression()
1143.     {
1144.         return $this->PathExpression(
1145.             AST\PathExpression::TYPE_SINGLE_VALUED_ASSOCIATION |
1146.             AST\PathExpression::TYPE_COLLECTION_VALUED_ASSOCIATION
1147.         );
1148.     }
1150.     /**
1151.      * SingleValuedPathExpression ::= StateFieldPathExpression | SingleValuedAssociationPathExpression
1152.      *
1153.      * @return AST\PathExpression
1154.      */
1155.     public function SingleValuedPathExpression()
1156.     {
1157.         return $this->PathExpression(
1158.             AST\PathExpression::TYPE_STATE_FIELD |
1159.             AST\PathExpression::TYPE_SINGLE_VALUED_ASSOCIATION
1160.         );
1161.     }
1163.     /**
1164.      * StateFieldPathExpression ::= IdentificationVariable "." StateField
1165.      *
1166.      * @return AST\PathExpression
1167.      */
1168.     public function StateFieldPathExpression()
1169.     {
1170.         return $this->PathExpression(AST\PathExpression::TYPE_STATE_FIELD);
1171.     }
1173.     /**
1174.      * SingleValuedAssociationPathExpression ::= IdentificationVariable "." SingleValuedAssociationField
1175.      *
1176.      * @return AST\PathExpression
1177.      */
1178.     public function SingleValuedAssociationPathExpression()
1179.     {
1180.         return $this->PathExpression(AST\PathExpression::TYPE_SINGLE_VALUED_ASSOCIATION);
1181.     }
1183.     /**
1184.      * CollectionValuedPathExpression ::= IdentificationVariable "." CollectionValuedAssociationField
1185.      *
1186.      * @return AST\PathExpression
1187.      */
1188.     public function CollectionValuedPathExpression()
1189.     {
1190.         return $this->PathExpression(AST\PathExpression::TYPE_COLLECTION_VALUED_ASSOCIATION);
1191.     }
1193.     /**
1194.      * SelectClause ::= "SELECT" ["DISTINCT"] SelectExpression {"," SelectExpression}
1195.      *
1196.      * @return AST\SelectClause
1197.      */
1198.     public function SelectClause()
1199.     {
1200.         $isDistinct = false;
1201.         $this->match(Lexer::T_SELECT);
1203.         // Check for DISTINCT
1204.         if ($this->lexer->isNextToken(Lexer::T_DISTINCT)) {
1205.             $this->match(Lexer::T_DISTINCT);
1207.             $isDistinct = true;
1208.         }
1210.         // Process SelectExpressions (1..N)
1211.         $selectExpressions   = [];
1212.         $selectExpressions[] = $this->SelectExpression();
1214.         while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
1215.             $this->match(Lexer::T_COMMA);
1217.             $selectExpressions[] = $this->SelectExpression();
1218.         }
1220.         return new AST\SelectClause($selectExpressions, $isDistinct);
1221.     }
1223.     /**
1224.      * SimpleSelectClause ::= "SELECT" ["DISTINCT"] SimpleSelectExpression
1225.      *
1226.      * @return AST\SimpleSelectClause
1227.      */
1228.     public function SimpleSelectClause()
1229.     {
1230.         $isDistinct = false;
1231.         $this->match(Lexer::T_SELECT);
1233.         if ($this->lexer->isNextToken(Lexer::T_DISTINCT)) {
1234.             $this->match(Lexer::T_DISTINCT);
1236.             $isDistinct = true;
1237.         }
1239.         return new AST\SimpleSelectClause($this->SimpleSelectExpression(), $isDistinct);
1240.     }
1242.     /**
1243.      * UpdateClause ::= "UPDATE" AbstractSchemaName ["AS"] AliasIdentificationVariable "SET" UpdateItem {"," UpdateItem}*
1244.      *
1245.      * @return AST\UpdateClause
1246.      */
1247.     public function UpdateClause()
1248.     {
1249.         $this->match(Lexer::T_UPDATE);
1250.         assert($this->lexer->lookahead !== null);
1252.         $token              = $this->lexer->lookahead;
1253.         $abstractSchemaName = $this->AbstractSchemaName();
1255.         $this->validateAbstractSchemaName($abstractSchemaName);
1257.         if ($this->lexer->isNextToken(Lexer::T_AS)) {
1258.             $this->match(Lexer::T_AS);
1259.         }
1261.         $aliasIdentificationVariable = $this->AliasIdentificationVariable();
1263.         $class = $this->em->getClassMetadata($abstractSchemaName);
1265.         // Building queryComponent
1266.         $queryComponent = [
1267.             'metadata'     => $class,
1268.             'parent'       => null,
1269.             'relation'     => null,
1270.             'map'          => null,
1271.             'nestingLevel' => $this->nestingLevel,
1272.             'token'        => $token,
1273.         ];
1275.         $this->queryComponents[$aliasIdentificationVariable] = $queryComponent;
1277.         $this->match(Lexer::T_SET);
1279.         $updateItems   = [];
1280.         $updateItems[] = $this->UpdateItem();
1282.         while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
1283.             $this->match(Lexer::T_COMMA);
1285.             $updateItems[] = $this->UpdateItem();
1286.         }
1288.         $updateClause                              = new AST\UpdateClause($abstractSchemaName, $updateItems);
1289.         $updateClause->aliasIdentificationVariable = $aliasIdentificationVariable;
1291.         return $updateClause;
1292.     }
1294.     /**
1295.      * DeleteClause ::= "DELETE" ["FROM"] AbstractSchemaName ["AS"] AliasIdentificationVariable
1296.      *
1297.      * @return AST\DeleteClause
1298.      */
1299.     public function DeleteClause()
1300.     {
1301.         $this->match(Lexer::T_DELETE);
1303.         if ($this->lexer->isNextToken(Lexer::T_FROM)) {
1304.             $this->match(Lexer::T_FROM);
1305.         }
1307.         assert($this->lexer->lookahead !== null);
1308.         $token              = $this->lexer->lookahead;
1309.         $abstractSchemaName = $this->AbstractSchemaName();
1311.         $this->validateAbstractSchemaName($abstractSchemaName);
1313.         $deleteClause = new AST\DeleteClause($abstractSchemaName);
1315.         if ($this->lexer->isNextToken(Lexer::T_AS)) {
1316.             $this->match(Lexer::T_AS);
1317.         }
1319.         $aliasIdentificationVariable = $this->lexer->isNextToken(Lexer::T_IDENTIFIER)
1320.             ? $this->AliasIdentificationVariable()
1321.             : 'alias_should_have_been_set';
1323.         $deleteClause->aliasIdentificationVariable = $aliasIdentificationVariable;
1324.         $class                                     = $this->em->getClassMetadata($deleteClause->abstractSchemaName);
1326.         // Building queryComponent
1327.         $queryComponent = [
1328.             'metadata'     => $class,
1329.             'parent'       => null,
1330.             'relation'     => null,
1331.             'map'          => null,
1332.             'nestingLevel' => $this->nestingLevel,
1333.             'token'        => $token,
1334.         ];
1336.         $this->queryComponents[$aliasIdentificationVariable] = $queryComponent;
1338.         return $deleteClause;
1339.     }
1341.     /**
1342.      * FromClause ::= "FROM" IdentificationVariableDeclaration {"," IdentificationVariableDeclaration}*
1343.      *
1344.      * @return AST\FromClause
1345.      */
1346.     public function FromClause()
1347.     {
1348.         $this->match(Lexer::T_FROM);
1350.         $identificationVariableDeclarations   = [];
1351.         $identificationVariableDeclarations[] = $this->IdentificationVariableDeclaration();
1353.         while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
1354.             $this->match(Lexer::T_COMMA);
1356.             $identificationVariableDeclarations[] = $this->IdentificationVariableDeclaration();
1357.         }
1359.         return new AST\FromClause($identificationVariableDeclarations);
1360.     }
1362.     /**
1363.      * SubselectFromClause ::= "FROM" SubselectIdentificationVariableDeclaration {"," SubselectIdentificationVariableDeclaration}*
1364.      *
1365.      * @return AST\SubselectFromClause
1366.      */
1367.     public function SubselectFromClause()
1368.     {
1369.         $this->match(Lexer::T_FROM);
1371.         $identificationVariables   = [];
1372.         $identificationVariables[] = $this->SubselectIdentificationVariableDeclaration();
1374.         while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
1375.             $this->match(Lexer::T_COMMA);
1377.             $identificationVariables[] = $this->SubselectIdentificationVariableDeclaration();
1378.         }
1380.         return new AST\SubselectFromClause($identificationVariables);
1381.     }
1383.     /**
1384.      * WhereClause ::= "WHERE" ConditionalExpression
1385.      *
1386.      * @return AST\WhereClause
1387.      */
1388.     public function WhereClause()
1389.     {
1390.         $this->match(Lexer::T_WHERE);
1392.         return new AST\WhereClause($this->ConditionalExpression());
1393.     }
1395.     /**
1396.      * HavingClause ::= "HAVING" ConditionalExpression
1397.      *
1398.      * @return AST\HavingClause
1399.      */
1400.     public function HavingClause()
1401.     {
1402.         $this->match(Lexer::T_HAVING);
1404.         return new AST\HavingClause($this->ConditionalExpression());
1405.     }
1407.     /**
1408.      * GroupByClause ::= "GROUP" "BY" GroupByItem {"," GroupByItem}*
1409.      *
1410.      * @return AST\GroupByClause
1411.      */
1412.     public function GroupByClause()
1413.     {
1414.         $this->match(Lexer::T_GROUP);
1415.         $this->match(Lexer::T_BY);
1417.         $groupByItems = [$this->GroupByItem()];
1419.         while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
1420.             $this->match(Lexer::T_COMMA);
1422.             $groupByItems[] = $this->GroupByItem();
1423.         }
1425.         return new AST\GroupByClause($groupByItems);
1426.     }
1428.     /**
1429.      * OrderByClause ::= "ORDER" "BY" OrderByItem {"," OrderByItem}*
1430.      *
1431.      * @return AST\OrderByClause
1432.      */
1433.     public function OrderByClause()
1434.     {
1435.         $this->match(Lexer::T_ORDER);
1436.         $this->match(Lexer::T_BY);
1438.         $orderByItems   = [];
1439.         $orderByItems[] = $this->OrderByItem();
1441.         while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
1442.             $this->match(Lexer::T_COMMA);
1444.             $orderByItems[] = $this->OrderByItem();
1445.         }
1447.         return new AST\OrderByClause($orderByItems);
1448.     }
1450.     /**
1451.      * Subselect ::= SimpleSelectClause SubselectFromClause [WhereClause] [GroupByClause] [HavingClause] [OrderByClause]
1452.      *
1453.      * @return AST\Subselect
1454.      */
1455.     public function Subselect()
1456.     {
1457.         // Increase query nesting level
1458.         $this->nestingLevel++;
1460.         $subselect = new AST\Subselect($this->SimpleSelectClause(), $this->SubselectFromClause());
1462.         $subselect->whereClause   = $this->lexer->isNextToken(Lexer::T_WHERE) ? $this->WhereClause() : null;
1463.         $subselect->groupByClause = $this->lexer->isNextToken(Lexer::T_GROUP) ? $this->GroupByClause() : null;
1464.         $subselect->havingClause  = $this->lexer->isNextToken(Lexer::T_HAVING) ? $this->HavingClause() : null;
1465.         $subselect->orderByClause = $this->lexer->isNextToken(Lexer::T_ORDER) ? $this->OrderByClause() : null;
1467.         // Decrease query nesting level
1468.         $this->nestingLevel--;
1470.         return $subselect;
1471.     }
1473.     /**
1474.      * UpdateItem ::= SingleValuedPathExpression "=" NewValue
1475.      *
1476.      * @return AST\UpdateItem
1477.      */
1478.     public function UpdateItem()
1479.     {
1480.         $pathExpr = $this->SingleValuedPathExpression();
1482.         $this->match(Lexer::T_EQUALS);
1484.         return new AST\UpdateItem($pathExpr, $this->NewValue());
1485.     }
1487.     /**
1488.      * GroupByItem ::= IdentificationVariable | ResultVariable | SingleValuedPathExpression
1489.      *
1490.      * @return string|AST\PathExpression
1491.      */
1492.     public function GroupByItem()
1493.     {
1494.         // We need to check if we are in a IdentificationVariable or SingleValuedPathExpression
1495.         $glimpse = $this->lexer->glimpse();
1497.         if ($glimpse !== null && $glimpse->type === Lexer::T_DOT) {
1498.             return $this->SingleValuedPathExpression();
1499.         }
1501.         assert($this->lexer->lookahead !== null);
1502.         // Still need to decide between IdentificationVariable or ResultVariable
1503.         $lookaheadValue = $this->lexer->lookahead->value;
1505.         if (! isset($this->queryComponents[$lookaheadValue])) {
1506.             $this->semanticalError('Cannot group by undefined identification or result variable.');
1507.         }
1509.         return isset($this->queryComponents[$lookaheadValue]['metadata'])
1510.             ? $this->IdentificationVariable()
1511.             : $this->ResultVariable();
1512.     }
1514.     /**
1515.      * OrderByItem ::= (
1516.      *      SimpleArithmeticExpression | SingleValuedPathExpression | CaseExpression |
1517.      *      ScalarExpression | ResultVariable | FunctionDeclaration
1518.      * ) ["ASC" | "DESC"]
1519.      *
1520.      * @return AST\OrderByItem
1521.      */
1522.     public function OrderByItem()
1523.     {
1524.         $this->lexer->peek(); // lookahead => '.'
1525.         $this->lexer->peek(); // lookahead => token after '.'
1527.         $peek = $this->lexer->peek(); // lookahead => token after the token after the '.'
1529.         $this->lexer->resetPeek();
1531.         $glimpse = $this->lexer->glimpse();
1533.         assert($this->lexer->lookahead !== null);
1534.         switch (true) {
1535.             case $this->isMathOperator($peek):
1536.                 $expr = $this->SimpleArithmeticExpression();
1537.                 break;
1539.             case $glimpse !== null && $glimpse->type === Lexer::T_DOT:
1540.                 $expr = $this->SingleValuedPathExpression();
1541.                 break;
1543.             case $this->lexer->peek() && $this->isMathOperator($this->peekBeyondClosingParenthesis()):
1544.                 $expr = $this->ScalarExpression();
1545.                 break;
1547.             case $this->lexer->lookahead->type === Lexer::T_CASE:
1548.                 $expr = $this->CaseExpression();
1549.                 break;
1551.             case $this->isFunction():
1552.                 $expr = $this->FunctionDeclaration();
1553.                 break;
1555.             default:
1556.                 $expr = $this->ResultVariable();
1557.                 break;
1558.         }
1560.         $type = 'ASC';
1561.         $item = new AST\OrderByItem($expr);
1563.         switch (true) {
1564.             case $this->lexer->isNextToken(Lexer::T_DESC):
1565.                 $this->match(Lexer::T_DESC);
1566.                 $type = 'DESC';
1567.                 break;
1569.             case $this->lexer->isNextToken(Lexer::T_ASC):
1570.                 $this->match(Lexer::T_ASC);
1571.                 break;
1573.             default:
1574.                 // Do nothing
1575.         }
1577.         $item->type = $type;
1579.         return $item;
1580.     }
1582.     /**
1583.      * NewValue ::= SimpleArithmeticExpression | StringPrimary | DatetimePrimary | BooleanPrimary |
1584.      *      EnumPrimary | SimpleEntityExpression | "NULL"
1585.      *
1586.      * NOTE: Since it is not possible to correctly recognize individual types, here is the full
1587.      * grammar that needs to be supported:
1588.      *
1589.      * NewValue ::= SimpleArithmeticExpression | "NULL"
1590.      *
1591.      * SimpleArithmeticExpression covers all *Primary grammar rules and also SimpleEntityExpression
1592.      *
1593.      * @return AST\ArithmeticExpression|AST\InputParameter|null
1594.      */
1595.     public function NewValue()
1596.     {
1597.         if ($this->lexer->isNextToken(Lexer::T_NULL)) {
1598.             $this->match(Lexer::T_NULL);
1600.             return null;
1601.         }
1603.         if ($this->lexer->isNextToken(Lexer::T_INPUT_PARAMETER)) {
1604.             $this->match(Lexer::T_INPUT_PARAMETER);
1605.             assert($this->lexer->token !== null);
1607.             return new AST\InputParameter($this->lexer->token->value);
1608.         }
1610.         return $this->ArithmeticExpression();
1611.     }
1613.     /**
1614.      * IdentificationVariableDeclaration ::= RangeVariableDeclaration [IndexBy] {Join}*
1615.      *
1616.      * @return AST\IdentificationVariableDeclaration
1617.      */
1618.     public function IdentificationVariableDeclaration()
1619.     {
1620.         $joins                    = [];
1621.         $rangeVariableDeclaration = $this->RangeVariableDeclaration();
1622.         $indexBy                  = $this->lexer->isNextToken(Lexer::T_INDEX)
1623.             ? $this->IndexBy()
1624.             : null;
1626.         $rangeVariableDeclaration->isRoot = true;
1628.         while (
1629.             $this->lexer->isNextToken(Lexer::T_LEFT) ||
1630.             $this->lexer->isNextToken(Lexer::T_INNER) ||
1631.             $this->lexer->isNextToken(Lexer::T_JOIN)
1632.         ) {
1633.             $joins[] = $this->Join();
1634.         }
1636.         return new AST\IdentificationVariableDeclaration(
1637.             $rangeVariableDeclaration,
1638.             $indexBy,
1639.             $joins
1640.         );
1641.     }
1643.     /**
1644.      * SubselectIdentificationVariableDeclaration ::= IdentificationVariableDeclaration
1645.      *
1646.      * {Internal note: WARNING: Solution is harder than a bare implementation.
1647.      * Desired EBNF support:
1648.      *
1649.      * SubselectIdentificationVariableDeclaration ::= IdentificationVariableDeclaration | (AssociationPathExpression ["AS"] AliasIdentificationVariable)
1650.      *
1651.      * It demands that entire SQL generation to become programmatical. This is
1652.      * needed because association based subselect requires "WHERE" conditional
1653.      * expressions to be injected, but there is no scope to do that. Only scope
1654.      * accessible is "FROM", prohibiting an easy implementation without larger
1655.      * changes.}
1656.      *
1657.      * @return AST\IdentificationVariableDeclaration
1658.      */
1659.     public function SubselectIdentificationVariableDeclaration()
1660.     {
1661.         /*
1662.         NOT YET IMPLEMENTED!
1664.         $glimpse = $this->lexer->glimpse();
1666.         if ($glimpse->type == Lexer::T_DOT) {
1667.             $associationPathExpression = $this->AssociationPathExpression();
1669.             if ($this->lexer->isNextToken(Lexer::T_AS)) {
1670.                 $this->match(Lexer::T_AS);
1671.             }
1673.             $aliasIdentificationVariable = $this->AliasIdentificationVariable();
1674.             $identificationVariable      = $associationPathExpression->identificationVariable;
1675.             $field                       = $associationPathExpression->associationField;
1677.             $class       = $this->queryComponents[$identificationVariable]['metadata'];
1678.             $targetClass = $this->em->getClassMetadata($class->associationMappings[$field]['targetEntity']);
1680.             // Building queryComponent
1681.             $joinQueryComponent = array(
1682.                 'metadata'     => $targetClass,
1683.                 'parent'       => $identificationVariable,
1684.                 'relation'     => $class->getAssociationMapping($field),
1685.                 'map'          => null,
1686.                 'nestingLevel' => $this->nestingLevel,
1687.                 'token'        => $this->lexer->lookahead
1688.             );
1690.             $this->queryComponents[$aliasIdentificationVariable] = $joinQueryComponent;
1692.             return new AST\SubselectIdentificationVariableDeclaration(
1693.                 $associationPathExpression, $aliasIdentificationVariable
1694.             );
1695.         }
1696.         */
1698.         return $this->IdentificationVariableDeclaration();
1699.     }
1701.     /**
1702.      * Join ::= ["LEFT" ["OUTER"] | "INNER"] "JOIN"
1703.      *          (JoinAssociationDeclaration | RangeVariableDeclaration)
1704.      *          ["WITH" ConditionalExpression]
1705.      *
1706.      * @return AST\Join
1707.      */
1708.     public function Join()
1709.     {
1710.         // Check Join type
1711.         $joinType = AST\Join::JOIN_TYPE_INNER;
1713.         switch (true) {
1714.             case $this->lexer->isNextToken(Lexer::T_LEFT):
1715.                 $this->match(Lexer::T_LEFT);
1717.                 $joinType = AST\Join::JOIN_TYPE_LEFT;
1719.                 // Possible LEFT OUTER join
1720.                 if ($this->lexer->isNextToken(Lexer::T_OUTER)) {
1721.                     $this->match(Lexer::T_OUTER);
1723.                     $joinType = AST\Join::JOIN_TYPE_LEFTOUTER;
1724.                 }
1726.                 break;
1728.             case $this->lexer->isNextToken(Lexer::T_INNER):
1729.                 $this->match(Lexer::T_INNER);
1730.                 break;
1732.             default:
1733.                 // Do nothing
1734.         }
1736.         $this->match(Lexer::T_JOIN);
1738.         $next = $this->lexer->glimpse();
1739.         assert($next !== null);
1740.         $joinDeclaration = $next->type === Lexer::T_DOT ? $this->JoinAssociationDeclaration() : $this->RangeVariableDeclaration();
1741.         $adhocConditions = $this->lexer->isNextToken(Lexer::T_WITH);
1742.         $join            = new AST\Join($joinType, $joinDeclaration);
1744.         // Describe non-root join declaration
1745.         if ($joinDeclaration instanceof AST\RangeVariableDeclaration) {
1746.             $joinDeclaration->isRoot = false;
1747.         }
1749.         // Check for ad-hoc Join conditions
1750.         if ($adhocConditions) {
1751.             $this->match(Lexer::T_WITH);
1753.             $join->conditionalExpression = $this->ConditionalExpression();
1754.         }
1756.         return $join;
1757.     }
1759.     /**
1760.      * RangeVariableDeclaration ::= AbstractSchemaName ["AS"] AliasIdentificationVariable
1761.      *
1762.      * @return AST\RangeVariableDeclaration
1763.      *
1764.      * @throws QueryException
1765.      */
1766.     public function RangeVariableDeclaration()
1767.     {
1768.         if ($this->lexer->isNextToken(Lexer::T_OPEN_PARENTHESIS) && $this->lexer->glimpse()->type === Lexer::T_SELECT) {
1769.             $this->semanticalError('Subquery is not supported here', $this->lexer->token);
1770.         }
1772.         $abstractSchemaName = $this->AbstractSchemaName();
1774.         $this->validateAbstractSchemaName($abstractSchemaName);
1776.         if ($this->lexer->isNextToken(Lexer::T_AS)) {
1777.             $this->match(Lexer::T_AS);
1778.         }
1780.         assert($this->lexer->lookahead !== null);
1781.         $token                       = $this->lexer->lookahead;
1782.         $aliasIdentificationVariable = $this->AliasIdentificationVariable();
1783.         $classMetadata               = $this->em->getClassMetadata($abstractSchemaName);
1785.         // Building queryComponent
1786.         $queryComponent = [
1787.             'metadata'     => $classMetadata,
1788.             'parent'       => null,
1789.             'relation'     => null,
1790.             'map'          => null,
1791.             'nestingLevel' => $this->nestingLevel,
1792.             'token'        => $token,
1793.         ];
1795.         $this->queryComponents[$aliasIdentificationVariable] = $queryComponent;
1797.         return new AST\RangeVariableDeclaration($abstractSchemaName, $aliasIdentificationVariable);
1798.     }
1800.     /**
1801.      * JoinAssociationDeclaration ::= JoinAssociationPathExpression ["AS"] AliasIdentificationVariable [IndexBy]
1802.      *
1803.      * @return AST\JoinAssociationDeclaration
1804.      */
1805.     public function JoinAssociationDeclaration()
1806.     {
1807.         $joinAssociationPathExpression = $this->JoinAssociationPathExpression();
1809.         if ($this->lexer->isNextToken(Lexer::T_AS)) {
1810.             $this->match(Lexer::T_AS);
1811.         }
1813.         assert($this->lexer->lookahead !== null);
1815.         $aliasIdentificationVariable = $this->AliasIdentificationVariable();
1816.         $indexBy                     = $this->lexer->isNextToken(Lexer::T_INDEX) ? $this->IndexBy() : null;
1818.         $identificationVariable = $joinAssociationPathExpression->identificationVariable;
1819.         $field                  = $joinAssociationPathExpression->associationField;
1821.         $class       = $this->getMetadataForDqlAlias($identificationVariable);
1822.         $targetClass = $this->em->getClassMetadata($class->associationMappings[$field]['targetEntity']);
1824.         // Building queryComponent
1825.         $joinQueryComponent = [
1826.             'metadata'     => $targetClass,
1827.             'parent'       => $joinAssociationPathExpression->identificationVariable,
1828.             'relation'     => $class->getAssociationMapping($field),
1829.             'map'          => null,
1830.             'nestingLevel' => $this->nestingLevel,
1831.             'token'        => $this->lexer->lookahead,
1832.         ];
1834.         $this->queryComponents[$aliasIdentificationVariable] = $joinQueryComponent;
1836.         return new AST\JoinAssociationDeclaration($joinAssociationPathExpression, $aliasIdentificationVariable, $indexBy);
1837.     }
1839.     /**
1840.      * PartialObjectExpression ::= "PARTIAL" IdentificationVariable "." PartialFieldSet
1841.      * PartialFieldSet ::= "{" SimpleStateField {"," SimpleStateField}* "}"
1842.      *
1843.      * @return AST\PartialObjectExpression
1844.      */
1845.     public function PartialObjectExpression()
1846.     {
1847.         Deprecation::trigger(
1848.             'doctrine/orm',
1849.             'https://github.com/doctrine/orm/issues/8471',
1850.             'PARTIAL syntax in DQL is deprecated.'
1851.         );
1853.         $this->match(Lexer::T_PARTIAL);
1855.         $partialFieldSet = [];
1857.         $identificationVariable = $this->IdentificationVariable();
1859.         $this->match(Lexer::T_DOT);
1860.         $this->match(Lexer::T_OPEN_CURLY_BRACE);
1861.         $this->match(Lexer::T_IDENTIFIER);
1863.         assert($this->lexer->token !== null);
1864.         $field = $this->lexer->token->value;
1866.         // First field in partial expression might be embeddable property
1867.         while ($this->lexer->isNextToken(Lexer::T_DOT)) {
1868.             $this->match(Lexer::T_DOT);
1869.             $this->match(Lexer::T_IDENTIFIER);
1870.             $field .= '.' . $this->lexer->token->value;
1871.         }
1873.         $partialFieldSet[] = $field;
1875.         while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
1876.             $this->match(Lexer::T_COMMA);
1877.             $this->match(Lexer::T_IDENTIFIER);
1879.             $field = $this->lexer->token->value;
1881.             while ($this->lexer->isNextToken(Lexer::T_DOT)) {
1882.                 $this->match(Lexer::T_DOT);
1883.                 $this->match(Lexer::T_IDENTIFIER);
1884.                 $field .= '.' . $this->lexer->token->value;
1885.             }
1887.             $partialFieldSet[] = $field;
1888.         }
1890.         $this->match(Lexer::T_CLOSE_CURLY_BRACE);
1892.         $partialObjectExpression = new AST\PartialObjectExpression($identificationVariable, $partialFieldSet);
1894.         // Defer PartialObjectExpression validation
1895.         $this->deferredPartialObjectExpressions[] = [
1896.             'expression'   => $partialObjectExpression,
1897.             'nestingLevel' => $this->nestingLevel,
1898.             'token'        => $this->lexer->token,
1899.         ];
1901.         return $partialObjectExpression;
1902.     }
1904.     /**
1905.      * NewObjectExpression ::= "NEW" AbstractSchemaName "(" NewObjectArg {"," NewObjectArg}* ")"
1906.      *
1907.      * @return AST\NewObjectExpression
1908.      */
1909.     public function NewObjectExpression()
1910.     {
1911.         $this->match(Lexer::T_NEW);
1913.         $className = $this->AbstractSchemaName(); // note that this is not yet validated
1914.         $token     = $this->lexer->token;
1916.         $this->match(Lexer::T_OPEN_PARENTHESIS);
1918.         $args[] = $this->NewObjectArg();
1920.         while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
1921.             $this->match(Lexer::T_COMMA);
1923.             $args[] = $this->NewObjectArg();
1924.         }
1926.         $this->match(Lexer::T_CLOSE_PARENTHESIS);
1928.         $expression = new AST\NewObjectExpression($className, $args);
1930.         // Defer NewObjectExpression validation
1931.         $this->deferredNewObjectExpressions[] = [
1932.             'token'        => $token,
1933.             'expression'   => $expression,
1934.             'nestingLevel' => $this->nestingLevel,
1935.         ];
1937.         return $expression;
1938.     }
1940.     /**
1941.      * NewObjectArg ::= ScalarExpression | "(" Subselect ")"
1942.      *
1943.      * @return mixed
1944.      */
1945.     public function NewObjectArg()
1946.     {
1947.         assert($this->lexer->lookahead !== null);
1948.         $token = $this->lexer->lookahead;
1949.         $peek  = $this->lexer->glimpse();
1951.         assert($peek !== null);
1952.         if ($token->type === Lexer::T_OPEN_PARENTHESIS && $peek->type === Lexer::T_SELECT) {
1953.             $this->match(Lexer::T_OPEN_PARENTHESIS);
1954.             $expression = $this->Subselect();
1955.             $this->match(Lexer::T_CLOSE_PARENTHESIS);
1957.             return $expression;
1958.         }
1960.         return $this->ScalarExpression();
1961.     }
1963.     /**
1964.      * IndexBy ::= "INDEX" "BY" SingleValuedPathExpression
1965.      *
1966.      * @return AST\IndexBy
1967.      */
1968.     public function IndexBy()
1969.     {
1970.         $this->match(Lexer::T_INDEX);
1971.         $this->match(Lexer::T_BY);
1972.         $pathExpr = $this->SingleValuedPathExpression();
1974.         // Add the INDEX BY info to the query component
1975.         $this->queryComponents[$pathExpr->identificationVariable]['map'] = $pathExpr->field;
1977.         return new AST\IndexBy($pathExpr);
1978.     }
1980.     /**
1981.      * ScalarExpression ::= SimpleArithmeticExpression | StringPrimary | DateTimePrimary |
1982.      *                      StateFieldPathExpression | BooleanPrimary | CaseExpression |
1983.      *                      InstanceOfExpression
1984.      *
1985.      * @return mixed One of the possible expressions or subexpressions.
1986.      */
1987.     public function ScalarExpression()
1988.     {
1989.         assert($this->lexer->token !== null);
1990.         assert($this->lexer->lookahead !== null);
1991.         $lookahead = $this->lexer->lookahead->type;
1992.         $peek      = $this->lexer->glimpse();
1994.         switch (true) {
1995.             case $lookahead === Lexer::T_INTEGER:
1996.             case $lookahead === Lexer::T_FLOAT:
1997.             // SimpleArithmeticExpression : (- u.value ) or ( + u.value )  or ( - 1 ) or ( + 1 )
1998.             case $lookahead === Lexer::T_MINUS:
1999.             case $lookahead === Lexer::T_PLUS:
2000.                 return $this->SimpleArithmeticExpression();
2002.             case $lookahead === Lexer::T_STRING:
2003.                 return $this->StringPrimary();
2005.             case $lookahead === Lexer::T_TRUE:
2006.             case $lookahead === Lexer::T_FALSE:
2007.                 $this->match($lookahead);
2009.                 return new AST\Literal(AST\Literal::BOOLEAN, $this->lexer->token->value);
2011.             case $lookahead === Lexer::T_INPUT_PARAMETER:
2012.                 switch (true) {
2013.                     case $this->isMathOperator($peek):
2014.                         // :param + u.value
2015.                         return $this->SimpleArithmeticExpression();
2017.                     default:
2018.                         return $this->InputParameter();
2019.                 }
2020.             case $lookahead === Lexer::T_CASE:
2021.             case $lookahead === Lexer::T_COALESCE:
2022.             case $lookahead === Lexer::T_NULLIF:
2023.                 // Since NULLIF and COALESCE can be identified as a function,
2024.                 // we need to check these before checking for FunctionDeclaration
2025.                 return $this->CaseExpression();
2027.             case $lookahead === Lexer::T_OPEN_PARENTHESIS:
2028.                 return $this->SimpleArithmeticExpression();
2030.             // this check must be done before checking for a filed path expression
2031.             case $this->isFunction():
2032.                 $this->lexer->peek(); // "("
2034.                 switch (true) {
2035.                     case $this->isMathOperator($this->peekBeyondClosingParenthesis()):
2036.                         // SUM(u.id) + COUNT(u.id)
2037.                         return $this->SimpleArithmeticExpression();
2039.                     default:
2040.                         // IDENTITY(u)
2041.                         return $this->FunctionDeclaration();
2042.                 }
2044.                 break;
2045.             // it is no function, so it must be a field path
2046.             case $lookahead === Lexer::T_IDENTIFIER:
2047.                 $this->lexer->peek(); // lookahead => '.'
2048.                 $this->lexer->peek(); // lookahead => token after '.'
2049.                 $peek = $this->lexer->peek(); // lookahead => token after the token after the '.'
2050.                 $this->lexer->resetPeek();
2052.                 if ($this->isMathOperator($peek)) {
2053.                     return $this->SimpleArithmeticExpression();
2054.                 }
2056.                 return $this->StateFieldPathExpression();
2058.             default:
2059.                 $this->syntaxError();
2060.         }
2061.     }
2063.     /**
2064.      * CaseExpression ::= GeneralCaseExpression | SimpleCaseExpression | CoalesceExpression | NullifExpression
2065.      * GeneralCaseExpression ::= "CASE" WhenClause {WhenClause}* "ELSE" ScalarExpression "END"
2066.      * WhenClause ::= "WHEN" ConditionalExpression "THEN" ScalarExpression
2067.      * SimpleCaseExpression ::= "CASE" CaseOperand SimpleWhenClause {SimpleWhenClause}* "ELSE" ScalarExpression "END"
2068.      * CaseOperand ::= StateFieldPathExpression | TypeDiscriminator
2069.      * SimpleWhenClause ::= "WHEN" ScalarExpression "THEN" ScalarExpression
2070.      * CoalesceExpression ::= "COALESCE" "(" ScalarExpression {"," ScalarExpression}* ")"
2071.      * NullifExpression ::= "NULLIF" "(" ScalarExpression "," ScalarExpression ")"
2072.      *
2073.      * @return mixed One of the possible expressions or subexpressions.
2074.      */
2075.     public function CaseExpression()
2076.     {
2077.         assert($this->lexer->lookahead !== null);
2078.         $lookahead = $this->lexer->lookahead->type;
2080.         switch ($lookahead) {
2081.             case Lexer::T_NULLIF:
2082.                 return $this->NullIfExpression();
2084.             case Lexer::T_COALESCE:
2085.                 return $this->CoalesceExpression();
2087.             case Lexer::T_CASE:
2088.                 $this->lexer->resetPeek();
2089.                 $peek = $this->lexer->peek();
2091.                 assert($peek !== null);
2092.                 if ($peek->type === Lexer::T_WHEN) {
2093.                     return $this->GeneralCaseExpression();
2094.                 }
2096.                 return $this->SimpleCaseExpression();
2098.             default:
2099.                 // Do nothing
2100.                 break;
2101.         }
2103.         $this->syntaxError();
2104.     }
2106.     /**
2107.      * CoalesceExpression ::= "COALESCE" "(" ScalarExpression {"," ScalarExpression}* ")"
2108.      *
2109.      * @return AST\CoalesceExpression
2110.      */
2111.     public function CoalesceExpression()
2112.     {
2113.         $this->match(Lexer::T_COALESCE);
2114.         $this->match(Lexer::T_OPEN_PARENTHESIS);
2116.         // Process ScalarExpressions (1..N)
2117.         $scalarExpressions   = [];
2118.         $scalarExpressions[] = $this->ScalarExpression();
2120.         while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
2121.             $this->match(Lexer::T_COMMA);
2123.             $scalarExpressions[] = $this->ScalarExpression();
2124.         }
2126.         $this->match(Lexer::T_CLOSE_PARENTHESIS);
2128.         return new AST\CoalesceExpression($scalarExpressions);
2129.     }
2131.     /**
2132.      * NullIfExpression ::= "NULLIF" "(" ScalarExpression "," ScalarExpression ")"
2133.      *
2134.      * @return AST\NullIfExpression
2135.      */
2136.     public function NullIfExpression()
2137.     {
2138.         $this->match(Lexer::T_NULLIF);
2139.         $this->match(Lexer::T_OPEN_PARENTHESIS);
2141.         $firstExpression = $this->ScalarExpression();
2142.         $this->match(Lexer::T_COMMA);
2143.         $secondExpression = $this->ScalarExpression();
2145.         $this->match(Lexer::T_CLOSE_PARENTHESIS);
2147.         return new AST\NullIfExpression($firstExpression, $secondExpression);
2148.     }
2150.     /**
2151.      * GeneralCaseExpression ::= "CASE" WhenClause {WhenClause}* "ELSE" ScalarExpression "END"
2152.      *
2153.      * @return AST\GeneralCaseExpression
2154.      */
2155.     public function GeneralCaseExpression()
2156.     {
2157.         $this->match(Lexer::T_CASE);
2159.         // Process WhenClause (1..N)
2160.         $whenClauses = [];
2162.         do {
2163.             $whenClauses[] = $this->WhenClause();
2164.         } while ($this->lexer->isNextToken(Lexer::T_WHEN));
2166.         $this->match(Lexer::T_ELSE);
2167.         $scalarExpression = $this->ScalarExpression();
2168.         $this->match(Lexer::T_END);
2170.         return new AST\GeneralCaseExpression($whenClauses, $scalarExpression);
2171.     }
2173.     /**
2174.      * SimpleCaseExpression ::= "CASE" CaseOperand SimpleWhenClause {SimpleWhenClause}* "ELSE" ScalarExpression "END"
2175.      * CaseOperand ::= StateFieldPathExpression | TypeDiscriminator
2176.      *
2177.      * @return AST\SimpleCaseExpression
2178.      */
2179.     public function SimpleCaseExpression()
2180.     {
2181.         $this->match(Lexer::T_CASE);
2182.         $caseOperand = $this->StateFieldPathExpression();
2184.         // Process SimpleWhenClause (1..N)
2185.         $simpleWhenClauses = [];
2187.         do {
2188.             $simpleWhenClauses[] = $this->SimpleWhenClause();
2189.         } while ($this->lexer->isNextToken(Lexer::T_WHEN));
2191.         $this->match(Lexer::T_ELSE);
2192.         $scalarExpression = $this->ScalarExpression();
2193.         $this->match(Lexer::T_END);
2195.         return new AST\SimpleCaseExpression($caseOperand, $simpleWhenClauses, $scalarExpression);
2196.     }
2198.     /**
2199.      * WhenClause ::= "WHEN" ConditionalExpression "THEN" ScalarExpression
2200.      *
2201.      * @return AST\WhenClause
2202.      */
2203.     public function WhenClause()
2204.     {
2205.         $this->match(Lexer::T_WHEN);
2206.         $conditionalExpression = $this->ConditionalExpression();
2207.         $this->match(Lexer::T_THEN);
2209.         return new AST\WhenClause($conditionalExpression, $this->ScalarExpression());
2210.     }
2212.     /**
2213.      * SimpleWhenClause ::= "WHEN" ScalarExpression "THEN" ScalarExpression
2214.      *
2215.      * @return AST\SimpleWhenClause
2216.      */
2217.     public function SimpleWhenClause()
2218.     {
2219.         $this->match(Lexer::T_WHEN);
2220.         $conditionalExpression = $this->ScalarExpression();
2221.         $this->match(Lexer::T_THEN);
2223.         return new AST\SimpleWhenClause($conditionalExpression, $this->ScalarExpression());
2224.     }
2226.     /**
2227.      * SelectExpression ::= (
2228.      *     IdentificationVariable | ScalarExpression | AggregateExpression | FunctionDeclaration |
2229.      *     PartialObjectExpression | "(" Subselect ")" | CaseExpression | NewObjectExpression
2230.      * ) [["AS"] ["HIDDEN"] AliasResultVariable]
2231.      *
2232.      * @return AST\SelectExpression
2233.      */
2234.     public function SelectExpression()
2235.     {
2236.         assert($this->lexer->lookahead !== null);
2237.         $expression    = null;
2238.         $identVariable = null;
2239.         $peek          = $this->lexer->glimpse();
2240.         $lookaheadType = $this->lexer->lookahead->type;
2241.         assert($peek !== null);
2243.         switch (true) {
2244.             // ScalarExpression (u.name)
2245.             case $lookaheadType === Lexer::T_IDENTIFIER && $peek->type === Lexer::T_DOT:
2246.                 $expression = $this->ScalarExpression();
2247.                 break;
2249.             // IdentificationVariable (u)
2250.             case $lookaheadType === Lexer::T_IDENTIFIER && $peek->type !== Lexer::T_OPEN_PARENTHESIS:
2251.                 $expression = $identVariable = $this->IdentificationVariable();
2252.                 break;
2254.             // CaseExpression (CASE ... or NULLIF(...) or COALESCE(...))
2255.             case $lookaheadType === Lexer::T_CASE:
2256.             case $lookaheadType === Lexer::T_COALESCE:
2257.             case $lookaheadType === Lexer::T_NULLIF:
2258.                 $expression = $this->CaseExpression();
2259.                 break;
2261.             // DQL Function (SUM(u.value) or SUM(u.value) + 1)
2262.             case $this->isFunction():
2263.                 $this->lexer->peek(); // "("
2265.                 switch (true) {
2266.                     case $this->isMathOperator($this->peekBeyondClosingParenthesis()):
2267.                         // SUM(u.id) + COUNT(u.id)
2268.                         $expression = $this->ScalarExpression();
2269.                         break;
2271.                     default:
2272.                         // IDENTITY(u)
2273.                         $expression = $this->FunctionDeclaration();
2274.                         break;
2275.                 }
2277.                 break;
2279.             // PartialObjectExpression (PARTIAL u.{id, name})
2280.             case $lookaheadType === Lexer::T_PARTIAL:
2281.                 $expression    = $this->PartialObjectExpression();
2282.                 $identVariable = $expression->identificationVariable;
2283.                 break;
2285.             // Subselect
2286.             case $lookaheadType === Lexer::T_OPEN_PARENTHESIS && $peek->type === Lexer::T_SELECT:
2287.                 $this->match(Lexer::T_OPEN_PARENTHESIS);
2288.                 $expression = $this->Subselect();
2289.                 $this->match(Lexer::T_CLOSE_PARENTHESIS);
2290.                 break;
2292.             // Shortcut: ScalarExpression => SimpleArithmeticExpression
2293.             case $lookaheadType === Lexer::T_OPEN_PARENTHESIS:
2294.             case $lookaheadType === Lexer::T_INTEGER:
2295.             case $lookaheadType === Lexer::T_STRING:
2296.             case $lookaheadType === Lexer::T_FLOAT:
2297.             // SimpleArithmeticExpression : (- u.value ) or ( + u.value )
2298.             case $lookaheadType === Lexer::T_MINUS:
2299.             case $lookaheadType === Lexer::T_PLUS:
2300.                 $expression = $this->SimpleArithmeticExpression();
2301.                 break;
2303.             // NewObjectExpression (New ClassName(id, name))
2304.             case $lookaheadType === Lexer::T_NEW:
2305.                 $expression = $this->NewObjectExpression();
2306.                 break;
2308.             default:
2309.                 $this->syntaxError(
2310.                     'IdentificationVariable | ScalarExpression | AggregateExpression | FunctionDeclaration | PartialObjectExpression | "(" Subselect ")" | CaseExpression',
2311.                     $this->lexer->lookahead
2312.                 );
2313.         }
2315.         // [["AS"] ["HIDDEN"] AliasResultVariable]
2316.         $mustHaveAliasResultVariable = false;
2318.         if ($this->lexer->isNextToken(Lexer::T_AS)) {
2319.             $this->match(Lexer::T_AS);
2321.             $mustHaveAliasResultVariable = true;
2322.         }
2324.         $hiddenAliasResultVariable = false;
2326.         if ($this->lexer->isNextToken(Lexer::T_HIDDEN)) {
2327.             $this->match(Lexer::T_HIDDEN);
2329.             $hiddenAliasResultVariable = true;
2330.         }
2332.         $aliasResultVariable = null;
2334.         if ($mustHaveAliasResultVariable || $this->lexer->isNextToken(Lexer::T_IDENTIFIER)) {
2335.             assert($expression instanceof AST\Node || is_string($expression));
2336.             $token               = $this->lexer->lookahead;
2337.             $aliasResultVariable = $this->AliasResultVariable();
2339.             // Include AliasResultVariable in query components.
2340.             $this->queryComponents[$aliasResultVariable] = [
2341.                 'resultVariable' => $expression,
2342.                 'nestingLevel'   => $this->nestingLevel,
2343.                 'token'          => $token,
2344.             ];
2345.         }
2347.         // AST
2349.         $expr = new AST\SelectExpression($expression, $aliasResultVariable, $hiddenAliasResultVariable);
2351.         if ($identVariable) {
2352.             $this->identVariableExpressions[$identVariable] = $expr;
2353.         }
2355.         return $expr;
2356.     }
2358.     /**
2359.      * SimpleSelectExpression ::= (
2360.      *      StateFieldPathExpression | IdentificationVariable | FunctionDeclaration |
2361.      *      AggregateExpression | "(" Subselect ")" | ScalarExpression
2362.      * ) [["AS"] AliasResultVariable]
2363.      *
2364.      * @return AST\SimpleSelectExpression
2365.      */
2366.     public function SimpleSelectExpression()
2367.     {
2368.         assert($this->lexer->lookahead !== null);
2369.         $peek = $this->lexer->glimpse();
2370.         assert($peek !== null);
2372.         switch ($this->lexer->lookahead->type) {
2373.             case Lexer::T_IDENTIFIER:
2374.                 switch (true) {
2375.                     case $peek->type === Lexer::T_DOT:
2376.                         $expression = $this->StateFieldPathExpression();
2378.                         return new AST\SimpleSelectExpression($expression);
2380.                     case $peek->type !== Lexer::T_OPEN_PARENTHESIS:
2381.                         $expression = $this->IdentificationVariable();
2383.                         return new AST\SimpleSelectExpression($expression);
2385.                     case $this->isFunction():
2386.                         // SUM(u.id) + COUNT(u.id)
2387.                         if ($this->isMathOperator($this->peekBeyondClosingParenthesis())) {
2388.                             return new AST\SimpleSelectExpression($this->ScalarExpression());
2389.                         }
2391.                         // COUNT(u.id)
2392.                         if ($this->isAggregateFunction($this->lexer->lookahead->type)) {
2393.                             return new AST\SimpleSelectExpression($this->AggregateExpression());
2394.                         }
2396.                         // IDENTITY(u)
2397.                         return new AST\SimpleSelectExpression($this->FunctionDeclaration());
2399.                     default:
2400.                         // Do nothing
2401.                 }
2403.                 break;
2405.             case Lexer::T_OPEN_PARENTHESIS:
2406.                 if ($peek->type !== Lexer::T_SELECT) {
2407.                     // Shortcut: ScalarExpression => SimpleArithmeticExpression
2408.                     $expression = $this->SimpleArithmeticExpression();
2410.                     return new AST\SimpleSelectExpression($expression);
2411.                 }
2413.                 // Subselect
2414.                 $this->match(Lexer::T_OPEN_PARENTHESIS);
2415.                 $expression = $this->Subselect();
2416.                 $this->match(Lexer::T_CLOSE_PARENTHESIS);
2418.                 return new AST\SimpleSelectExpression($expression);
2420.             default:
2421.                 // Do nothing
2422.         }
2424.         $this->lexer->peek();
2426.         $expression = $this->ScalarExpression();
2427.         $expr       = new AST\SimpleSelectExpression($expression);
2429.         if ($this->lexer->isNextToken(Lexer::T_AS)) {
2430.             $this->match(Lexer::T_AS);
2431.         }
2433.         if ($this->lexer->isNextToken(Lexer::T_IDENTIFIER)) {
2434.             $token                             = $this->lexer->lookahead;
2435.             $resultVariable                    = $this->AliasResultVariable();
2436.             $expr->fieldIdentificationVariable = $resultVariable;
2438.             // Include AliasResultVariable in query components.
2439.             $this->queryComponents[$resultVariable] = [
2440.                 'resultvariable' => $expr,
2441.                 'nestingLevel'   => $this->nestingLevel,
2442.                 'token'          => $token,
2443.             ];
2444.         }
2446.         return $expr;
2447.     }
2449.     /**
2450.      * ConditionalExpression ::= ConditionalTerm {"OR" ConditionalTerm}*
2451.      *
2452.      * @return AST\ConditionalExpression|AST\ConditionalFactor|AST\ConditionalPrimary|AST\ConditionalTerm
2453.      */
2454.     public function ConditionalExpression()
2455.     {
2456.         $conditionalTerms   = [];
2457.         $conditionalTerms[] = $this->ConditionalTerm();
2459.         while ($this->lexer->isNextToken(Lexer::T_OR)) {
2460.             $this->match(Lexer::T_OR);
2462.             $conditionalTerms[] = $this->ConditionalTerm();
2463.         }
2465.         // Phase 1 AST optimization: Prevent AST\ConditionalExpression
2466.         // if only one AST\ConditionalTerm is defined
2467.         if (count($conditionalTerms) === 1) {
2468.             return $conditionalTerms[0];
2469.         }
2471.         return new AST\ConditionalExpression($conditionalTerms);
2472.     }
2474.     /**
2475.      * ConditionalTerm ::= ConditionalFactor {"AND" ConditionalFactor}*
2476.      *
2477.      * @return AST\ConditionalFactor|AST\ConditionalPrimary|AST\ConditionalTerm
2478.      */
2479.     public function ConditionalTerm()
2480.     {
2481.         $conditionalFactors   = [];
2482.         $conditionalFactors[] = $this->ConditionalFactor();
2484.         while ($this->lexer->isNextToken(Lexer::T_AND)) {
2485.             $this->match(Lexer::T_AND);
2487.             $conditionalFactors[] = $this->ConditionalFactor();
2488.         }
2490.         // Phase 1 AST optimization: Prevent AST\ConditionalTerm
2491.         // if only one AST\ConditionalFactor is defined
2492.         if (count($conditionalFactors) === 1) {
2493.             return $conditionalFactors[0];
2494.         }
2496.         return new AST\ConditionalTerm($conditionalFactors);
2497.     }
2499.     /**
2500.      * ConditionalFactor ::= ["NOT"] ConditionalPrimary
2501.      *
2502.      * @return AST\ConditionalFactor|AST\ConditionalPrimary
2503.      */
2504.     public function ConditionalFactor()
2505.     {
2506.         $not = false;
2508.         if ($this->lexer->isNextToken(Lexer::T_NOT)) {
2509.             $this->match(Lexer::T_NOT);
2511.             $not = true;
2512.         }
2514.         $conditionalPrimary = $this->ConditionalPrimary();
2516.         // Phase 1 AST optimization: Prevent AST\ConditionalFactor
2517.         // if only one AST\ConditionalPrimary is defined
2518.         if (! $not) {
2519.             return $conditionalPrimary;
2520.         }
2522.         return new AST\ConditionalFactor($conditionalPrimary, $not);
2523.     }
2525.     /**
2526.      * ConditionalPrimary ::= SimpleConditionalExpression | "(" ConditionalExpression ")"
2527.      *
2528.      * @return AST\ConditionalPrimary
2529.      */
2530.     public function ConditionalPrimary()
2531.     {
2532.         $condPrimary = new AST\ConditionalPrimary();
2534.         if (! $this->lexer->isNextToken(Lexer::T_OPEN_PARENTHESIS)) {
2535.             $condPrimary->simpleConditionalExpression = $this->SimpleConditionalExpression();
2537.             return $condPrimary;
2538.         }
2540.         // Peek beyond the matching closing parenthesis ')'
2541.         $peek = $this->peekBeyondClosingParenthesis();
2543.         if (
2544.             $peek !== null && (
2545.             in_array($peek->value, ['=', '<', '<=', '<>', '>', '>=', '!='], true) ||
2546.             in_array($peek->type, [Lexer::T_NOT, Lexer::T_BETWEEN, Lexer::T_LIKE, Lexer::T_IN, Lexer::T_IS, Lexer::T_EXISTS], true) ||
2547.             $this->isMathOperator($peek)
2548.             )
2549.         ) {
2550.             $condPrimary->simpleConditionalExpression = $this->SimpleConditionalExpression();
2552.             return $condPrimary;
2553.         }
2555.         $this->match(Lexer::T_OPEN_PARENTHESIS);
2556.         $condPrimary->conditionalExpression = $this->ConditionalExpression();
2557.         $this->match(Lexer::T_CLOSE_PARENTHESIS);
2559.         return $condPrimary;
2560.     }
2562.     /**
2563.      * SimpleConditionalExpression ::=
2564.      *      ComparisonExpression | BetweenExpression | LikeExpression |
2565.      *      InExpression | NullComparisonExpression | ExistsExpression |
2566.      *      EmptyCollectionComparisonExpression | CollectionMemberExpression |
2567.      *      InstanceOfExpression
2568.      *
2569.      * @return AST\BetweenExpression|
2570.      *         AST\CollectionMemberExpression|
2571.      *         AST\ComparisonExpression|
2572.      *         AST\EmptyCollectionComparisonExpression|
2573.      *         AST\ExistsExpression|
2574.      *         AST\InExpression|
2575.      *         AST\InstanceOfExpression|
2576.      *         AST\LikeExpression|
2577.      *         AST\NullComparisonExpression
2578.      */
2579.     public function SimpleConditionalExpression()
2580.     {
2581.         assert($this->lexer->lookahead !== null);
2582.         if ($this->lexer->isNextToken(Lexer::T_EXISTS)) {
2583.             return $this->ExistsExpression();
2584.         }
2586.         $token     = $this->lexer->lookahead;
2587.         $peek      = $this->lexer->glimpse();
2588.         $lookahead = $token;
2590.         if ($this->lexer->isNextToken(Lexer::T_NOT)) {
2591.             $token = $this->lexer->glimpse();
2592.         }
2594.         assert($token !== null);
2595.         assert($peek !== null);
2596.         if ($token->type === Lexer::T_IDENTIFIER || $token->type === Lexer::T_INPUT_PARAMETER || $this->isFunction()) {
2597.             // Peek beyond the matching closing parenthesis.
2598.             $beyond = $this->lexer->peek();
2600.             switch ($peek->value) {
2601.                 case '(':
2602.                     // Peeks beyond the matched closing parenthesis.
2603.                     $token = $this->peekBeyondClosingParenthesis(false);
2604.                     assert($token !== null);
2606.                     if ($token->type === Lexer::T_NOT) {
2607.                         $token = $this->lexer->peek();
2608.                         assert($token !== null);
2609.                     }
2611.                     if ($token->type === Lexer::T_IS) {
2612.                         $lookahead = $this->lexer->peek();
2613.                     }
2615.                     break;
2617.                 default:
2618.                     // Peek beyond the PathExpression or InputParameter.
2619.                     $token = $beyond;
2621.                     while ($token->value === '.') {
2622.                         $this->lexer->peek();
2624.                         $token = $this->lexer->peek();
2625.                         assert($token !== null);
2626.                     }
2628.                     // Also peek beyond a NOT if there is one.
2629.                     assert($token !== null);
2630.                     if ($token->type === Lexer::T_NOT) {
2631.                         $token = $this->lexer->peek();
2632.                         assert($token !== null);
2633.                     }
2635.                     // We need to go even further in case of IS (differentiate between NULL and EMPTY)
2636.                     $lookahead = $this->lexer->peek();
2637.             }
2639.             assert($lookahead !== null);
2640.             // Also peek beyond a NOT if there is one.
2641.             if ($lookahead->type === Lexer::T_NOT) {
2642.                 $lookahead = $this->lexer->peek();
2643.             }
2645.             $this->lexer->resetPeek();
2646.         }
2648.         if ($token->type === Lexer::T_BETWEEN) {
2649.             return $this->BetweenExpression();
2650.         }
2652.         if ($token->type === Lexer::T_LIKE) {
2653.             return $this->LikeExpression();
2654.         }
2656.         if ($token->type === Lexer::T_IN) {
2657.             return $this->InExpression();
2658.         }
2660.         if ($token->type === Lexer::T_INSTANCE) {
2661.             return $this->InstanceOfExpression();
2662.         }
2664.         if ($token->type === Lexer::T_MEMBER) {
2665.             return $this->CollectionMemberExpression();
2666.         }
2668.         assert($lookahead !== null);
2669.         if ($token->type === Lexer::T_IS && $lookahead->type === Lexer::T_NULL) {
2670.             return $this->NullComparisonExpression();
2671.         }
2673.         if ($token->type === Lexer::T_IS && $lookahead->type === Lexer::T_EMPTY) {
2674.             return $this->EmptyCollectionComparisonExpression();
2675.         }
2677.         return $this->ComparisonExpression();
2678.     }
2680.     /**
2681.      * EmptyCollectionComparisonExpression ::= CollectionValuedPathExpression "IS" ["NOT"] "EMPTY"
2682.      *
2683.      * @return AST\EmptyCollectionComparisonExpression
2684.      */
2685.     public function EmptyCollectionComparisonExpression()
2686.     {
2687.         $pathExpression = $this->CollectionValuedPathExpression();
2688.         $this->match(Lexer::T_IS);
2690.         $not = false;
2691.         if ($this->lexer->isNextToken(Lexer::T_NOT)) {
2692.             $this->match(Lexer::T_NOT);
2693.             $not = true;
2694.         }
2696.         $this->match(Lexer::T_EMPTY);
2698.         return new AST\EmptyCollectionComparisonExpression(
2699.             $pathExpression,
2700.             $not
2701.         );
2702.     }
2704.     /**
2705.      * CollectionMemberExpression ::= EntityExpression ["NOT"] "MEMBER" ["OF"] CollectionValuedPathExpression
2706.      *
2707.      * EntityExpression ::= SingleValuedAssociationPathExpression | SimpleEntityExpression
2708.      * SimpleEntityExpression ::= IdentificationVariable | InputParameter
2709.      *
2710.      * @return AST\CollectionMemberExpression
2711.      */
2712.     public function CollectionMemberExpression()
2713.     {
2714.         $not        = false;
2715.         $entityExpr = $this->EntityExpression();
2717.         if ($this->lexer->isNextToken(Lexer::T_NOT)) {
2718.             $this->match(Lexer::T_NOT);
2720.             $not = true;
2721.         }
2723.         $this->match(Lexer::T_MEMBER);
2725.         if ($this->lexer->isNextToken(Lexer::T_OF)) {
2726.             $this->match(Lexer::T_OF);
2727.         }
2729.         return new AST\CollectionMemberExpression(
2730.             $entityExpr,
2731.             $this->CollectionValuedPathExpression(),
2732.             $not
2733.         );
2734.     }
2736.     /**
2737.      * Literal ::= string | char | integer | float | boolean
2738.      *
2739.      * @return AST\Literal
2740.      */
2741.     public function Literal()
2742.     {
2743.         assert($this->lexer->lookahead !== null);
2744.         assert($this->lexer->token !== null);
2745.         switch ($this->lexer->lookahead->type) {
2746.             case Lexer::T_STRING:
2747.                 $this->match(Lexer::T_STRING);
2749.                 return new AST\Literal(AST\Literal::STRING, $this->lexer->token->value);
2751.             case Lexer::T_INTEGER:
2752.             case Lexer::T_FLOAT:
2753.                 $this->match(
2754.                     $this->lexer->isNextToken(Lexer::T_INTEGER) ? Lexer::T_INTEGER : Lexer::T_FLOAT
2755.                 );
2757.                 return new AST\Literal(AST\Literal::NUMERIC, $this->lexer->token->value);
2759.             case Lexer::T_TRUE:
2760.             case Lexer::T_FALSE:
2761.                 $this->match(
2762.                     $this->lexer->isNextToken(Lexer::T_TRUE) ? Lexer::T_TRUE : Lexer::T_FALSE
2763.                 );
2765.                 return new AST\Literal(AST\Literal::BOOLEAN, $this->lexer->token->value);
2767.             default:
2768.                 $this->syntaxError('Literal');
2769.         }
2770.     }
2772.     /**
2773.      * InParameter ::= ArithmeticExpression | InputParameter
2774.      *
2775.      * @return AST\InputParameter|AST\ArithmeticExpression
2776.      */
2777.     public function InParameter()
2778.     {
2779.         assert($this->lexer->lookahead !== null);
2780.         if ($this->lexer->lookahead->type === Lexer::T_INPUT_PARAMETER) {
2781.             return $this->InputParameter();
2782.         }
2784.         return $this->ArithmeticExpression();
2785.     }
2787.     /**
2788.      * InputParameter ::= PositionalParameter | NamedParameter
2789.      *
2790.      * @return AST\InputParameter
2791.      */
2792.     public function InputParameter()
2793.     {
2794.         $this->match(Lexer::T_INPUT_PARAMETER);
2795.         assert($this->lexer->token !== null);
2797.         return new AST\InputParameter($this->lexer->token->value);
2798.     }
2800.     /**
2801.      * ArithmeticExpression ::= SimpleArithmeticExpression | "(" Subselect ")"
2802.      *
2803.      * @return AST\ArithmeticExpression
2804.      */
2805.     public function ArithmeticExpression()
2806.     {
2807.         $expr = new AST\ArithmeticExpression();
2809.         if ($this->lexer->isNextToken(Lexer::T_OPEN_PARENTHESIS)) {
2810.             $peek = $this->lexer->glimpse();
2811.             assert($peek !== null);
2813.             if ($peek->type === Lexer::T_SELECT) {
2814.                 $this->match(Lexer::T_OPEN_PARENTHESIS);
2815.                 $expr->subselect = $this->Subselect();
2816.                 $this->match(Lexer::T_CLOSE_PARENTHESIS);
2818.                 return $expr;
2819.             }
2820.         }
2822.         $expr->simpleArithmeticExpression = $this->SimpleArithmeticExpression();
2824.         return $expr;
2825.     }
2827.     /**
2828.      * SimpleArithmeticExpression ::= ArithmeticTerm {("+" | "-") ArithmeticTerm}*
2829.      *
2830.      * @return AST\SimpleArithmeticExpression|AST\ArithmeticTerm
2831.      */
2832.     public function SimpleArithmeticExpression()
2833.     {
2834.         $terms   = [];
2835.         $terms[] = $this->ArithmeticTerm();
2837.         while (($isPlus = $this->lexer->isNextToken(Lexer::T_PLUS)) || $this->lexer->isNextToken(Lexer::T_MINUS)) {
2838.             $this->match($isPlus ? Lexer::T_PLUS : Lexer::T_MINUS);
2840.             assert($this->lexer->token !== null);
2841.             $terms[] = $this->lexer->token->value;
2842.             $terms[] = $this->ArithmeticTerm();
2843.         }
2845.         // Phase 1 AST optimization: Prevent AST\SimpleArithmeticExpression
2846.         // if only one AST\ArithmeticTerm is defined
2847.         if (count($terms) === 1) {
2848.             return $terms[0];
2849.         }
2851.         return new AST\SimpleArithmeticExpression($terms);
2852.     }
2854.     /**
2855.      * ArithmeticTerm ::= ArithmeticFactor {("*" | "/") ArithmeticFactor}*
2856.      *
2857.      * @return AST\ArithmeticTerm
2858.      */
2859.     public function ArithmeticTerm()
2860.     {
2861.         $factors   = [];
2862.         $factors[] = $this->ArithmeticFactor();
2864.         while (($isMult = $this->lexer->isNextToken(Lexer::T_MULTIPLY)) || $this->lexer->isNextToken(Lexer::T_DIVIDE)) {
2865.             $this->match($isMult ? Lexer::T_MULTIPLY : Lexer::T_DIVIDE);
2867.             assert($this->lexer->token !== null);
2868.             $factors[] = $this->lexer->token->value;
2869.             $factors[] = $this->ArithmeticFactor();
2870.         }
2872.         // Phase 1 AST optimization: Prevent AST\ArithmeticTerm
2873.         // if only one AST\ArithmeticFactor is defined
2874.         if (count($factors) === 1) {
2875.             return $factors[0];
2876.         }
2878.         return new AST\ArithmeticTerm($factors);
2879.     }
2881.     /**
2882.      * ArithmeticFactor ::= [("+" | "-")] ArithmeticPrimary
2883.      *
2884.      * @return AST\ArithmeticFactor
2885.      */
2886.     public function ArithmeticFactor()
2887.     {
2888.         $sign = null;
2890.         $isPlus = $this->lexer->isNextToken(Lexer::T_PLUS);
2891.         if ($isPlus || $this->lexer->isNextToken(Lexer::T_MINUS)) {
2892.             $this->match($isPlus ? Lexer::T_PLUS : Lexer::T_MINUS);
2893.             $sign = $isPlus;
2894.         }
2896.         $primary = $this->ArithmeticPrimary();
2898.         // Phase 1 AST optimization: Prevent AST\ArithmeticFactor
2899.         // if only one AST\ArithmeticPrimary is defined
2900.         if ($sign === null) {
2901.             return $primary;
2902.         }
2904.         return new AST\ArithmeticFactor($primary, $sign);
2905.     }
2907.     /**
2908.      * ArithmeticPrimary ::= SingleValuedPathExpression | Literal | ParenthesisExpression
2909.      *          | FunctionsReturningNumerics | AggregateExpression | FunctionsReturningStrings
2910.      *          | FunctionsReturningDatetime | IdentificationVariable | ResultVariable
2911.      *          | InputParameter | CaseExpression
2912.      *
2913.      * @return AST\Node|string
2914.      */
2915.     public function ArithmeticPrimary()
2916.     {
2917.         if ($this->lexer->isNextToken(Lexer::T_OPEN_PARENTHESIS)) {
2918.             $this->match(Lexer::T_OPEN_PARENTHESIS);
2920.             $expr = $this->SimpleArithmeticExpression();
2922.             $this->match(Lexer::T_CLOSE_PARENTHESIS);
2924.             return new AST\ParenthesisExpression($expr);
2925.         }
2927.         assert($this->lexer->lookahead !== null);
2928.         switch ($this->lexer->lookahead->type) {
2929.             case Lexer::T_COALESCE:
2930.             case Lexer::T_NULLIF:
2931.             case Lexer::T_CASE:
2932.                 return $this->CaseExpression();
2934.             case Lexer::T_IDENTIFIER:
2935.                 $peek = $this->lexer->glimpse();
2937.                 if ($peek !== null && $peek->value === '(') {
2938.                     return $this->FunctionDeclaration();
2939.                 }
2941.                 if ($peek !== null && $peek->value === '.') {
2942.                     return $this->SingleValuedPathExpression();
2943.                 }
2945.                 if (isset($this->queryComponents[$this->lexer->lookahead->value]['resultVariable'])) {
2946.                     return $this->ResultVariable();
2947.                 }
2949.                 return $this->StateFieldPathExpression();
2951.             case Lexer::T_INPUT_PARAMETER:
2952.                 return $this->InputParameter();
2954.             default:
2955.                 $peek = $this->lexer->glimpse();
2957.                 if ($peek !== null && $peek->value === '(') {
2958.                     return $this->FunctionDeclaration();
2959.                 }
2961.                 return $this->Literal();
2962.         }
2963.     }
2965.     /**
2966.      * StringExpression ::= StringPrimary | ResultVariable | "(" Subselect ")"
2967.      *
2968.      * @return AST\Subselect|AST\Node|string
2969.      */
2970.     public function StringExpression()
2971.     {
2972.         $peek = $this->lexer->glimpse();
2973.         assert($peek !== null);
2975.         // Subselect
2976.         if ($this->lexer->isNextToken(Lexer::T_OPEN_PARENTHESIS) && $peek->type === Lexer::T_SELECT) {
2977.             $this->match(Lexer::T_OPEN_PARENTHESIS);
2978.             $expr = $this->Subselect();
2979.             $this->match(Lexer::T_CLOSE_PARENTHESIS);
2981.             return $expr;
2982.         }
2984.         assert($this->lexer->lookahead !== null);
2985.         // ResultVariable (string)
2986.         if (
2987.             $this->lexer->isNextToken(Lexer::T_IDENTIFIER) &&
2988.             isset($this->queryComponents[$this->lexer->lookahead->value]['resultVariable'])
2989.         ) {
2990.             return $this->ResultVariable();
2991.         }
2993.         return $this->StringPrimary();
2994.     }
2996.     /**
2997.      * StringPrimary ::= StateFieldPathExpression | string | InputParameter | FunctionsReturningStrings | AggregateExpression | CaseExpression
2998.      *
2999.      * @return AST\Node
3000.      */
3001.     public function StringPrimary()
3002.     {
3003.         assert($this->lexer->lookahead !== null);
3004.         $lookaheadType = $this->lexer->lookahead->type;
3006.         switch ($lookaheadType) {
3007.             case Lexer::T_IDENTIFIER:
3008.                 $peek = $this->lexer->glimpse();
3009.                 assert($peek !== null);
3011.                 if ($peek->value === '.') {
3012.                     return $this->StateFieldPathExpression();
3013.                 }
3015.                 if ($peek->value === '(') {
3016.                     // do NOT directly go to FunctionsReturningString() because it doesn't check for custom functions.
3017.                     return $this->FunctionDeclaration();
3018.                 }
3020.                 $this->syntaxError("'.' or '('");
3021.                 break;
3023.             case Lexer::T_STRING:
3024.                 $this->match(Lexer::T_STRING);
3025.                 assert($this->lexer->token !== null);
3027.                 return new AST\Literal(AST\Literal::STRING, $this->lexer->token->value);
3029.             case Lexer::T_INPUT_PARAMETER:
3030.                 return $this->InputParameter();
3032.             case Lexer::T_CASE:
3033.             case Lexer::T_COALESCE:
3034.             case Lexer::T_NULLIF:
3035.                 return $this->CaseExpression();
3037.             default:
3038.                 assert($lookaheadType !== null);
3039.                 if ($this->isAggregateFunction($lookaheadType)) {
3040.                     return $this->AggregateExpression();
3041.                 }
3042.         }
3044.         $this->syntaxError(
3045.             'StateFieldPathExpression | string | InputParameter | FunctionsReturningStrings | AggregateExpression'
3046.         );
3047.     }
3049.     /**
3050.      * EntityExpression ::= SingleValuedAssociationPathExpression | SimpleEntityExpression
3051.      *
3052.      * @return AST\InputParameter|AST\PathExpression
3053.      */
3054.     public function EntityExpression()
3055.     {
3056.         $glimpse = $this->lexer->glimpse();
3057.         assert($glimpse !== null);
3059.         if ($this->lexer->isNextToken(Lexer::T_IDENTIFIER) && $glimpse->value === '.') {
3060.             return $this->SingleValuedAssociationPathExpression();
3061.         }
3063.         return $this->SimpleEntityExpression();
3064.     }
3066.     /**
3067.      * SimpleEntityExpression ::= IdentificationVariable | InputParameter
3068.      *
3069.      * @return AST\InputParameter|AST\PathExpression
3070.      */
3071.     public function SimpleEntityExpression()
3072.     {
3073.         if ($this->lexer->isNextToken(Lexer::T_INPUT_PARAMETER)) {
3074.             return $this->InputParameter();
3075.         }
3077.         return $this->StateFieldPathExpression();
3078.     }
3080.     /**
3081.      * AggregateExpression ::=
3082.      *  ("AVG" | "MAX" | "MIN" | "SUM" | "COUNT") "(" ["DISTINCT"] SimpleArithmeticExpression ")"
3083.      *
3084.      * @return AST\AggregateExpression
3085.      */
3086.     public function AggregateExpression()
3087.     {
3088.         assert($this->lexer->lookahead !== null);
3089.         $lookaheadType = $this->lexer->lookahead->type;
3090.         $isDistinct    = false;
3092.         if (! in_array($lookaheadType, [Lexer::T_COUNT, Lexer::T_AVG, Lexer::T_MAX, Lexer::T_MIN, Lexer::T_SUM], true)) {
3093.             $this->syntaxError('One of: MAX, MIN, AVG, SUM, COUNT');
3094.         }
3096.         $this->match($lookaheadType);
3097.         assert($this->lexer->token !== null);
3098.         $functionName = $this->lexer->token->value;
3099.         $this->match(Lexer::T_OPEN_PARENTHESIS);
3101.         if ($this->lexer->isNextToken(Lexer::T_DISTINCT)) {
3102.             $this->match(Lexer::T_DISTINCT);
3103.             $isDistinct = true;
3104.         }
3106.         $pathExp = $this->SimpleArithmeticExpression();
3108.         $this->match(Lexer::T_CLOSE_PARENTHESIS);
3110.         return new AST\AggregateExpression($functionName, $pathExp, $isDistinct);
3111.     }
3113.     /**
3114.      * QuantifiedExpression ::= ("ALL" | "ANY" | "SOME") "(" Subselect ")"
3115.      *
3116.      * @return AST\QuantifiedExpression
3117.      */
3118.     public function QuantifiedExpression()
3119.     {
3120.         assert($this->lexer->lookahead !== null);
3121.         $lookaheadType = $this->lexer->lookahead->type;
3122.         $value         = $this->lexer->lookahead->value;
3124.         if (! in_array($lookaheadType, [Lexer::T_ALL, Lexer::T_ANY, Lexer::T_SOME], true)) {
3125.             $this->syntaxError('ALL, ANY or SOME');
3126.         }
3128.         $this->match($lookaheadType);
3129.         $this->match(Lexer::T_OPEN_PARENTHESIS);
3131.         $qExpr       = new AST\QuantifiedExpression($this->Subselect());
3132.         $qExpr->type = $value;
3134.         $this->match(Lexer::T_CLOSE_PARENTHESIS);
3136.         return $qExpr;
3137.     }
3139.     /**
3140.      * BetweenExpression ::= ArithmeticExpression ["NOT"] "BETWEEN" ArithmeticExpression "AND" ArithmeticExpression
3141.      *
3142.      * @return AST\BetweenExpression
3143.      */
3144.     public function BetweenExpression()
3145.     {
3146.         $not        = false;
3147.         $arithExpr1 = $this->ArithmeticExpression();
3149.         if ($this->lexer->isNextToken(Lexer::T_NOT)) {
3150.             $this->match(Lexer::T_NOT);
3151.             $not = true;
3152.         }
3154.         $this->match(Lexer::T_BETWEEN);
3155.         $arithExpr2 = $this->ArithmeticExpression();
3156.         $this->match(Lexer::T_AND);
3157.         $arithExpr3 = $this->ArithmeticExpression();
3159.         return new AST\BetweenExpression($arithExpr1, $arithExpr2, $arithExpr3, $not);
3160.     }
3162.     /**
3163.      * ComparisonExpression ::= ArithmeticExpression ComparisonOperator ( QuantifiedExpression | ArithmeticExpression )
3164.      *
3165.      * @return AST\ComparisonExpression
3166.      */
3167.     public function ComparisonExpression()
3168.     {
3169.         $this->lexer->glimpse();
3171.         $leftExpr  = $this->ArithmeticExpression();
3172.         $operator  = $this->ComparisonOperator();
3173.         $rightExpr = $this->isNextAllAnySome()
3174.             ? $this->QuantifiedExpression()
3175.             : $this->ArithmeticExpression();
3177.         return new AST\ComparisonExpression($leftExpr, $operator, $rightExpr);
3178.     }
3180.     /**
3181.      * InExpression ::= SingleValuedPathExpression ["NOT"] "IN" "(" (InParameter {"," InParameter}* | Subselect) ")"
3182.      *
3183.      * @return AST\InListExpression|AST\InSubselectExpression
3184.      */
3185.     public function InExpression()
3186.     {
3187.         $expression = $this->ArithmeticExpression();
3189.         $not = false;
3190.         if ($this->lexer->isNextToken(Lexer::T_NOT)) {
3191.             $this->match(Lexer::T_NOT);
3192.             $not = true;
3193.         }
3195.         $this->match(Lexer::T_IN);
3196.         $this->match(Lexer::T_OPEN_PARENTHESIS);
3198.         if ($this->lexer->isNextToken(Lexer::T_SELECT)) {
3199.             $inExpression = new AST\InSubselectExpression(
3200.                 $expression,
3201.                 $this->Subselect(),
3202.                 $not
3203.             );
3204.         } else {
3205.             $literals = [$this->InParameter()];
3207.             while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
3208.                 $this->match(Lexer::T_COMMA);
3209.                 $literals[] = $this->InParameter();
3210.             }
3212.             $inExpression = new AST\InListExpression(
3213.                 $expression,
3214.                 $literals,
3215.                 $not
3216.             );
3217.         }
3219.         $this->match(Lexer::T_CLOSE_PARENTHESIS);
3221.         return $inExpression;
3222.     }
3224.     /**
3225.      * InstanceOfExpression ::= IdentificationVariable ["NOT"] "INSTANCE" ["OF"] (InstanceOfParameter | "(" InstanceOfParameter {"," InstanceOfParameter}* ")")
3226.      *
3227.      * @return AST\InstanceOfExpression
3228.      */
3229.     public function InstanceOfExpression()
3230.     {
3231.         $identificationVariable = $this->IdentificationVariable();
3233.         $not = false;
3234.         if ($this->lexer->isNextToken(Lexer::T_NOT)) {
3235.             $this->match(Lexer::T_NOT);
3236.             $not = true;
3237.         }
3239.         $this->match(Lexer::T_INSTANCE);
3240.         $this->match(Lexer::T_OF);
3242.         $exprValues = $this->lexer->isNextToken(Lexer::T_OPEN_PARENTHESIS)
3243.             ? $this->InstanceOfParameterList()
3244.             : [$this->InstanceOfParameter()];
3246.         return new AST\InstanceOfExpression(
3247.             $identificationVariable,
3248.             $exprValues,
3249.             $not
3250.         );
3251.     }
3253.     /** @return non-empty-list<AST\InputParameter|string> */
3254.     public function InstanceOfParameterList(): array
3255.     {
3256.         $this->match(Lexer::T_OPEN_PARENTHESIS);
3258.         $exprValues = [$this->InstanceOfParameter()];
3260.         while ($this->lexer->isNextToken(Lexer::T_COMMA)) {
3261.             $this->match(Lexer::T_COMMA);
3263.             $exprValues[] = $this->InstanceOfParameter();
3264.         }
3266.         $this->match(Lexer::T_CLOSE_PARENTHESIS);
3268.         return $exprValues;
3269.     }
3271.     /**
3272.      * InstanceOfParameter ::= AbstractSchemaName | InputParameter
3273.      *
3274.      * @return AST\InputParameter|string
3275.      */
3276.     public function InstanceOfParameter()
3277.     {
3278.         if ($this->lexer->isNextToken(Lexer::T_INPUT_PARAMETER)) {
3279.             $this->match(Lexer::T_INPUT_PARAMETER);
3280.             assert($this->lexer->token !== null);
3282.             return new AST\InputParameter($this->lexer->token->value);
3283.         }
3285.         $abstractSchemaName = $this->AbstractSchemaName();
3287.         $this->validateAbstractSchemaName($abstractSchemaName);
3289.         return $abstractSchemaName;
3290.     }
3292.     /**
3293.      * LikeExpression ::= StringExpression ["NOT"] "LIKE" StringPrimary ["ESCAPE" char]
3294.      *
3295.      * @return AST\LikeExpression
3296.      */
3297.     public function LikeExpression()
3298.     {
3299.         $stringExpr = $this->StringExpression();
3300.         $not        = false;
3302.         if ($this->lexer->isNextToken(Lexer::T_NOT)) {
3303.             $this->match(Lexer::T_NOT);
3304.             $not = true;
3305.         }
3307.         $this->match(Lexer::T_LIKE);
3309.         if ($this->lexer->isNextToken(Lexer::T_INPUT_PARAMETER)) {
3310.             $this->match(Lexer::T_INPUT_PARAMETER);
3311.             assert($this->lexer->token !== null);
3312.             $stringPattern = new AST\InputParameter($this->lexer->token->value);
3313.         } else {
3314.             $stringPattern = $this->StringPrimary();
3315.         }
3317.         $escapeChar = null;
3319.         if ($this->lexer->lookahead !== null && $this->lexer->lookahead->type === Lexer::T_ESCAPE) {
3320.             $this->match(Lexer::T_ESCAPE);
3321.             $this->match(Lexer::T_STRING);
3322.             assert($this->lexer->token !== null);
3324.             $escapeChar = new AST\Literal(AST\Literal::STRING, $this->lexer->token->value);
3325.         }
3327.         return new AST\LikeExpression($stringExpr, $stringPattern, $escapeChar, $not);
3328.     }
3330.     /**
3331.      * NullComparisonExpression ::= (InputParameter | NullIfExpression | CoalesceExpression | AggregateExpression | FunctionDeclaration | IdentificationVariable | SingleValuedPathExpression | ResultVariable) "IS" ["NOT"] "NULL"
3332.      *
3333.      * @return AST\NullComparisonExpression
3334.      */
3335.     public function NullComparisonExpression()
3336.     {
3337.         switch (true) {
3338.             case $this->lexer->isNextToken(Lexer::T_INPUT_PARAMETER):
3339.                 $this->match(Lexer::T_INPUT_PARAMETER);
3340.                 assert($this->lexer->token !== null);
3342.                 $expr = new AST\InputParameter($this->lexer->token->value);
3343.                 break;
3345.             case $this->lexer->isNextToken(Lexer::T_NULLIF):
3346.                 $expr = $this->NullIfExpression();
3347.                 break;
3349.             case $this->lexer->isNextToken(Lexer::T_COALESCE):
3350.                 $expr = $this->CoalesceExpression();
3351.                 break;
3353.             case $this->isFunction():
3354.                 $expr = $this->FunctionDeclaration();
3355.                 break;
3357.             default:
3358.                 // We need to check if we are in a IdentificationVariable or SingleValuedPathExpression
3359.                 $glimpse = $this->lexer->glimpse();
3360.                 assert($glimpse !== null);
3362.                 if ($glimpse->type === Lexer::T_DOT) {
3363.                     $expr = $this->SingleValuedPathExpression();
3365.                     // Leave switch statement
3366.                     break;
3367.                 }
3369.                 assert($this->lexer->lookahead !== null);
3370.                 $lookaheadValue = $this->lexer->lookahead->value;
3372.                 // Validate existing component
3373.                 if (! isset($this->queryComponents[$lookaheadValue])) {
3374.                     $this->semanticalError('Cannot add having condition on undefined result variable.');
3375.                 }
3377.                 // Validate SingleValuedPathExpression (ie.: "product")
3378.                 if (isset($this->queryComponents[$lookaheadValue]['metadata'])) {
3379.                     $expr = $this->SingleValuedPathExpression();
3380.                     break;
3381.                 }
3383.                 // Validating ResultVariable
3384.                 if (! isset($this->queryComponents[$lookaheadValue]['resultVariable'])) {
3385.                     $this->semanticalError('Cannot add having condition on a non result variable.');
3386.                 }
3388.                 $expr = $this->ResultVariable();
3389.                 break;
3390.         }
3392.         $this->match(Lexer::T_IS);
3394.         $not = false;
3395.         if ($this->lexer->isNextToken(Lexer::T_NOT)) {
3396.             $this->match(Lexer::T_NOT);
3398.             $not = true;
3399.         }
3401.         $this->match(Lexer::T_NULL);
3403.         return new AST\NullComparisonExpression($expr, $not);
3404.     }
3406.     /**
3407.      * ExistsExpression ::= ["NOT"] "EXISTS" "(" Subselect ")"
3408.      *
3409.      * @return AST\ExistsExpression
3410.      */
3411.     public function ExistsExpression()
3412.     {
3413.         $not = false;
3415.         if ($this->lexer->isNextToken(Lexer::T_NOT)) {
3416.             $this->match(Lexer::T_NOT);
3417.             $not = true;
3418.         }
3420.         $this->match(Lexer::T_EXISTS);
3421.         $this->match(Lexer::T_OPEN_PARENTHESIS);
3423.         $subselect = $this->Subselect();
3425.         $this->match(Lexer::T_CLOSE_PARENTHESIS);
3427.         return new AST\ExistsExpression($subselect, $not);
3428.     }
3430.     /**
3431.      * ComparisonOperator ::= "=" | "<" | "<=" | "<>" | ">" | ">=" | "!="
3432.      *
3433.      * @return string
3434.      */
3435.     public function ComparisonOperator()
3436.     {
3437.         assert($this->lexer->lookahead !== null);
3438.         switch ($this->lexer->lookahead->value) {
3439.             case '=':
3440.                 $this->match(Lexer::T_EQUALS);
3442.                 return '=';
3444.             case '<':
3445.                 $this->match(Lexer::T_LOWER_THAN);
3446.                 $operator = '<';
3448.                 if ($this->lexer->isNextToken(Lexer::T_EQUALS)) {
3449.                     $this->match(Lexer::T_EQUALS);
3450.                     $operator .= '=';
3451.                 } elseif ($this->lexer->isNextToken(Lexer::T_GREATER_THAN)) {
3452.                     $this->match(Lexer::T_GREATER_THAN);
3453.                     $operator .= '>';
3454.                 }
3456.                 return $operator;
3458.             case '>':
3459.                 $this->match(Lexer::T_GREATER_THAN);
3460.                 $operator = '>';
3462.                 if ($this->lexer->isNextToken(Lexer::T_EQUALS)) {
3463.                     $this->match(Lexer::T_EQUALS);
3464.                     $operator .= '=';
3465.                 }
3467.                 return $operator;
3469.             case '!':
3470.                 $this->match(Lexer::T_NEGATE);
3471.                 $this->match(Lexer::T_EQUALS);
3473.                 return '<>';
3475.             default:
3476.                 $this->syntaxError('=, <, <=, <>, >, >=, !=');
3477.         }
3478.     }
3480.     /**
3481.      * FunctionDeclaration ::= FunctionsReturningStrings | FunctionsReturningNumerics | FunctionsReturningDatetime
3482.      *
3483.      * @return Functions\FunctionNode
3484.      */
3485.     public function FunctionDeclaration()
3486.     {
3487.         assert($this->lexer->lookahead !== null);
3488.         $token    = $this->lexer->lookahead;
3489.         $funcName = strtolower($token->value);
3491.         $customFunctionDeclaration = $this->CustomFunctionDeclaration();
3493.         // Check for custom functions functions first!
3494.         switch (true) {
3495.             case $customFunctionDeclaration !== null:
3496.                 return $customFunctionDeclaration;
3498.             case isset(self::$stringFunctions[$funcName]):
3499.                 return $this->FunctionsReturningStrings();
3501.             case isset(self::$numericFunctions[$funcName]):
3502.                 return $this->FunctionsReturningNumerics();
3504.             case isset(self::$datetimeFunctions[$funcName]):
3505.                 return $this->FunctionsReturningDatetime();
3507.             default:
3508.                 $this->syntaxError('known function', $token);
3509.         }
3510.     }
3512.     /**
3513.      * Helper function for FunctionDeclaration grammar rule.
3514.      */
3515.     private function CustomFunctionDeclaration(): ?Functions\FunctionNode
3516.     {
3517.         assert($this->lexer->lookahead !== null);
3518.         $token    = $this->lexer->lookahead;
3519.         $funcName = strtolower($token->value);
3521.         // Check for custom functions afterwards
3522.         $config = $this->em->getConfiguration();
3524.         switch (true) {
3525.             case $config->getCustomStringFunction($funcName) !== null:
3526.                 return $this->CustomFunctionsReturningStrings();
3528.             case $config->getCustomNumericFunction($funcName) !== null:
3529.                 return $this->CustomFunctionsReturningNumerics();
3531.             case $config->getCustomDatetimeFunction($funcName) !== null:
3532.                 return $this->CustomFunctionsReturningDatetime();
3534.             default:
3535.                 return null;
3536.         }
3537.     }
3539.     /**
3540.      * FunctionsReturningNumerics ::=
3541.      *      "LENGTH" "(" StringPrimary ")" |
3542.      *      "LOCATE" "(" StringPrimary "," StringPrimary ["," SimpleArithmeticExpression]")" |
3543.      *      "ABS" "(" SimpleArithmeticExpression ")" |
3544.      *      "SQRT" "(" SimpleArithmeticExpression ")" |
3545.      *      "MOD" "(" SimpleArithmeticExpression "," SimpleArithmeticExpression ")" |
3546.      *      "SIZE" "(" CollectionValuedPathExpression ")" |
3547.      *      "DATE_DIFF" "(" ArithmeticPrimary "," ArithmeticPrimary ")" |
3548.      *      "BIT_AND" "(" ArithmeticPrimary "," ArithmeticPrimary ")" |
3549.      *      "BIT_OR" "(" ArithmeticPrimary "," ArithmeticPrimary ")"
3550.      *
3551.      * @return Functions\FunctionNode
3552.      */
3553.     public function FunctionsReturningNumerics()
3554.     {
3555.         assert($this->lexer->lookahead !== null);
3556.         $funcNameLower = strtolower($this->lexer->lookahead->value);
3557.         $funcClass     = self::$numericFunctions[$funcNameLower];
3559.         $function = new $funcClass($funcNameLower);
3560.         $function->parse($this);
3562.         return $function;
3563.     }
3565.     /** @return Functions\FunctionNode */
3566.     public function CustomFunctionsReturningNumerics()
3567.     {
3568.         assert($this->lexer->lookahead !== null);
3569.         // getCustomNumericFunction is case-insensitive
3570.         $functionName  = strtolower($this->lexer->lookahead->value);
3571.         $functionClass = $this->em->getConfiguration()->getCustomNumericFunction($functionName);
3573.         assert($functionClass !== null);
3575.         $function = is_string($functionClass)
3576.             ? new $functionClass($functionName)
3577.             : $functionClass($functionName);
3579.         $function->parse($this);
3581.         return $function;
3582.     }
3584.     /**
3585.      * FunctionsReturningDateTime ::=
3586.      *     "CURRENT_DATE" |
3587.      *     "CURRENT_TIME" |
3588.      *     "CURRENT_TIMESTAMP" |
3589.      *     "DATE_ADD" "(" ArithmeticPrimary "," ArithmeticPrimary "," StringPrimary ")" |
3590.      *     "DATE_SUB" "(" ArithmeticPrimary "," ArithmeticPrimary "," StringPrimary ")"
3591.      *
3592.      * @return Functions\FunctionNode
3593.      */
3594.     public function FunctionsReturningDatetime()
3595.     {
3596.         assert($this->lexer->lookahead !== null);
3597.         $funcNameLower = strtolower($this->lexer->lookahead->value);
3598.         $funcClass     = self::$datetimeFunctions[$funcNameLower];
3600.         $function = new $funcClass($funcNameLower);
3601.         $function->parse($this);
3603.         return $function;
3604.     }
3606.     /** @return Functions\FunctionNode */
3607.     public function CustomFunctionsReturningDatetime()
3608.     {
3609.         assert($this->lexer->lookahead !== null);
3610.         // getCustomDatetimeFunction is case-insensitive
3611.         $functionName  = $this->lexer->lookahead->value;
3612.         $functionClass = $this->em->getConfiguration()->getCustomDatetimeFunction($functionName);
3614.         assert($functionClass !== null);
3616.         $function = is_string($functionClass)
3617.             ? new $functionClass($functionName)
3618.             : $functionClass($functionName);
3620.         $function->parse($this);
3622.         return $function;
3623.     }
3625.     /**
3626.      * FunctionsReturningStrings ::=
3627.      *   "CONCAT" "(" StringPrimary "," StringPrimary {"," StringPrimary}* ")" |
3628.      *   "SUBSTRING" "(" StringPrimary "," SimpleArithmeticExpression "," SimpleArithmeticExpression ")" |
3629.      *   "TRIM" "(" [["LEADING" | "TRAILING" | "BOTH"] [char] "FROM"] StringPrimary ")" |
3630.      *   "LOWER" "(" StringPrimary ")" |
3631.      *   "UPPER" "(" StringPrimary ")" |
3632.      *   "IDENTITY" "(" SingleValuedAssociationPathExpression {"," string} ")"
3633.      *
3634.      * @return Functions\FunctionNode
3635.      */
3636.     public function FunctionsReturningStrings()
3637.     {
3638.         assert($this->lexer->lookahead !== null);
3639.         $funcNameLower = strtolower($this->lexer->lookahead->value);
3640.         $funcClass     = self::$stringFunctions[$funcNameLower];
3642.         $function = new $funcClass($funcNameLower);
3643.         $function->parse($this);
3645.         return $function;
3646.     }
3648.     /** @return Functions\FunctionNode */
3649.     public function CustomFunctionsReturningStrings()
3650.     {
3651.         assert($this->lexer->lookahead !== null);
3652.         // getCustomStringFunction is case-insensitive
3653.         $functionName  = $this->lexer->lookahead->value;
3654.         $functionClass = $this->em->getConfiguration()->getCustomStringFunction($functionName);
3656.         assert($functionClass !== null);
3658.         $function = is_string($functionClass)
3659.             ? new $functionClass($functionName)
3660.             : $functionClass($functionName);
3662.         $function->parse($this);
3664.         return $function;
3665.     }
3667.     private function getMetadataForDqlAlias(string $dqlAlias): ClassMetadata
3668.     {
3669.         if (! isset($this->queryComponents[$dqlAlias]['metadata'])) {
3670.             throw new LogicException(sprintf('No metadata for DQL alias: %s', $dqlAlias));
3671.         }
3673.         return $this->queryComponents[$dqlAlias]['metadata'];
3674.     }
3675. }