The JsonPath Component

Installation

You can install the component in your project using Composer:

1

$ composer require symfony/json-path

Usage

To start querying a JSON document, first create a JsonCrawler object from a JSON string. The following examples use this sample "bookstore" JSON data:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

use Symfony\Component\JsonPath\JsonCrawler;

$json = <<<'JSON'
{
    "store": {
        "book": [
            {
                "category": "reference",
                "author": "Nigel Rees",
                "title": "Sayings of the Century",
                "price": 8.95
            },
            {
                "category": "fiction",
                "author": "Evelyn Waugh",
                "title": "Sword of Honour",
                "price": 12.99
            },
            {
                "category": "fiction",
                "author": "Herman Melville",
                "title": "Moby Dick",
                "isbn": "0-553-21311-3",
                "price": 8.99
            },
            {
                "category": "fiction",
                "author": "John Ronald Reuel Tolkien",
                "title": "The Lord of the Rings",
                "isbn": "0-395-19395-8",
                "price": 22.99
            }
        ],
        "bicycle": {
            "color": "red",
            "price": 399
        }
    }
}
JSON;

$crawler = new JsonCrawler($json);

Once you have the crawler instance, use its find() method to start querying the data. This method returns an array of matching values.

Querying with Expressions

The primary way to query the JSON is by passing a JSONPath expression string to the find() method.

1
2
3
4

// get the title of the first book in the store
$titles = $crawler->find('$.store.book[0].title');

// $titles is ['Sayings of the Century']

1
2
3
4
5
6
7
8

// this is equivalent to the previous example
$titles = $crawler->find('$["store"]["book"][0]["title"]');

// this expression requires brackets because some keys use dots or spaces
$titles = $crawler->find('$["store"]["book collection"][0]["title.original"]');

// you can combine both notations
$titles = $crawler->find('$["store"].book[0].title');

1
2
3
4

// get all authors from anywhere in the document
$authors = $crawler->find('$..author');

// $authors is ['Nigel Rees', 'Evelyn Waugh', 'Herman Melville', 'John Ronald Reuel Tolkien']

1
2

// get all books with a price less than 10
$cheapBooks = $crawler->find('$.store.book[?(@.price < 10)]');

Building Queries Programmatically

For more dynamic or complex query building, use the fluent API provided by the JsonPath class. This lets you construct a query object step by step. The JsonPath object can then be passed to the crawler's find() method.

The main advantage of the programmatic builder is that it automatically handles escaping of keys and values, preventing syntax errors:

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Component\JsonPath\JsonPath;

$path = (new JsonPath())
    ->key('store') // selects the 'store' key
    ->key('book')  // then the 'book' key
    ->index(1);    // then the second item (indexes start at 0)

// the created $path object is equivalent to the string '$["store"]["book"][1]'
$book = $crawler->find($path);

// $book contains the book object for "Sword of Honour"

The JsonPath class provides several methods to build your query:

• key() Adds a key selector. The key name is properly escaped:

  1
  2

  // creates the path '$["key\"with\"quotes"]'
  $path = (new JsonPath())->key('key"with"quotes');

• deepScan() Adds the descendant operator .. to perform a recursive search from the current point in the path:

  1
  2

  // get all prices in the store: '$["store"]..["price"]'
  $path = (new JsonPath())->key('store')->deepScan()->key('price');

• all() Adds the wildcard operator [*] to select all items in an array or object:

  1
  2

  // creates the path '$["store"]["book"][*]'
  $path = (new JsonPath())->key('store')->key('book')->all();

• index() Adds an array index selector. Index numbers start at 0.

• first() / last() Shortcuts for index(0) and index(-1) respectively:

  1
  2

  // get the last book: '$["store"]["book"][-1]'
  $path = (new JsonPath())->key('store')->key('book')->last();

• slice() Adds an array slice selector [start:end:step]:

  1
  2
  3
  4
  5
  6
  7

  // get books from index 1 up to (but not including) index 3
  // creates the path '$["store"]["book"][1:3]'
  $path = (new JsonPath())->key('store')->key('book')->slice(1, 3);
  
  // get every second book from the first four books
  // creates the path '$["store"]["book"][0:4:2]'
  $path = (new JsonPath())->key('store')->key('book')->slice(0, 4, 2);

