josephsilber / lazy-json

🐼 Framework agnostic package to load heavy JSON into Laravel lazy collections.

🐼 Lazy JSON

Framework agnostic package to load heavy JSON in lazy collections. Under the hood, the brilliant JSON Machine by @halaxa is used as a lexer and parser.

Need to load paginated items of JSON APIs? Consider using Lazy JSON Pages instead.

Install

In a Laravel application, all you need to do is requiring the package:

composer require cerbero/lazy-json

Otherwise, you also need to register the lazy collection macro manually:

use Cerbero\LazyJson\Macro;
use Illuminate\Support\LazyCollection;

LazyCollection::macro('fromJson', new Macro());

Usage

Loading JSON in lazy collections is possible by using the collection itself or the included helper:

LazyCollection::fromJson($source);

lazyJson($source);

The following are the supported JSON sources:

$source = '{"foo":"bar"}'; // JSON string
$source = ['{"foo":"bar"}']; // any iterable containing JSON, i.e. array or Traversable
$source = 'https://foo.test/endpoint'; // endpoint
$source = Http::get('https://foo.test/endpoint'); // Laravel HTTP client response
$source = '/path/to/file.json'; // JSON file
$source = fopen('/path/to/file.json', 'rb'); // any resource
$source = <Psr\Http\Message\MessageInterface>; // any PSR-7 message, e.g. Guzzle response
$source = <Psr\Http\Message\StreamInterface>; // any PSR-7 stream

Optionally, you can define a dot-noted path to extract only a sub-tree of the JSON. For example, given the following JSON:

{
    "data": [
        {
            "name": "Team 1",
            "users": [
                {
                    "id": 1
                },
                {
                    "id": 2
                }
            ]
        },
        {
            "name": "Team 2",
            "users": [
                {
                    "id": 3
                }
            ]
        }
    ]
}

defining the path data.*.users.*.id would iterate only user IDs:

$ids = lazyJson($source, 'data.*.users.*.id')
    ->filter(fn ($id) => $id % 2 == 0)
    ->all();

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 [email protected] instead of using the issue tracker.

Credits

• Andrea Marco Sartori
• All Contributors

License

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