[JsonPath] Better handling of Unicode chars in expressions

Author: alexandre-daubois

JsonCrawler.php

@@ -230,7 +230,7 @@ private function evaluateBracket(string $expr, mixed $value): array
 
         // quoted strings for object keys
         if (preg_match('/^([\'"])(.*)\1$/', $expr, $matches)) {
-            $key = stripslashes($matches[2]);
+            $key = JsonPathUtils::unescapeString($matches[2], $matches[1]);
 
             return \array_key_exists($key, $value) ? [$value[$key]] : [];
         }
@@ -335,7 +335,7 @@ private function evaluateScalar(string $expr, array $context): mixed
 
         // string literals
         if (preg_match('/^([\'"])(.*)\1$/', $expr, $matches)) {
-            return $matches[2];
+            return JsonPathUtils::unescapeString($matches[2], $matches[1]);
         }
 
         // current node references

JsonCrawlerInterface.php

@@ -25,7 +25,7 @@ interface JsonCrawlerInterface
      * @return list<array|string|float|int|bool|null>
      *
      * @throws InvalidArgumentException When the JSON string provided to the crawler cannot be decoded
-     * @throws JsonCrawlerException When a syntax error occurs in the provided JSON path
+     * @throws JsonCrawlerException     When a syntax error occurs in the provided JSON path
      */
     public function find(string|JsonPath $query): array;
 }

JsonPath.php

@@ -92,12 +92,12 @@ private function escapeKey(string $key): string
             "\r" => '\\r',
             "\t" => '\\t',
             "\b" => '\\b',
-            "\f" => '\\f'
+            "\f" => '\\f',
         ]);
 
-        for ($i = 0; $i <= 31; $i++) {
+        for ($i = 0; $i <= 31; ++$i) {
             if ($i < 8 || $i > 13) {
-                $key = str_replace(chr($i), sprintf('\\u%04x', $i), $key);
+                $key = str_replace(\chr($i), \sprintf('\\u%04x', $i), $key);
             }
         }
 

JsonPathUtils.php

@@ -85,4 +85,78 @@ public static function findSmallestDeserializableStringAndPath(array $tokens, mi
             'tokens' => $remainingTokens,
         ];
     }
+
+    public static function unescapeString(string $str, string $quoteChar): string
+    {
+        if ('"' === $quoteChar) {
+            // try JSON decoding first for unicode sequences
+            $jsonStr = '"'.$str.'"';
+            $decoded = json_decode($jsonStr, true);
+
+            if (null !== $decoded) {
+                return $decoded;
+            }
+        }
+
+        $result = '';
+        $length = \strlen($str);
+
+        for ($i = 0; $i < $length; ++$i) {
+            if ('\\' === $str[$i] && $i + 1 < $length) {
+                $result .= match ($str[$i + 1]) {
+                    '"' => '"',
+                    "'" => "'",
+                    '\\' => '\\',
+                    '/' => '/',
+                    'b' => "\b",
+                    'f' => "\f",
+                    'n' => "\n",
+                    'r' => "\r",
+                    't' => "\t",
+                    'u' => self::unescapeUnicodeSequence($str, $length, $i),
+                    default => $str[$i].$str[$i + 1], // keep the backslash
+                };
+
+                ++$i;
+            } else {
+                $result .= $str[$i];
+            }
+        }
+
+        return $result;
+    }
+
+    private static function unescapeUnicodeSequence(string $str, int $length, int &$i): string
+    {
+        if ($i + 5 >= $length) {
+            // not enough characters for Unicode escape, treat as literal
+            return $str[$i];
+        }
+
+        $hex = substr($str, $i + 2, 4);
+        if (!ctype_xdigit($hex)) {
+            // invalid hex, treat as literal
+            return $str[$i];
+        }
+
+        $codepoint = hexdec($hex);
+        // looks like a valid Unicode codepoint, string length is sufficient and it starts with \u
+        if (0xD800 <= $codepoint && $codepoint <= 0xDBFF && $i + 11 < $length && '\\' === $str[$i + 6] && 'u' === $str[$i + 7]) {
+            $lowHex = substr($str, $i + 8, 4);
+            if (ctype_xdigit($lowHex)) {
+                $lowSurrogate = hexdec($lowHex);
+                if (0xDC00 <= $lowSurrogate && $lowSurrogate <= 0xDFFF) {
+                    $codepoint = 0x10000 + (($codepoint & 0x3FF) << 10) + ($lowSurrogate & 0x3FF);
+                    $i += 10; // skip surrogate pair
+
+                    return mb_chr($codepoint, 'UTF-8');
+                }
+            }
+        }
+
+        // single Unicode character or invalid surrogate, skip the sequence
+        $i += 4;
+
+        return mb_chr($codepoint, 'UTF-8');
+    }
 }