@@ -30,9 +30,9 @@ You can install the component in your project using Composer:
30
30
Usage
31
31
-----
32
32
33
- To start querying a JSON document, first create a :class: ` Symfony \\ Component \\ JsonPath \\ JsonCrawler `
34
- object from a JSON string. The following examples use this sample "bookstore"
35
- JSON data::
33
+ To start querying a JSON document, first create a
34
+ :class: ` Symfony \\ Component \\ JsonPath \\ JsonCrawler` object from a JSON string. The
35
+ following examples use this sample "bookstore" JSON data::
36
36
37
37
use Symfony\C omponent\J sonPath\J sonCrawler;
38
38
@@ -77,8 +77,9 @@ JSON data::
77
77
78
78
$crawler = new JsonCrawler($json);
79
79
80
- Once you have the crawler instance, use its :method: `Symfony\\ Component\\ JsonPath\\ JsonCrawler::find `
81
- method to start querying the data. This method returns an array of matching values.
80
+ Once you have the crawler instance, use its
81
+ :method:`Symfony\\ Component\\ JsonPath\\ JsonCrawler::find ` method to start
82
+ querying the data. This method returns an array of matching values.
82
83
83
84
Querying with Expressions
84
85
-------------------------
@@ -97,9 +98,9 @@ of the document is represented by ``$``::
97
98
98
99
// $titles is ['Sayings of the Century']
99
100
100
- Dot notation is the default, but JSONPath provides other syntaxes for cases where
101
- it doesn't work. Use bracket notation (``['...'] ``) when a key contains spaces
102
- or special characters::
101
+ Dot notation is the default, but JSONPath provides other syntaxes for cases
102
+ where it doesn't work. Use bracket notation (``['...'] ``) when a key contains
103
+ spaces or special characters::
103
104
104
105
// this is equivalent to the previous example
105
106
$titles = $crawler->find('$["store"]["book"][0]["title"]');
@@ -119,7 +120,12 @@ you to find values without specifying the full path::
119
120
// get all authors from anywhere in the document
120
121
$authors = $crawler->find('$..author');
121
122
122
- // $authors is ['Nigel Rees', 'Evelyn Waugh', 'Herman Melville', 'John Ronald Reuel Tolkien']
123
+ // $authors is equals to [
124
+ 'Nigel Rees',
125
+ 'Evelyn Waugh',
126
+ 'Herman Melville',
127
+ 'John Ronald Reuel Tolkien'
128
+ ]
123
129
124
130
Filtering Results
125
131
~~~~~~~~~~~~~~~~~
@@ -135,8 +141,9 @@ Building Queries Programmatically
135
141
136
142
For more dynamic or complex query building, use the fluent API provided
137
143
by the :class: `Symfony\\ Component\\ JsonPath\\ JsonPath ` class. This lets you
138
- construct a query object step by step. The ``JsonPath `` object can then be passed
139
- to the crawler's :method: `Symfony\\ Component\\ JsonPath\\ JsonCrawler::find ` method.
144
+ construct a query object step by step. The ``JsonPath `` object can then be
145
+ passed to the crawler's
146
+ :method: `Symfony\\ Component\\ JsonPath\\ JsonCrawler::find ` method.
140
147
141
148
The main advantage of the programmatic builder is that it automatically handles
142
149
escaping of keys and values, preventing syntax errors::
@@ -178,7 +185,8 @@ methods to build your query:
178
185
* :method: `Symfony\\ Component\\ JsonPath\\ JsonPath::index `
179
186
Adds an array index selector. Index numbers start at ``0 ``.
180
187
181
- * :method: `Symfony\\ Component\\ JsonPath\\ JsonPath::first ` / :method: `Symfony\\ Component\\ JsonPath\\ JsonPath::last `
188
+ * :method: `Symfony\\ Component\\ JsonPath\\ JsonPath::first ` /
189
+ :method: `Symfony\\ Component\\ JsonPath\\ JsonPath::last `
182
190
Shortcuts for ``index(0) `` and ``index(-1) `` respectively::
183
191
184
192
// get the last book: '$["store"]["book"][-1]'
@@ -216,8 +224,10 @@ appropriate (e.g., inside a ``filter()`` expression).
216
224
Testing with JSON Assertions
217
225
----------------------------
218
226
219
- The component provides a set of PHPUnit assertions to make testing JSON data more convenient. Use the
220
- :class: `Symfony\\ Component\\ JsonPath\\ Test\\ JsonPathAssertionsTrait ` in your test class::
227
+ The component provides a set of PHPUnit assertions to make testing JSON data
228
+ more convenient. Use the
229
+ :class: `Symfony\\ Component\\ JsonPath\\ Test\\ JsonPathAssertionsTrait `
230
+ in your test class::
221
231
222
232
use PHPUnit\Framework\TestCase;
223
233
use Symfony\Component\JsonPath\Test\JsonPathAssertionsTrait;
@@ -237,27 +247,32 @@ The component provides a set of PHPUnit assertions to make testing JSON data mor
237
247
The trait provides the following assertion methods:
238
248
239
249
* :method: `Symfony\\ Component\\ JsonPath\\ Test\\ JsonPathAssertionsTrait::assertJsonPathCount `
240
- Asserts that the number of elements found by the JSONPath expression matches an expected count::
250
+ Asserts that the number of elements found by the JSONPath expression matches
251
+ an expected count::
241
252
242
253
$json = '{"a": [1, 2, 3]}';
243
254
self::assertJsonPathCount(3, '$.a[*]', $json);
244
255
245
256
* :method: `Symfony\\ Component\\ JsonPath\\ Test\\ JsonPathAssertionsTrait::assertJsonPathEquals `
246
- Asserts that the result of a JSONPath expression is equal to an expected value.The comparison uses ``== `` (type coercion) instead of ``=== ``::
257
+ Asserts that the result of a JSONPath expression is equal to an expected
258
+ value. The comparison uses ``== `` (type coercion) instead of ``=== ``::
247
259
248
260
$json = '{"a": [1, 2, 3]}';
249
261
250
262
// passes because "1" == 1
251
263
self::assertJsonPathEquals(['1'], '$.a[0]', $json);
252
264
253
265
* :method: `Symfony\\ Component\\ JsonPath\\ Test\\ JsonPathAssertionsTrait::assertJsonPathNotEquals `
254
- Asserts that the result of a JSONPath expression is not equal to an expected value.The comparison uses ``!= `` (type coercion) instead of ``!== ``::
266
+ Asserts that the result of a JSONPath expression is not equal to an expected
267
+ value. The comparison uses ``!= `` (type coercion) instead of ``!== ``::
255
268
256
269
$json = '{"a": [1, 2, 3]}';
257
270
self::assertJsonPathNotEquals([42], '$.a[0]', $json);
258
271
259
272
* :method: `Symfony\\ Component\\ JsonPath\\ Test\\ JsonPathAssertionsTrait::assertJsonPathSame `
260
- 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::
273
+ Asserts that the result of a JSONPath expression is identical (``=== ``) to an
274
+ expected value. This is a strict comparison and does not perform type
275
+ coercion::
261
276
262
277
$json = '{"a": [1, 2, 3]}';
263
278
@@ -267,19 +282,22 @@ The trait provides the following assertion methods:
267
282
self::assertJsonPathSame([1], '$.a[0]', $json);
268
283
269
284
* :method: `Symfony\\ Component\\ JsonPath\\ Test\\ JsonPathAssertionsTrait::assertJsonPathNotSame `
270
- Asserts that the result of a JSONPath expression is not identical (``!== ``) to an expected value::
285
+ Asserts that the result of a JSONPath expression is not identical (``!== ``) to
286
+ an expected value::
271
287
272
288
$json = '{"a": [1, 2, 3]}';
273
289
self::assertJsonPathNotSame(['1'], '$.a[0]', $json);
274
290
275
291
* :method: `Symfony\\ Component\\ JsonPath\\ Test\\ JsonPathAssertionsTrait::assertJsonPathContains `
276
- Asserts that a given value is found within the array of results from the JSONPath expression::
292
+ Asserts that a given value is found within the array of results from the
293
+ JSONPath expression::
277
294
278
295
$json = '{"tags": ["php", "symfony", "json"]}';
279
296
self::assertJsonPathContains('symfony', '$.tags[*]', $json);
280
297
281
298
* :method: `Symfony\\ Component\\ JsonPath\\ Test\\ JsonPathAssertionsTrait::assertJsonPathNotContains `
282
- Asserts that a given value is NOT found within the array of results from the JSONPath expression::
299
+ Asserts that a given value is NOT found within the array of results from the
300
+ JSONPath expression::
283
301
284
302
$json = '{"tags": ["php", "symfony", "json"]}';
285
303
self::assertJsonPathNotContains('java', '$.tags[*]', $json);
@@ -290,11 +308,14 @@ Error Handling
290
308
The component throws specific exceptions for invalid input or queries:
291
309
292
310
* :class: `Symfony\\ Component\\ JsonPath\\ Exception\\ InvalidArgumentException `:
293
- Thrown if the input to the ``JsonCrawler `` constructor is not a valid JSON string;
311
+ Thrown if the input to the ``JsonCrawler `` constructor is not a valid JSON
312
+ string;
294
313
* :class: `Symfony\\ Component\\ JsonPath\\ Exception\\ InvalidJsonStringInputException `:
295
- Thrown during a ``find() `` call if the JSON string is malformed (e.g., syntax error);
314
+ Thrown during a ``find() `` call if the JSON string is malformed
315
+ (e.g., syntax error);
296
316
* :class: `Symfony\\ Component\\ JsonPath\\ Exception\\ JsonCrawlerException `:
297
- Thrown for errors within the JsonPath expression itself, such as using an unknown function
317
+ Thrown for errors within the JsonPath expression itself, such as using an
318
+ unknown function
298
319
299
320
Example of handling errors::
300
321
0 commit comments