feat: implement feature parity with jsonpath-js 0.3.0

composer.json

@@ -33,6 +33,8 @@
             "src/parsers/filter-selector.php",
             "src/types/nothing.php",
             "src/types/node.php",
+            "src/types/path-result.php",
+            "src/types/path-segments-result.php",
             "src/PeggyParser.php",
             "src/parser.php",
             "src/JsonPath.php",

package.json

@@ -1,10 +1,10 @@
 {
   "type": "module",
   "dependencies": {
-    "@prettier/plugin-php": "^0.22.4",
+    "@prettier/plugin-php": "^0.24.0",
     "peggy": "^3.0.2",
     "phpeggy": "^2.0.1",
-    "prettier": "^3.5.1"
+    "prettier": "^3.8.1"
   },
   "scripts": {
     "generate-parser": "node src/grammar/generate.js",

readme.md

@@ -38,18 +38,85 @@ $result = $query->find([
 	],
 ]);
 
-var_dump($result);
+print_r($result);
 
 /*
 Prints:
 
-array(2) {
-  [0]=>
-  string(8) "John Doe"
-  [1]=>
-  string(8) "Jane Doe"
-}
+Array
+(
+	[0] => John Doe
+	[1] => Jane Doe
+)
 */
+
+$path_result = $query->paths([
+	'users' => [
+		[ 'name' => 'John Doe' ],
+		[ 'name' => 'Jane Doe' ],
+	],
+]);
+
+print_r($path_result);
+
+/*
+Prints:
+
+Array
+(
+	[0] => Loilo\JsonPath\PathResult Object
+		(
+			[value] => John Doe
+			[path] => $['users'][0]['name']
+		)
+
+	[1] => Loilo\JsonPath\PathResult Object
+		(
+			[value] => Jane Doe
+			[path] => $['users'][1]['name']
+		)
+)
+*/
+
+
+$path_segments_result = $query->path_segments([
+	'users' => [
+		[ 'name' => 'John Doe' ],
+		[ 'name' => 'Jane Doe' ],
+	],
+]);
+
+print_r($path_segments_result);
+
+/*
+Prints:
+
+Array
+(
+	[0] => Loilo\JsonPath\PathSegmentsResult Object
+		(
+			[value] => John Doe
+			[segments] => Array
+				(
+					[0] => users
+					[1] => 0
+					[2] => name
+				)
+		)
+
+	[1] => Loilo\JsonPath\PathSegmentsResult Object
+		(
+			[value] => Jane Doe
+			[segments] => Array
+				(
+					[0] => users
+					[1] => 1
+					[2] => name
+				)
+		)
+)
+*/
+
 ```
 
 ## Development

src/JsonPath.php

@@ -2,31 +2,86 @@
 
 namespace Loilo\JsonPath;
 
+/**
+ * A JSONPath query engine for executing JSONPath queries against JSON data.
+ * Fully implements the RFC 9535 JSONPath specification.
+ */
 class JsonPath
 {
 	private $root_node;
 
-	public function __construct(private $query)
+	/**
+	 * Creates a new JSONPath query instance.
+	 * @param string $query The JSONPath query string to parse
+	 * @throws \Exception Throws an error if the query string is invalid
+	 */
+	public function __construct(private string $query)
 	{
 		$parser = new PeggyParser();
 		$parse_result = $parser->parse($query);
 		$this->root_node = $parse_result;
 	}
 
-	public function find($json)
+	/**
+	 * Executes the JSONPath query and returns only the matching values.
+	 * @param mixed $json The JSON data to query against
+	 * @return array An array of matching values
+	 */
+	public function find($json): array
 	{
 		$result_node_list = run($json, $this->root_node);
 		return array_map(fn(Node $node) => $node->value, $result_node_list);
 	}
 
-	public function paths($json)
+	protected function convert_path_segment_to_string($segment)
+	{
+		if (is_string($segment)) {
+			if ($segment === '$') {
+				return $segment;
+			}
+
+			return "['{$segment}']";
+		}
+
+		return "[{$segment}]";
+	}
+
+	/**
+	 * Executes the JSONPath query and returns both matching values and their JSONPath strings.
+	 * @param mixed $json The JSON data to query against
+	 * @return array An array of objects containing the matching value and its JSONPath string
+	 */
+	public function paths($json): array
+	{
+		$path_segments = $this->path_segments($json);
+		return array_map(
+			fn($result) => new PathResult(
+				$result->value,
+				'$' .
+					join(
+						'',
+						array_map(
+							fn($result) => $this->convert_path_segment_to_string($result),
+							$result->segments,
+						),
+					),
+			),
+			$path_segments,
+		);
+	}
+
+	/**
+	 * Executes the JSONPath query and returns both matching values and their path segments as arrays.
+	 * Path segments are returned as arrays containing strings (for object keys) and numbers (for array indices).
+	 * The root segment $ is not included in path segments.
+	 * @param mixed $json The JSON data to query against
+	 * @return PathSegmentsResult[] An array of objects containing the matching value and its path segments as an array
+	 */
+	public function path_segments($json): array
 	{
 		$result_node_list = run($json, $this->root_node);
 		return array_map(
-			fn(Node $node) => [
-				'value' => $node->value,
-				'path' => $node->path,
-			],
+			fn(Node $node) => new PathSegmentsResult($node->value, array_slice($node->path, 1)),
 			$result_node_list,
 		);
 	}

src/parser.php

@@ -4,6 +4,6 @@
 
 function run($json, $query): array
 {
-	$root_node = create_node($json, '$');
+	$root_node = create_node($json, ['$']);
 	return apply_root($query, $root_node);
 }

src/types/node.php

@@ -6,10 +6,12 @@
 
 class Node
 {
-	public function __construct(public mixed $value, public string $path) {}
+	public function __construct(public mixed $value, public array $path)
+	{
+	}
 }
 
-function create_node(mixed $json, string $path): Node
+function create_node(mixed $json, array $path): Node
 {
 	return new Node($json, $path);
 }
@@ -18,12 +20,12 @@ function add_member_path(Node $base, mixed $new_value, string $member_name): Nod
 {
 	$escaped_member_name = escape_member_name($member_name);
 
-	return create_node($new_value, "{$base->path}['{$escaped_member_name}']");
+	return create_node($new_value, [...$base->path, $escaped_member_name]);
 }
 
 function add_index_path(Node $base, mixed $new_value, int $index): Node
 {
-	return create_node($new_value, "{$base->path}[{$index}]");
+	return create_node($new_value, [...$base->path, $index]);
 }
 
 function is_node($node)

src/types/path-result.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Loilo\JsonPath;
+
+class PathResult
+{
+	public function __construct(public mixed $value, public string $path) {}
+}

src/types/path-segments-result.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Loilo\JsonPath;
+
+class PathSegmentsResult
+{
+	public function __construct(
+		public mixed $value,
+		/**
+		 * @var string[]
+		 */
+		public array $segments
+	) {}
+}

tests/PathSegmentsTest.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+use Loilo\JsonPath\JsonPath;
+
+$book_1 = [
+	'category' => 'reference',
+	'author' => 'Nigel Rees',
+	'title' => 'Sayings of the Century',
+	'price' => 8.95,
+];
+
+$book_2 = [
+	'category' => 'fiction',
+	'author' => 'Evelyn Waugh',
+	'title' => 'Sword of Honour',
+	'price' => 12.99,
+];
+
+$json = [
+	'store' => [
+		'book' => [$book_1, $book_2],
+	],
+];
+
+it(
+	'should return path segments as arrays of strings and numbers',
+	function () use ($json) {
+		$path = new JsonPath("$.store.book[*].author");
+		$path_segments_list = array_map(
+			fn($result) => $result->segments,
+			$path->path_segments($json),
+		);
+
+		expect($path_segments_list[0])->toEqual(['store', 'book', 0, 'author']);
+		expect($path_segments_list[1])->toEqual(['store', 'book', 1, 'author']);
+	},
+);
+
+it('should return empty segments for root segment', function () use ($json) {
+	$path = new JsonPath("$");
+	$path_segments_list = array_map(
+		fn($result) => $result->segments,
+		$path->path_segments($json),
+	);
+
+	expect($path_segments_list[0])->toEqual([]);
+});