# ๐Ÿงฉ JSON Parser [![Author][ico-author]][link-author] [![PHP Version][ico-php]][link-php] [![Build Status][ico-actions]][link-actions] [![Coverage Status][ico-scrutinizer]][link-scrutinizer] [![Quality Score][ico-code-quality]][link-code-quality] [![PHPStan Level][ico-phpstan]][link-phpstan] [![Latest Version][ico-version]][link-packagist] [![Software License][ico-license]](LICENSE.md) [![PSR-7][ico-psr7]][link-psr7] [![PSR-12][ico-psr12]][link-psr12] [![Total Downloads][ico-downloads]][link-downloads] Zero-dependencies pull parser to read large JSON from any source in a memory-efficient way. ## ๐Ÿ“ฆ Install Via Composer: ``` bash composer require cerbero/json-parser ``` ## ๐Ÿ”ฎ Usage * [Sources](#sources) JSON Parser provides a minimal API to read large JSON from any source: ```php 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: ```php 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 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 responses**, 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: ```php 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](https://github.com/cerbero90/json-parser/tree/master/src/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](CHANGELOG.md) for more information on what has changed recently. ## ๐Ÿงช Testing ``` bash composer test ``` ## ๐Ÿ’ž Contributing Please see [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) 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][link-author] - [All Contributors][link-contributors] ## โš–๏ธ License The MIT License (MIT). Please see [License File](LICENSE.md) for more information. [ico-author]: https://img.shields.io/static/v1?label=author&message=cerbero90&color=50ABF1&logo=twitter&style=flat-square [ico-php]: https://img.shields.io/packagist/php-v/cerbero/json-parser?color=%234F5B93&logo=php&style=flat-square [ico-version]: https://img.shields.io/packagist/v/cerbero/json-parser.svg?label=version&style=flat-square [ico-actions]: https://img.shields.io/github/actions/workflow/status/cerbero90/json-parser/workflows/build.yml?branch=master&style=flat-square&logo=github [ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square [ico-psr7]: https://img.shields.io/static/v1?label=compliance&message=PSR-7&color=blue&style=flat-square [ico-psr12]: https://img.shields.io/static/v1?label=compliance&message=PSR-12&color=blue&style=flat-square [ico-scrutinizer]: https://img.shields.io/scrutinizer/coverage/g/cerbero90/json-parser.svg?style=flat-square&logo=scrutinizer [ico-code-quality]: https://img.shields.io/scrutinizer/g/cerbero90/json-parser.svg?style=flat-square&logo=scrutinizer [ico-phpstan]: https://img.shields.io/badge/level-max-success?style=flat-square&logo=data:image/png;base64,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 [ico-downloads]: https://img.shields.io/packagist/dt/cerbero/json-parser.svg?style=flat-square [link-author]: https://twitter.com/cerbero90 [link-php]: https://www.php.net [link-packagist]: https://packagist.org/packages/cerbero/json-parser [link-actions]: https://github.com/cerbero90/json-parser/actions?query=workflow%3Abuild [link-psr7]: https://www.php-fig.org/psr/psr-7/ [link-psr12]: https://www.php-fig.org/psr/psr-12/ [link-scrutinizer]: https://scrutinizer-ci.com/g/cerbero90/json-parser/code-structure [link-code-quality]: https://scrutinizer-ci.com/g/cerbero90/json-parser [link-phpstan]: https://phpstan.org/ [link-downloads]: https://packagist.org/packages/cerbero/json-parser [link-contributors]: ../../contributors