README

jsonpath-php

An implementation of RFC 9535 JSONPath

This is a PHP implementation of JSONPath, a query language for JSON. It aims for 100% compatibilty with the JSONPath syntax standardized in RFC 9535.

Currently, this library passes 99% of the work-in-progress JSONPath Compliance Test Suite (with the test suite version on Feb 21, 2025). All of the the missing 1% are UTF-16 related tests, which should not affect most day-to-day users (and which I'm not sure how to implement in PHP — any help is appreciated!)

Installation

composer require loilo/jsonpath

Note that at least PHP 8.0 is needed to use jsonpath-php. For technical reasons, unit tests are only run against PHP 8.2+.

Usage

use Loilo\JsonPath\JsonPath;

$query = new JsonPath('$.users[*].name');

$result = $query->find([
	'users' => [
		[ 'name' => 'John Doe' ],
		[ 'name' => 'Jane Doe' ],
	],
]);

print_r($result);

/*
Prints:

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

Project Scope

Please note that I'm striving for feature parity with the jsonpath-js library and therefore will add neither features nor fixes to the search logic that are not reflected in jsonpath-js itself.

If you have any issues with the library that are not obviously bugs in this PHP port, and you happen to know JavaScript, please check if your use case works correctly in the online demo of jsonpath-js since that's the canonical implementation. If the issue appears there as well, please open an issue in their repo.

Setup

To start development on jsonpath-php, you need git, PHP (≥ 8.2), Composer and npm.

Since code is formatted using Prettier, it's also recommended to use an editor which supports Prettier formatting.

Clone the repository and cd into it:

git clone https://github.com/loilo/jsonpath-php.git
cd jsonpath-php

Install Composer dependencies:

composer install

Install npm dependencies. They are needed for code formatting and for compiling the Peggy grammar.

npm ci

Formatting the Code

The code is formatted using Prettier. To format the code, run:

npm run format

Compiling the Grammar

The JSONPath grammar is defined in src/grammar/rfc9535-parser.pegjs. To compile it to src/PeggyParser.php, run:

npm run generate-parser

Quality Assurance

There are different kinds of code checks in place for this project. All of these are run when a pull request is submitted but can also be run locally:

Credit

All the credit goes to the creator of jsonpath-js. They did all the hard conceptual work, this PHP library is merely a port of their code.