json-parser/README.md

🧩 JSON Parser

Zero-dependencies pull parser to read large JSON from any source in a memory-efficient way.

📦 Install

Via Composer:

composer require cerbero/json-parser

🔮 Usage

• Sources

JSON Parser provides a minimal API to read large JSON from any source:

use Cerbero\JsonParser\JsonParser;

// the JSON source in this example is an API 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
}

Depending on our taste, we can instantiate the parser in 3 different ways:

use Cerbero\JsonParser\JsonParser;

// classic object instantiation
new JsonParser($source);

// static instantiation, facilitates methods chaining
JsonParser::parse($source);

// namespaced function
use function Cerbero\JsonParser\parseJson;

parseJson($source);

Sources

A wide range of JSON sources is supported, here is the full list:

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

If the source we need to parse is not supported by default, we can implement our own custom source.

Click here to see how to implement a custom source.

To implement a custom source, we need to extend Source and implement 3 methods:

use Cerbero\JsonParser\Sources\Source;
use Traversable;

class CustomSource extends Source
{
    public function getIterator(): Traversable
    {
        // return a Traversable holding the JSON source, e.g. a Generator yielding chunks of JSON
    }

    public function matches(): bool
    {
        // return TRUE if this class can handle the JSON source
    }

    protected function calculateSize(): ?int
    {
        // return the size of the JSON in bytes or NULL if it can't be calculated
    }
}

The parent class Source gives us access to 2 properties:

• $source: the JSON source we pass to the parser, i.e.: new JsonParser($source)
• $config: the configuration we set by chaining methods, e.g.: $parser->pointer('/foo')

The method getIterator() defines the logic to read the JSON source in a memory-efficient way. It feeds the parser with small pieces of JSON. Please refer to the already existing sources to see some implementations.

The method matches() determines whether the JSON source passed to the parser can be handled by our custom implementation. In other words, we are telling the parser if it should use our class for the JSON to parse.

Finally, calculateSize() computes the whole size of the JSON source. It's used to track the parsing progress, however it's not always possible to know the size of a JSON source. In this case, or if we don't need to track the progress, we can return null.

📆 Change log

Please see CHANGELOG for more information on what has changed recently.

🧪 Testing

composer test

💞 Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

🧯 Security

If you discover any security related issues, please email andrea.marco.sartori@gmail.com instead of using the issue tracker.

🏅 Credits

• Andrea Marco Sartori
• All Contributors

⚖️ License

The MIT License (MIT). Please see License File for more information.