• filter() Adds a filter expression. The expression string is the part that goes inside the ?() syntax:

  1
  2
  3
  4
  5

  // get expensive books: '$["store"]["book"][?(@.price > 20)]'
  $path = (new JsonPath())
      ->key('store')
      ->key('book')
      ->filter('@.price > 20');

Advanced Querying

For a complete overview of advanced operators like wildcards and functions within filters, refer to the Querying with Expressions section above. All these features are supported and can be combined with the programmatic builder when appropriate (e.g., inside a filter() expression).

Testing with JSON Assertions

The component provides a set of PHPUnit assertions to make testing JSON data more convenient. Use the JsonPathAssertionsTrait in your test class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

use PHPUnit\Framework\TestCase;
use Symfony\Component\JsonPath\Test\JsonPathAssertionsTrait;

class MyTest extends TestCase
{
    use JsonPathAssertionsTrait;

    public function testSomething(): void
    {
        $json = '{"books": [{"title": "A"}, {"title": "B"}]}';

        self::assertJsonPathCount(2, '$.books[*]', $json);
    }
}

The trait provides the following assertion methods:

• assertJsonPathCount() Asserts that the number of elements found by the JSONPath expression matches an expected count:

  1
  2

  $json = '{"a": [1, 2, 3]}';
  self::assertJsonPathCount(3, '$.a[*]', $json);

• assertJsonPathEquals() Asserts that the result of a JSONPath expression is equal to an expected value. The comparison uses == (type coercion) instead of ===:

  1
  2
  3
  4

  $json = '{"a": [1, 2, 3]}';
  
  // passes because "1" == 1
  self::assertJsonPathEquals(['1'], '$.a[0]', $json);

• assertJsonPathNotEquals() Asserts that the result of a JSONPath expression is not equal to an expected value. The comparison uses != (type coercion) instead of !==:

  1
  2

  $json = '{"a": [1, 2, 3]}';
  self::assertJsonPathNotEquals([42], '$.a[0]', $json);

• assertJsonPathSame() Asserts that the result of a JSONPath expression is identical (===) to an expected value. This is a strict comparison and does not perform type coercion:

  1
  2
  3
  4
  5
  6

  $json = '{"a": [1, 2, 3]}';
  
  // fails because "1" !== 1
  // self::assertJsonPathSame(['1'], '$.a[0]', $json);
  
  self::assertJsonPathSame([1], '$.a[0]', $json);

• assertJsonPathNotSame() Asserts that the result of a JSONPath expression is not identical (!==) to an expected value:

  1
  2

  $json = '{"a": [1, 2, 3]}';
  self::assertJsonPathNotSame(['1'], '$.a[0]', $json);

• assertJsonPathContains() Asserts that a given value is found within the array of results from the JSONPath expression:

  1
  2

  $json = '{"tags": ["php", "symfony", "json"]}';
  self::assertJsonPathContains('symfony', '$.tags[*]', $json);

• assertJsonPathNotContains() Asserts that a given value is NOT found within the array of results from the JSONPath expression:

  1
  2

  $json = '{"tags": ["php", "symfony", "json"]}';
  self::assertJsonPathNotContains('java', '$.tags[*]', $json);

Error Handling

The component throws specific exceptions for invalid input or queries:

• InvalidArgumentException: Thrown if the input to the JsonCrawler constructor is not a valid JSON string;
• InvalidJsonStringInputException: Thrown during a find() call if the JSON string is malformed (e.g., syntax error);
• JsonCrawlerException: Thrown for errors within the JsonPath expression itself, such as using an unknown function

Example of handling errors:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

use Symfony\Component\JsonPath\Exception\InvalidJsonStringInputException;
use Symfony\Component\JsonPath\Exception\JsonCrawlerException;

try {
    // the following line contains malformed JSON
    $crawler = new JsonCrawler('{"store": }');
    $crawler->find('$..*');
} catch (InvalidJsonStringInputException $e) {
    // ... handle error
}

try {
    // the following line contains an invalid query
    $crawler->find('$.store.book[?unknown_function(@.price)]');
} catch (JsonCrawlerException $e) {
    // ... handle error
}