PHP JSON Parser – Memory-efficiently read large JSON files from any source

A memory-efficient pull parser with zero dependencies, JSON Parser can read large amounts of JSON from any source. Any source, including a string, URL, etc., can be used to read JSON, and you can iterate through it in this way:

// a source is anything that can provide a JSON, in this case an endpoint
$source = 'https://randomuser.me/api/1.4?seed=json-parser&results=5';
 
foreach (new JsonParser($source) as $key => $value) {
    // instead of loading the whole JSON, we keep in memory only one key and value at a time
}

This parser also has a traverse method that looks like this if you don’t want to use foreach:

JsonParser::parse($source)->traverse(function (mixed $value, string|int $key, JsonParser $parser) {
    // lazily load one key and value at a time; we can also access the parser if needed
});

The aforementioned examples show how to process JSON using a URL, however the package supports multiple data sources.

• strings, e.g. {“foo”:”bar”}
• iterables, i.e. arrays or instances of Traversable
• file paths, e.g. /path/to/large.json
• resources, e.g. streams
• API endpoint URLs, e.g. https://endpoint.json or any instance of Psr\Http\Message\UriInterface
• PSR-7 requests, i.e. any instance of Psr\Http\Message\RequestInterface
• PSR-7 messages, i.e. any instance of Psr\Http\Message\MessageInterface
• PSR-7 streams, i.e. any instance of Psr\Http\Message\StreamInterface
• Laravel HTTP client requests, i.e. any instance of Illuminate\Http\Client\Request
• Laravel HTTP client responses, i.e. any instance of Illuminate\Http\Client\Response
• user-defined sources, i.e. any instance of Cerbero\JsonParser\Sources\Source

Pointers are another fantastic feature of this library that I would like to highlight. They are helpful in extracting only particular subtrees from a large JSON dataset:

// Select the first gender result
$json = JsonParser::parse($source)->pointer('/results/0/gender');
 
foreach ($json as $key => $value) {
    // 1st and only iteration: $key === 'gender', $value === 'female'
}
 
// Get all gender results
$json = JsonParser::parse($source)->pointer('/results/-/gender');
// ...

There’s a lot more features in this package. I should still point out that you should look at! It includes a progress API, for instance, to monitor the parsing progress (bytes processed, completion percentage, etc.).