{"id":22487757,"url":"https://github.com/cerbero90/lazy-json","last_synced_at":"2025-12-25T05:48:42.561Z","repository":{"id":40354268,"uuid":"363557651","full_name":"cerbero90/lazy-json","owner":"cerbero90","description":"🐼 Framework-agnostic package to load JSON of any dimension and from any source into Laravel lazy collections recursively.","archived":false,"fork":false,"pushed_at":"2023-11-29T23:53:18.000Z","size":63,"stargazers_count":233,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2024-06-18T21:43:33.970Z","etag":null,"topics":["json","laravel","lexer","parser","stream"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cerbero90.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"cerbero90","ko_fi":"cerbero90"}},"created_at":"2021-05-02T03:27:15.000Z","updated_at":"2024-06-14T21:36:54.000Z","dependencies_parsed_at":"2024-06-18T21:27:23.327Z","dependency_job_id":"5de321e8-ee66-4079-812c-c3e2877b8449","html_url":"https://github.com/cerbero90/lazy-json","commit_stats":{"total_commits":28,"total_committers":2,"mean_commits":14.0,"dds":0.0714285714285714,"last_synced_commit":"f471ec6d1e5fdfa6d516d2192508b0b9866bf430"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":"cerbero90/skeleton","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbero90%2Flazy-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbero90%2Flazy-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbero90%2Flazy-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbero90%2Flazy-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cerbero90","download_url":"https://codeload.github.com/cerbero90/lazy-json/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228500239,"owners_count":17930015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","laravel","lexer","parser","stream"],"created_at":"2024-12-06T17:17:11.855Z","updated_at":"2025-12-25T05:48:42.517Z","avatar_url":"https://github.com/cerbero90.png","language":"PHP","funding_links":["https://github.com/sponsors/cerbero90","https://ko-fi.com/cerbero90"],"categories":["PHP","Table of Contents"],"sub_categories":["JSON"],"readme":"# 🐼 Lazy JSON\n\n[![Author][ico-author]][link-author]\n[![PHP Version][ico-php]][link-php]\n[![Build Status][ico-actions]][link-actions]\n[![Coverage Status][ico-scrutinizer]][link-scrutinizer]\n[![Quality Score][ico-code-quality]][link-code-quality]\n[![PHPStan Level][ico-phpstan]][link-phpstan]\n[![Latest Version][ico-version]][link-packagist]\n[![Software License][ico-license]](LICENSE.md)\n[![PER][ico-per]][link-per]\n[![Total Downloads][ico-downloads]][link-downloads]\n\n```php\nLazyCollection::fromJson($source, 'data.*.users.*')\n    -\u003emap($this-\u003emapToUser(...))\n    -\u003efilter($this-\u003efilterUser(...))\n    -\u003evalues()\n    -\u003echunk(1_000)\n    -\u003eeach($this-\u003estoreUsersChunk(...));\n```\n\nFramework-agnostic package to load JSON of any size and from any source into [Laravel lazy collections](https://laravel.com/docs/collections#lazy-collections).\n\nLazy 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.\n\nIt optionally allows to extract only some sub-trees, instead of the whole JSON, with an easy dot-notation syntax.\n\nUnder the hood, [🧩 JSON Parser](https://github.com/cerbero90/json-parser) is used to parse JSONs and extract sub-trees.\n\nNeed to lazy load items from paginated JSON APIs? Consider using [🐼 Lazy JSON Pages](https://github.com/cerbero90/lazy-json-pages) instead.\n\n\n## 📦 Install\n\nVia Composer:\n\n``` bash\ncomposer require cerbero/lazy-json\n```\n\n## 🔮 Usage\n\n* [👣 Basics](#-basics)\n* [💧 Sources](#-sources)\n* [🎯 Dots](#-dots)\n\n\n### 👣 Basics\n\nDepending on our coding style, we can call Lazy JSON in 3 different ways:\n\n```php\nuse Cerbero\\LazyJson\\LazyJson;\nuse Illuminate\\Support\\LazyCollection;\n\nuse function Cerbero\\LazyJson\\lazyJson;\n\n// auto-registered lazy collection macro\n$lazyCollection = LazyCollection::fromJson($source);\n\n// static method\n$lazyCollection = LazyJson::from($source);\n\n// namespaced helper\n$lazyCollection = lazyJson($source);\n```\n\nThe 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:\n\n```php\nLazyCollection::fromJson($source)\n    -\u003evalues()\n    -\u003emap(/* ... */)\n    -\u003ewhere(/* ... */)\n    -\u003eeach(/* ... */);\n```\n\n\n### 💧 Sources\n\nA JSON source is any data point that provides a JSON. A wide range of sources are supported by default:\n- **strings**, e.g. `{\"foo\":\"bar\"}`\n- **iterables**, i.e. arrays or instances of `Traversable`\n- **file paths**, e.g. `/path/to/large.json`\n- **resources**, e.g. streams\n- **API endpoint URLs**, e.g. `https://endpoint.json` or any instance of `Psr\\Http\\Message\\UriInterface`\n- **PSR-7 requests**, i.e. any instance of `Psr\\Http\\Message\\RequestInterface`\n- **PSR-7 messages**, i.e. any instance of `Psr\\Http\\Message\\MessageInterface`\n- **PSR-7 streams**, i.e. any instance of `Psr\\Http\\Message\\StreamInterface`\n- **Laravel HTTP client requests**, i.e. any instance of `Illuminate\\Http\\Client\\Request`\n- **Laravel HTTP client responses**, i.e. any instance of `Illuminate\\Http\\Client\\Response`\n- **user-defined sources**, i.e. any instance of `Cerbero\\JsonParser\\Sources\\Source`\n\nFor more information about JSON sources, please consult the [🧩 JSON Parser documentation](https://github.com/cerbero90/json-parser).\n\n\n### 🎯 Dots\n\nIf 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**).\n\nConsider [this JSON](https://randomuser.me/api/1.4?seed=json-parser\u0026results=5) for example. To extract only the cities and avoid parsing the rest of the JSON, we can set the `results.*.location.city` dot:\n\n```php\n$source = 'https://randomuser.me/api/1.4?seed=json-parser\u0026results=5';\n\n$dot = 'results.*.location.city';\n\nLazyCollection::fromJson($source, $dot)-\u003eeach(function (string $value, string $key) {\n    // 1st iteration: $key === 'city', $value === 'Sontra'\n    // 2nd iteration: $key === 'city', $value === 'San Rafael Tlanalapan'\n    // 3rd iteration: $key === 'city', $value === 'گرگان'\n    // ...\n});\n```\n\nThe dot-notation syntax is very simple and it can include any of the following 4 elements:\n- a key of a JSON array, e.g. `0`\n- a key of a JSON object, e.g. `results`\n- a dot to indicate the nesting level within a JSON, e.g. `results.0`\n- an asterisk to indicate all items within an array, e.g. `results.*`\n\nIf we need to extract several sub-trees, Lazy JSON supports multiple dots:\n\n```php\n$dots = ['results.*.gender', 'results.*.email'];\n\nLazyCollection::fromJson($source, $dots)-\u003eeach(function (string $value, string $key) {\n    // 1st iteration: $key === 'gender', $value === 'female'\n    // 2nd iteration: $key === 'email', $value === 'sara.meder@example.com'\n    // 3rd iteration: $key === 'gender', $value === 'female'\n    // 4th iteration: $key === 'email', $value === 'andrea.roque@example.com'\n    // ...\n});\n```\n\n## 📆 Change log\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## 🧪 Testing\n\n``` bash\ncomposer test\n```\n\n## 💞 Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) for details.\n\n## 🧯 Security\n\nIf you discover any security related issues, please email andrea.marco.sartori@gmail.com instead of using the issue tracker.\n\n## 🏅 Credits\n\n- [Andrea Marco Sartori][link-author]\n- [All Contributors][link-contributors]\n\n## ⚖️ License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n[ico-author]: https://img.shields.io/static/v1?label=author\u0026message=cerbero90\u0026color=50ABF1\u0026logo=twitter\u0026style=flat-square\n[ico-php]: https://img.shields.io/packagist/php-v/cerbero/lazy-json?color=%234F5B93\u0026logo=php\u0026style=flat-square\n[ico-version]: https://img.shields.io/packagist/v/cerbero/lazy-json.svg?label=version\u0026style=flat-square\n[ico-actions]: https://img.shields.io/github/actions/workflow/status/cerbero90/json-parser/build.yml?branch=master\u0026style=flat-square\u0026logo=github\n[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square\n[ico-per]: https://img.shields.io/static/v1?label=compliance\u0026message=PER\u0026color=blue\u0026style=flat-square\n[ico-scrutinizer]: https://img.shields.io/scrutinizer/coverage/g/cerbero90/lazy-json.svg?style=flat-square\u0026logo=scrutinizer\n[ico-code-quality]: https://img.shields.io/scrutinizer/g/cerbero90/lazy-json.svg?style=flat-square\u0026logo=scrutinizer\n[ico-phpstan]: https://img.shields.io/badge/level-max-success?style=flat-square\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAGb0lEQVR42u1Xe1BUZRS/y4Kg8oiR3FCCBUySESZBRCiaBnmEsOzeSzsg+KxYYO9dEEftNRqZjx40FRZkTpqmOz5S2LsXlEZBciatkQnHDGYaGdFy1EpGMHl/p/PdFlt2rk5O+J9n5nA/vtf5ned3lnlISpRhafBlLRLHCtJGVrB/ZBDsaw2lUqzReGAC46DstTYfnSCGUjaaDvgxACo6j3vUenNdImeRXqdnWV5az5rrnzeZznj8J+E5Ftsclhf3s4J4CS/oRx5Bvon8ZU65FGYQxAwcf85a7CeRz+C41THejueydCZ7AAK34nwv3kHP/oUKdOL4K7258fF7Cud427O48RQeGkIGJ77N8fZqlrcfRP4d/x90WQfHXLeBt9dTrSlwl3V65ynWLM1SEA2qbNQckbe4Xmww10Hmy3shid0CMcmlEJtSDsl5VZBdfAgMvI3uuR+moJqN6LaxmpsOBeLCDmTifCB92RcQmbAUJvtqALc5sQr8p86gYBCcFdBq9wOin7NQax6ewlB6rqLZHf23FP10y3lj6uJtEBg2HxiVCtzd3SEwMBCio6Nh9uzZ4O/vLwOZ4OUNM2NyIGPFrvuzBG//lRPs+VQ2k1ki+ePkd84bskz7YFpYgizEz88P8vPzYffu3dDS0gJNTU1QXV0NqampRK1WIwgfiE4qhOyig0rC+pCvK8QUoML7uJVHA5kcQUp3DSpqWjc3d/Dy8oKioiLo6uqCoaEhuHb1KvT09AAhBFpbW4lOpyMyyIBQSCmoUQLQzgniNvz+obB2HS2RwBgE6dOxCyJogmNkP2u1Wrhw4QJ03+iGrR9XEd3CTNBn6eCbo40wPDwMdXV1BF1DVG5qiEtboxSUP6J71+D3NwUAhLOIRQzm7lnnhYUv7QFv/yDZ/Lm5ubK2DVI9iZ8bR8JDtEB57lNzENQN6OjoIGlpabIVZsYaMTO+hrikRRA1JxmSX9hE7/sJtVyF38tKsUCVZxBhz9jI3wGT/QJlADzPAyXrnj0kInzGHQCRMyOg/ed2uHjxIuE4TgYQHq2DLJqumashY+lnsMC4GVC5do6XVuK9l+4SkN8y+GfYeVJn2g++U7QygPT0dBgYGIDvT58mnF5PQcjC83PzSF9fH7S1tZGEhAQZQOT8JaA317oIkM6jS8uVLSDzOQqg23Uh+MlkOf00Gg0cP34c+vv74URzM9n41gby/rvvkc7OThlATU3NCGYJUXt4QaLuTYwBcTSOBmj1RD7D4Tsix4ByOjZRF/zgupDEbgZ3j4ly/qekpND0o5aQ44HS4OAgsVqtI1gTZO01IbG0aP1bknnxCDUvArHi+B0lJSlzglTFYO2udF3Ql9TCrHn5oEIreHp6QlRUFJSUlJCqqipSWVlJ8vLyCGYIFS7HS3zGa87mv4lcjLwLlStlLTKYYUUAlvrlDGcW45wKxXX6aqHZNutM+1oQBHFTewAKkoH4+vqCj48PYAGS5yb5amjNoO+CU2SL53NKpDD0vxHHmOJir7L5xUvZgm0us2R142ScOIyVqYvlpWU4XoHIP8DXL2b+wjdWeXh6U2FjmIIKmbWAYPFRMus62h/geIvjOQYlpuDysQrLL6Ger49HgW8jqvXUhI7UvDb9iaSTDqHtyItiF5Suw5ewF/Nd8VJ6zlhsn06bEhwX4NyfCvuGEeRpTmh4mkG68yDpyuzB9EUcjU5awbAgncPlAeSdAQER0zCndzqVbeXC4qDsMpvGEYBXRnsDx4N3Auf1FCTjTIaVtY/QTmd0I8bBVm1kejEubUfO01vqImn3c49X7qpeqI9inIgtbpxK3YrKfIJCt+OeV2nfUVFR4ca4EkVENyA7gkYcMfB1R5MMmxZ7ez/2KF5SSN1yV+158UPsJT0ZBcI2bRLtIXGoYu5FerOUiJe1OfsL3XEWH43l2KS+iJF9+S4FpcNgsc+j8cT8H4o1bfPg/qkLt50uJ1RzdMsGg0UqwfEN114Pwb1CtWTGg+Y9U5ClK9x7xUWI7BI5VQVp0AVcQ3bZkQhmnEgdHhKyNSZe16crtBIlc7sIb6cRLft2PCgoKGjijBDtjrAQ7a3EdMsxzIRflAFIhPb6mHYmYwX+WBlPQgskhgVryyJCQyNyBLsBQdQ6fgsQhyt6MSOOsWZ7gbH8wETmgRKAijatNL8Ngm0xx4tLcsps0Wzx4al0jXlI40B/A3pa144MDtSgAAAAAElFTkSuQmCC\n[ico-downloads]: https://img.shields.io/packagist/dt/cerbero/lazy-json.svg?style=flat-square\n\n[link-author]: https://twitter.com/cerbero90\n[link-php]: https://www.php.net\n[link-packagist]: https://packagist.org/packages/cerbero/lazy-json\n[link-actions]: https://github.com/cerbero90/lazy-json/actions?query=workflow%3Abuild\n[link-per]: https://www.php-fig.org/per/coding-style/\n[link-scrutinizer]: https://scrutinizer-ci.com/g/cerbero90/lazy-json/code-structure\n[link-code-quality]: https://scrutinizer-ci.com/g/cerbero90/lazy-json\n[link-downloads]: https://packagist.org/packages/cerbero/lazy-json\n[link-phpstan]: https://phpstan.org/\n[link-contributors]: ../../contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerbero90%2Flazy-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcerbero90%2Flazy-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerbero90%2Flazy-json/lists"}