PHPackages cerbero/lazy-json - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. cerbero/lazy-json ActiveLibrary[Utility & Helpers](/categories/utility) cerbero/lazy-json ================= Framework-agnostic package to load JSONs of any dimension and from any source into Laravel lazy collections. 2.0.0(2y ago)254309.8kโ€”5%41MITPHPPHP ^8.1 Since May 6Pushed 2y ago1 watchersCompare [ Source](https://github.com/cerbero90/lazy-json)[ Packagist](https://packagist.org/packages/cerbero/lazy-json)[ Docs](https://github.com/cerbero90/lazy-json)[ GitHub Sponsors](https://github.com/cerbero90)[ Fund](https://ko-fi.com/cerbero90)[ RSS](/packages/cerbero-lazy-json/feed)WikiDiscussions develop Synced 1mo ago READMEChangelogDependencies (7)Versions (5)Used By (1) ๐Ÿผ Lazy JSON =========== [](#-lazy-json) [![Author](https://camo.githubusercontent.com/fffbc89ca2742dccf8be167716e04b7125a913abae0da6a488131999dab8ca25/68747470733a2f2f696d672e736869656c64732e696f2f7374617469632f76313f6c6162656c3d617574686f72266d6573736167653d6365726265726f393026636f6c6f723d353041424631266c6f676f3d74776974746572267374796c653d666c61742d737175617265)](https://twitter.com/cerbero90)[![PHP Version](https://camo.githubusercontent.com/ee45e77f289a96d053cb21844719d39db7ce8f40f83711f0ea6b17f73c9c3b6e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6365726265726f2f6c617a792d6a736f6e3f636f6c6f723d253233344635423933266c6f676f3d706870267374796c653d666c61742d737175617265)](https://www.php.net)[![Build Status](https://camo.githubusercontent.com/abe25e71cbd0fdcee960799167bd4a0dd2afaf37eda56b246ce15f0e7b00effc/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6365726265726f39302f6a736f6e2d7061727365722f6275696c642e796d6c3f6272616e63683d6d6173746572267374796c653d666c61742d737175617265266c6f676f3d676974687562)](https://github.com/cerbero90/lazy-json/actions?query=workflow%3Abuild)[![Coverage Status](https://camo.githubusercontent.com/cbd177bd3af031039212a6d5c6497178e9cc593231c51bf095888087fc10dd2d/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f636f7665726167652f672f6365726265726f39302f6c617a792d6a736f6e2e7376673f7374796c653d666c61742d737175617265266c6f676f3d7363727574696e697a6572)](https://scrutinizer-ci.com/g/cerbero90/lazy-json/code-structure)[![Quality Score](https://camo.githubusercontent.com/b96fea8c39787edfea2bb9facd1283eca46cbc71aba37f0c7fc6455b0a6faff9/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f6365726265726f39302f6c617a792d6a736f6e2e7376673f7374796c653d666c61742d737175617265266c6f676f3d7363727574696e697a6572)](https://scrutinizer-ci.com/g/cerbero90/lazy-json)[![PHPStan Level](https://camo.githubusercontent.com/a297104012c8207e99eac313bcf680ff32843c3d3a21decb547f454bf4097ee2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6576656c2d6d61782d737563636573733f7374796c653d666c61742d737175617265266c6f676f3d646174613a696d6167652f706e673b6261736536342c6956424f5277304b47676f414141414e53556845556741414143414141414167434159414141427a656e72304141414762306c455156523432753158653142555a52532f79344b67386f6952334643434255795345535a4252436961426e6d45734f7a65537a73672b4b7859594f3964454566744e52715a6a78343046525a6b5470716d4f7a3553324c73586c455a42636961746b516e484447596147644679314570474d486c2f702f5064466c7432726b354f2b4a396e356e412f767466356e6564336c6e6c49537052686166426c4c524c4843744a475672422f5a4244736177326c55717a526547414334364473745459666e534347556a61614476677841436f366a337655656e4e64496d65525871646e575635617a3572726e7a655a7a6e6a384a2b4535467473636c68663373344a3443532f6f52783542766f6e385a553635464759517841776366383561374365527a2b4334315448656a75657964435a3741414b33346e7776336b48502f6f554b644f4c344b373235386646374375643432374f3438525165476b49474a37374e38665a716c726366525034642f78393057516648584c65427439645472536c776c33563635796e574c4d315345413271624e51636b626534586d77773130486d79337368696430434d636d6c454a745344736c35565a42646641674d7649337575522b6d6f4a714e364c61786d70734f42654c43446d546966434239325263516d6241554a767471414c63357351723870383667594243634664427139774f696e374e5161783665776c423672714c5a486632334650313079336c6a36754a74454267324878695643747a64335345774d4243696f364e6839757a5a344f2f764c774f5a344f554e4d324e79494750467276757a42472f2f6c5250732b5651326b316b692b65506b64383462736b7a375946705967697a457a3838503876507a596666753364445330674a4e545531515856304e71616d70524b31574977676669453471684f7969673072432b7043764b3851556f4d4c37754a564841356b635155703344537071576a6333642f4479386f4b696f694c6f367571436f614568754862314b765430394141684246706257346c4f70794d797949425153436d6f55514c517a676e694e767a2b6f624232485332527742674536644f7843794a6f676d4e6b503275315772687734514a30332b69477252395845643343544e426e366543626f3430775044774d645856314246314456473571694574626f78535550364a37312b44334e775541684c4f4952517a6d376c6e6e68595576375146762f79445a2f4c6d3575624b3244564939695a386252384a4474454235376c4e7a454e514e364f6a6f49476c70616249565a7359614d544f2b6872696b525241314a786d5358396845372f734a745679463338744b735543565a7842687a396a49337747542f514a6c41447a50417958726e6a306b496e7a47485143524d794f672f65643275486a784975453454675951487132444c4a71756d617368592b6c6e734d433447564335646f365856754b396c2b34536b4e38792b47665965564a6e32672b2b553751796750543064426759474944765435386d6e46355051636a433833507a5346396648375331745a47456841515a514f54384a61413331376f496b4d366a533875564c53447a4f517167323355682b4d6c6b4f66303047673063503334632b7676373455527a4d396e34316762792f7276766b63374f54686c415455334e4347594a5558743451614c75545977426354534f426d6a315244374434547369783442794f6a5a52462f7a677570444562675a336a346c792f71656b704e44306f35615134344853344f416773567174493167545a4f303149624730615031626b6e6e7843445576417248692b42306c4a536c7a676c5446594f3275644633516c39544372486e356f45497265487036516c5255464a53556c4a43717169705357566c4a38764c79434759494653374853337a476138376d76346c636a4c774c6c53746c4c544b59595555416c76726c444763573435774b785858366171485a4e75744d2b316f51424846546577414b6b6f48342b7671436a3438505941475335796235616d6a4e6f4f2b435532534c35334e4b70444430767848486d4f4a6972374c357855765a676d307573325231343253634f4979567159766c70575534586f4849503844584c32622b776a6457655868365532466a6d49494b6d625741595046524d75733632682f676549766a4f51596c707544797351724c4c364765723439486757386a7176585568493755764462396961535444714874794974694635537577356577462f4e6438564a367a6c68736e30366245687758344e79664376754745655270546d68346d6b47363879447079757a42394555636a553561776241676e63506c4165536441514552307a436e647a715662655843347144734d70764745594258526e734478344e33417566314643546a5449615674592f51546d643049386242566d316b656a45756255664f30317671496d6e336334395837717065714939696e4967746270784b3359724b66494a43742b4f6556326e665556465234636134456b56454e794137676b59634d66423152354d4d6d785a37657a2f324b463553534e3179562b3135385550734a54305a4263493262524c744958476f5975354665724f55694a65314f66734c335845574834336c324b532b694a46392b53344670634e6773632b6a3863543848346f31626650672f716b4c743530754a31527a644d7347673055717766454e313134507762314374575447672b59395535436c4b397837785557493742493556515670304156635133625a6b51686d6e45676448684b794e535a65313663727442496c63377349623663524c6674325043676f4b476a696a4244746a72415137613345644d73787a4952666c414649685062366d48596d5977582b57426c505167736b6867567279794a4351794e79424c73425164513666677351687974364d534f4f73575a37676248387745546d67524b41696a61744e4c384e676d30787834744c6373707330577a7834616c306a586c493430422f413370613134344d447453674141414141456c46546b5375516d4343)](https://phpstan.org/)[![Latest Version](https://camo.githubusercontent.com/96286aa740a0d8953e0ec1c64298a4b75f0e1e8244396f2e1325910bdc9b6882/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6365726265726f2f6c617a792d6a736f6e2e7376673f6c6162656c3d76657273696f6e267374796c653d666c61742d737175617265)](https://packagist.org/packages/cerbero/lazy-json)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![PER](https://camo.githubusercontent.com/84278b6753117019e91c00fda1fe3c0b04f80f38e435f191ddef6fe2069e2607/68747470733a2f2f696d672e736869656c64732e696f2f7374617469632f76313f6c6162656c3d636f6d706c69616e6365266d6573736167653d50455226636f6c6f723d626c7565267374796c653d666c61742d737175617265)](https://www.php-fig.org/per/coding-style/)[![Total Downloads](https://camo.githubusercontent.com/f7d3520f44bbb1c4f79e1800a3606252b67b8bdb554e223304f4a2e128ac00ee/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6365726265726f2f6c617a792d6a736f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cerbero/lazy-json) ``` LazyCollection::fromJson($source, 'data.*.users.*') ->map($this->mapToUser(...)) ->filter($this->filterUser(...)) ->values() ->chunk(1_000) ->each($this->storeUsersChunk(...)); ``` Framework-agnostic package to load JSON of any size and from any source into [Laravel lazy collections](https://laravel.com/docs/collections#lazy-collections). Lazy JSON recursively turns any JSON array or object into a lazy collection, consuming only a few KB of memory while parsing JSON of any dimension. It optionally allows to extract only some sub-trees, instead of the whole JSON, with an easy dot-notation syntax. Under the hood, [๐Ÿงฉ JSON Parser](https://github.com/cerbero90/json-parser) is used to parse JSONs and extract sub-trees. Need to lazy load items from paginated JSON APIs? Consider using [๐Ÿผ Lazy JSON Pages](https://github.com/cerbero90/lazy-json-pages) instead. ๐Ÿ“ฆ Install --------- [](#-install) Via Composer: ``` composer require cerbero/lazy-json ``` ๐Ÿ”ฎ Usage ------- [](#-usage) - [๐Ÿ‘ฃ Basics](#-basics) - [๐Ÿ’ง Sources](#-sources) - [๐ŸŽฏ Dots](#-dots) ### ๐Ÿ‘ฃ Basics [](#-basics) Depending on our coding style, we can call Lazy JSON in 3 different ways: ``` use Cerbero\LazyJson\LazyJson; use Illuminate\Support\LazyCollection; use function Cerbero\LazyJson\lazyJson; // auto-registered lazy collection macro $lazyCollection = LazyCollection::fromJson($source); // static method $lazyCollection = LazyJson::from($source); // namespaced helper $lazyCollection = lazyJson($source); ``` The variable `$source` in our examples represents any [JSON source](#-sources). Once we define the source, we can chain any method of the [Laravel lazy collection](https://laravel.com/docs/collections#lazy-collections) to process the JSON in a memory-efficient way: ``` LazyCollection::fromJson($source) ->values() ->map(/* ... */) ->where(/* ... */) ->each(/* ... */); ``` ### ๐Ÿ’ง Sources [](#-sources) A JSON source is any data point that provides a JSON. A wide range of sources are supported by default: - **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` For more information about JSON sources, please consult the [๐Ÿงฉ JSON Parser documentation](https://github.com/cerbero90/json-parser). ### ๐ŸŽฏ Dots [](#-dots) If we only need a sub-tree of a large JSON, we can use a simple dot-notation syntax to extract the desired path (or **dot**). Consider [this JSON](https://randomuser.me/api/1.4?seed=json-parser&results=5) for example. To extract only the cities and avoid parsing the rest of the JSON, we can set the `results.*.location.city` dot: ``` $source = 'https://randomuser.me/api/1.4?seed=json-parser&results=5'; $dot = 'results.*.location.city'; LazyCollection::fromJson($source, $dot)->each(function (string $value, string $key) { // 1st iteration: $key === 'city', $value === 'Sontra' // 2nd iteration: $key === 'city', $value === 'San Rafael Tlanalapan' // 3rd iteration: $key === 'city', $value === 'ฺฏุฑฺฏุงู†' // ... }); ``` The dot-notation syntax is very simple and it can include any of the following 4 elements: - a key of a JSON array, e.g. `0` - a key of a JSON object, e.g. `results` - a dot to indicate the nesting level within a JSON, e.g. `results.0` - an asterisk to indicate all items within an array, e.g. `results.*` If we need to extract several sub-trees, Lazy JSON supports multiple dots: ``` $dots = ['results.*.gender', 'results.*.email']; LazyCollection::fromJson($source, $dots)->each(function (string $value, string $key) { // 1st iteration: $key === 'gender', $value === 'female' // 2nd iteration: $key === 'email', $value === 'sara.meder@example.com' // 3rd iteration: $key === 'gender', $value === 'female' // 4th iteration: $key === 'email', $value === 'andrea.roque@example.com' // ... }); ``` ๐Ÿ“† Change log ------------ [](#-change-log) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. ๐Ÿงช Testing --------- [](#-testing) ``` composer test ``` ๐Ÿ’ž Contributing -------------- [](#-contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) and [CODE\_OF\_CONDUCT](CODE_OF_CONDUCT.md) for details. ๐Ÿงฏ Security ---------- [](#-security) If you discover any security related issues, please email instead of using the issue tracker. ๐Ÿ… Credits --------- [](#-credits) - [Andrea Marco Sartori](https://twitter.com/cerbero90) - [All Contributors](../../contributors) โš–๏ธ License ---------- [](#๏ธ-license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 41 โ€” FairBetter than 89% of packages Maintenance20 Infrequent updates โ€” may be unmaintained Popularity50 Moderate usage in the ecosystem Community14 Small or concentrated contributor base Maturity64 Established project with proven stability Bus Factor1 Top contributor holds 97% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~468 days Total 3 Last Release 902d ago Major Versions 1.1.0 โ†’ 2.0.02023-11-29 PHP version history (2 changes)1.0.0PHP ^7.2||^8.0 2.0.0PHP ^8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/596523?v=4)[Matteo Picciolini](/maintainers/cerbero)[@cerbero](https://github.com/cerbero) --- Top Contributors [![cerbero90](https://avatars.githubusercontent.com/u/5838106?v=4)](https://github.com/cerbero90 "cerbero90 (64 commits)")[![jeromegamez](https://avatars.githubusercontent.com/u/67554?v=4)](https://github.com/jeromegamez "jeromegamez (2 commits)") --- Tags jsonlaravellexerparserstreamjsonlaravelparsercollectionlazy ### Code Quality TestsPest Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/cerbero-lazy-json/health.svg) ``` [![Health](https://phpackages.com/badges/cerbero-lazy-json/health.svg)](https://phpackages.com/packages/cerbero-lazy-json) ``` ### Alternatives [cerbero/lazy-json-pages Framework-agnostic package to load items from any paginated JSON API into a Laravel lazy collection via async HTTP requests. 19697.4k](/packages/cerbero-lazy-json-pages)[pragmarx/ia-collection Laravel Illuminate Agnostic Collection 473.4M2](/packages/pragmarx-ia-collection)[armincms/json A Laravel Nova field. 25149.4k3](/packages/armincms-json)[gamez/typed-collection Type-safe collections based on Laravel Collections 45317.8k](/packages/gamez-typed-collection)[jshannon63/jsoncollect Supercharge your JSON using collections 154.9k1](/packages/jshannon63-jsoncollect)[werxe/laravel-collection-macros Custom Laravel Collection macros. 2625.8k](/packages/werxe-laravel-collection-macros) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)