[ExpressionLanguage] Add more configurability to the parsing/linting methods

Author: fabpot

src/Symfony/Component/ExpressionLanguage/CHANGELOG.md

@@ -5,6 +5,8 @@ CHANGELOG
 ---
 
  * Add support for PHP `min` and `max` functions
+ * Add `Parser::IGNORE_UNKNOWN_VARIABLES` and `Parser::IGNORE_UNKNOWN_FUNCTIONS` to control whether
+   parsing and linting should check for unknown variables and functions.
 
 7.0
 ---

src/Symfony/Component/ExpressionLanguage/ExpressionLanguage.php

@@ -62,7 +62,7 @@ public function evaluate(Expression|string $expression, array $values = []): mix
     /**
      * Parses an expression.
      */
-    public function parse(Expression|string $expression, array $names): ParsedExpression
+    public function parse(Expression|string $expression, array $names, int $checks = 0): ParsedExpression
     {
         if ($expression instanceof ParsedExpression) {
             return $expression;
@@ -78,7 +78,7 @@ public function parse(Expression|string $expression, array $names): ParsedExpres
         $cacheItem = $this->cache->getItem(rawurlencode($expression.'//'.implode('|', $cacheKeyItems)));
 
         if (null === $parsedExpression = $cacheItem->get()) {
-            $nodes = $this->getParser()->parse($this->getLexer()->tokenize((string) $expression), $names);
+            $nodes = $this->getParser()->parse($this->getLexer()->tokenize((string) $expression), $names, $checks);
             $parsedExpression = new ParsedExpression((string) $expression, $nodes);
 
             $cacheItem->set($parsedExpression);
@@ -95,13 +95,20 @@ public function parse(Expression|string $expression, array $names): ParsedExpres
      *
      * @throws SyntaxError When the passed expression is invalid
      */
-    public function lint(Expression|string $expression, ?array $names): void
+    public function lint(Expression|string $expression, ?array $names, int $checks = 0): void
     {
+        if (null === $names) {
+            trigger_deprecation('symfony/expression-language', '7.1', 'Passing "null" as the second argument of "%s()" is deprecated, pass "self::IGNORE_UNKNOWN_VARIABLES" instead as a third argument.', __METHOD__);
+
+            $checks |= Parser::IGNORE_UNKNOWN_VARIABLES;
+            $names = [];
+        }
+
         if ($expression instanceof ParsedExpression) {
             return;
         }
 
-        $this->getParser()->lint($this->getLexer()->tokenize((string) $expression), $names);
+        $this->getParser()->lint($this->getLexer()->tokenize((string) $expression), $names, $checks);
     }
 
     /**

src/Symfony/Component/ExpressionLanguage/Parser.php

@@ -26,11 +26,14 @@ class Parser
     public const OPERATOR_LEFT = 1;
     public const OPERATOR_RIGHT = 2;
 
+    public const IGNORE_UNKNOWN_VARIABLES = 1;
+    public const IGNORE_UNKNOWN_FUNCTIONS = 2;
+
     private TokenStream $stream;
     private array $unaryOperators;
     private array $binaryOperators;
-    private ?array $names;
-    private bool $lint = false;
+    private array $names;
+    private int $checks = 0;
 
     public function __construct(
         private array $functions,
@@ -87,34 +90,43 @@ public function __construct(
      * variable 'container' can be used in the expression
      * but the compiled code will use 'this'.
      *
+     * @param int $checks A bit field of `Parser::IGNORE_UNKNOWN_VARIABLES` and `Parser::IGNORE_UNKNOWN_FUNCTIONS`
+     *
      * @throws SyntaxError
      */
-    public function parse(TokenStream $stream, array $names = []): Node\Node
+    public function parse(TokenStream $stream, array $names = [], int $checks = 0): Node\Node
     {
-        $this->lint = false;
-
-        return $this->doParse($stream, $names);
+        return $this->doParse($stream, $names, $checks);
     }
 
     /**
      * Validates the syntax of an expression.
      *
      * The syntax of the passed expression will be checked, but not parsed.
-     * If you want to skip checking dynamic variable names, pass `null` instead of the array.
+     * If you want to skip checking dynamic variable names, pass `Parser::IGNORE_UNKNOWN_VARIABLES` instead of the array.
+     *
+     * @param int $checks A bit field of `Parser::IGNORE_UNKNOWN_VARIABLES` and `Parser::IGNORE_UNKNOWN_FUNCTIONS`
      *
      * @throws SyntaxError When the passed expression is invalid
      */
-    public function lint(TokenStream $stream, ?array $names = []): void
+    public function lint(TokenStream $stream, ?array $names = [], int $checks = 0): void
     {
-        $this->lint = true;
-        $this->doParse($stream, $names);
+        if (null === $names) {
+            trigger_deprecation('symfony/expression-language', '7.1', 'Passing "null" as the second argument of "%s()" is deprecated, pass "self::IGNORE_UNKNOWN_VARIABLES" instead as a third argument.', __METHOD__);
+
+            $checks |= self::IGNORE_UNKNOWN_VARIABLES;
+            $names = [];
+        }
+
+        $this->doParse($stream, $names, $checks);
     }
 
     /**
      * @throws SyntaxError
      */
-    private function doParse(TokenStream $stream, ?array $names = []): Node\Node
+    private function doParse(TokenStream $stream, array $names, int $checks): Node\Node
     {
+        $this->checks = $checks;
         $this->stream = $stream;
         $this->names = $names;
 
@@ -224,13 +236,13 @@ public function parsePrimaryExpression(): Node\Node
 
                     default:
                         if ('(' === $this->stream->current->value) {
-                            if (false === isset($this->functions[$token->value])) {
+                            if (!($this->checks & self::IGNORE_UNKNOWN_FUNCTIONS) && false === isset($this->functions[$token->value])) {
                                 throw new SyntaxError(sprintf('The function "%s" does not exist.', $token->value), $token->cursor, $this->stream->getExpression(), $token->value, array_keys($this->functions));
                             }
 
                             $node = new Node\FunctionNode($token->value, $this->parseArguments());
                         } else {
-                            if (!$this->lint || \is_array($this->names)) {
+                            if (!($this->checks & self::IGNORE_UNKNOWN_VARIABLES)) {
                                 if (!\in_array($token->value, $this->names, true)) {
                                     throw new SyntaxError(sprintf('Variable "%s" is not valid.', $token->value), $token->cursor, $this->stream->getExpression(), $token->value, $this->names);
                                 }

src/Symfony/Component/ExpressionLanguage/Tests/ExpressionLanguageTest.php

@@ -461,7 +461,7 @@ public function testRegisterAfterCompile($registerCallback)
     public function testLintDoesntThrowOnValidExpression()
     {
         $el = new ExpressionLanguage();
-        $el->lint('1 + 1', null);
+        $el->lint('1 + 1', []);
 
         $this->expectNotToPerformAssertions();
     }

src/Symfony/Component/ExpressionLanguage/Tests/ParserTest.php

@@ -295,7 +295,7 @@ public function testNameProposal()
     /**
      * @dataProvider getLintData
      */
-    public function testLint($expression, $names, ?string $exception = null)
+    public function testLint($expression, $names, int $checks = 0, ?string $exception = null)
     {
         if ($exception) {
             $this->expectException(SyntaxError::class);
@@ -304,7 +304,7 @@ public function testLint($expression, $names, ?string $exception = null)
 
         $lexer = new Lexer();
         $parser = new Parser([]);
-        $parser->lint($lexer->tokenize($expression), $names);
+        $parser->lint($lexer->tokenize($expression), $names, $checks);
 
         // Parser does't return anything when the correct expression is passed
         $this->expectNotToPerformAssertions();
@@ -323,7 +323,8 @@ public static function getLintData(): array
             ],
             'allow expression without names' => [
                 'expression' => 'foo.bar',
-                'names' => null,
+                'names' => [],
+                'checks' => Parser::IGNORE_UNKNOWN_VARIABLES,
             ],
             'array with trailing comma' => [
                 'expression' => '[value1, value2, value3,]',
@@ -336,6 +337,7 @@ public static function getLintData(): array
             'disallow expression without names' => [
                 'expression' => 'foo.bar',
                 'names' => [],
+                'checks' => 0,
                 'exception' => 'Variable "foo" is not valid around position 1 for expression `foo.bar',
             ],
             'operator collisions' => [
@@ -345,57 +347,67 @@ public static function getLintData(): array
             'incorrect expression ending' => [
                 'expression' => 'foo["a"] foo["b"]',
                 'names' => ['foo'],
+                'checks' => 0,
                 'exception' => 'Unexpected token "name" of value "foo" '.
                     'around position 10 for expression `foo["a"] foo["b"]`.',
             ],
             'incorrect operator' => [
                 'expression' => 'foo["some_key"] // 2',
                 'names' => ['foo'],
+                'checks' => 0,
                 'exception' => 'Unexpected token "operator" of value "/" '.
                     'around position 18 for expression `foo["some_key"] // 2`.',
             ],
             'incorrect array' => [
                 'expression' => '[value1, value2 value3]',
                 'names' => ['value1', 'value2', 'value3'],
+                'checks' => 0,
                 'exception' => 'An array element must be followed by a comma. '.
                     'Unexpected token "name" of value "value3" ("punctuation" expected with value ",") '.
                     'around position 17 for expression `[value1, value2 value3]`.',
             ],
             'incorrect array element' => [
                 'expression' => 'foo["some_key")',
                 'names' => ['foo'],
+                'checks' => 0,
                 'exception' => 'Unclosed "[" around position 3 for expression `foo["some_key")`.',
             ],
             'incorrect hash key' => [
                 'expression' => '{+: value1}',
                 'names' => ['value1'],
+                'checks' => 0,
                 'exception' => 'A hash key must be a quoted string, a number, a name, or an expression enclosed in parentheses (unexpected token "operator" of value "+" around position 2 for expression `{+: value1}`.',
             ],
             'missed array key' => [
                 'expression' => 'foo[]',
                 'names' => ['foo'],
+                'checks' => 0,
                 'exception' => 'Unexpected token "punctuation" of value "]" around position 5 for expression `foo[]`.',
             ],
             'missed closing bracket in sub expression' => [
                 'expression' => 'foo[(bar ? bar : "default"]',
                 'names' => ['foo', 'bar'],
+                'checks' => 0,
                 'exception' => 'Unclosed "(" around position 4 for expression `foo[(bar ? bar : "default"]`.',
             ],
             'incorrect hash following' => [
                 'expression' => '{key: foo key2: bar}',
                 'names' => ['foo', 'bar'],
+                'checks' => 0,
                 'exception' => 'A hash value must be followed by a comma. '.
                     'Unexpected token "name" of value "key2" ("punctuation" expected with value ",") '.
                     'around position 11 for expression `{key: foo key2: bar}`.',
             ],
             'incorrect hash assign' => [
                 'expression' => '{key => foo}',
                 'names' => ['foo'],
+                'checks' => 0,
                 'exception' => 'Unexpected character "=" around position 5 for expression `{key => foo}`.',
             ],
             'incorrect array as hash using' => [
                 'expression' => '[foo: foo]',
                 'names' => ['foo'],
+                'checks' => 0,
                 'exception' => 'An array element must be followed by a comma. '.
                     'Unexpected token "punctuation" of value ":" ("punctuation" expected with value ",") '.
                     'around position 5 for expression `[foo: foo]`.',