minor symfony#61749 [JsonPath] Add Nothing enum to support special nothing value (alexandre-daubois)

This PR was merged into the 7.3 branch.

Discussion
----------

[JsonPath] Add `Nothing` enum to support special nothing value

| Q             | A
| ------------- | ---
| Branch?       | 7.3
| Bug fix?      | no
| New feature?  | no
| Deprecations? | no
| Issues        | -
| License       | MIT

symfony#61517 introduces custom functions mechanism. For consistency, RFC built-in functions will also use the new functions mechanism. In order to fully work, functions must be able to return the special `nothing` value defined by the RFC. This PR exposes the Nothing enum to the public API instead of storing it internally in the JsonCrawler with stdClass.

Context: symfony#61517 (comment)

Commits
-------

dc4d528 [JsonPath] Add `Nothing` enum to support special nothing value

Author: nicolas-grekas

src/Symfony/Component/JsonPath/JsonCrawler.php

@@ -722,12 +722,12 @@ private function evaluateScalar(string $expr, mixed $context): mixed
                 $bracketContent = substr($path, 1, -1);
                 $result = $this->evaluateBracket($bracketContent, $context);
 
-                return $result ? $result[0] : self::nothing();
+                return $result ? $result[0] : Nothing::Nothing;
             }
 
             $results = $this->evaluateTokensOnDecodedData(JsonPathTokenizer::tokenize(new JsonPath('$'.$path)), $context);
 
-            return $results ? $results[0] : self::nothing();
+            return $results ? $results[0] : Nothing::Nothing;
         }
 
         // function calls
@@ -785,7 +785,7 @@ private function evaluateFunction(string $name, string $args, mixed $context): m
                 \is_string($value) => mb_strlen($value),
                 \is_array($value) => \count($value),
                 $value instanceof \stdClass => \count(get_object_vars($value)),
-                default => self::nothing(),
+                default => Nothing::Nothing,
             },
             'count' => $nodelistSize,
             'match' => match (true) {
@@ -796,7 +796,7 @@ private function evaluateFunction(string $name, string $args, mixed $context): m
                 \is_string($value) && \is_string($argList[1] ?? null) => (bool) @preg_match("/{$this->transformJsonPathRegex($argList[1])}/u", $value),
                 default => false,
             },
-            'value' => 1 < $nodelistSize ? self::nothing() : (1 === $nodelistSize ? (\is_array($value) ? ($value[0] ?? null) : $value) : $value),
+            'value' => 1 < $nodelistSize ? Nothing::Nothing : (1 === $nodelistSize ? (\is_array($value) ? ($value[0] ?? null) : $value) : $value),
             default => null,
         };
     }
@@ -833,8 +833,8 @@ private function compare(mixed $left, mixed $right, string $operator): bool
 
     private function compareEquality(mixed $left, mixed $right): bool
     {
-        $leftIsNothing = $left === self::nothing();
-        $rightIsNothing = $right === self::nothing();
+        $leftIsNothing = $left === Nothing::Nothing;
+        $rightIsNothing = $right === Nothing::Nothing;
 
         if (
             $leftIsNothing && $rightIsNothing
@@ -1103,11 +1103,6 @@ private function isValidMixedBracketExpression(string $expr): bool
         return $hasFilter && $validMixed && 1 < \count($parts);
     }
 
-    private static function nothing(): \stdClass
-    {
-        return self::$nothing ??= new \stdClass();
-    }
-
     private function getValueIfKeyExists(mixed $value, string $key): array
     {
         return $this->isArrayOrObject($value) && \array_key_exists($key, $arrayValue = (array) $value) ? [$arrayValue[$key]] : [];

src/Symfony/Component/JsonPath/Nothing.php

@@ -0,0 +1,17 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\JsonPath;
+
+enum Nothing
+{
+    case Nothing;
+}