- How do I install cerbero/lazy-json in a Laravel app?
- Install it with composer require cerbero/lazy-json. The Laravel adapter ships with a facade and helper that are picked up by package auto-discovery where your Laravel version supports it, so you can call LazyJson::fromFile($path)->collection() almost immediately. Before committing, confirm that the package's PHP and illuminate/support constraints resolve cleanly against your application's composer.json.
- Which PHP and Laravel versions does lazy-json support?
- Support is defined entirely by the PHP and illuminate/support constraints in the package's composer.json, so check those against your current stack and your planned upgrade path. Because the Laravel layer is only a thin adapter over a framework-agnostic parser, most compatibility friction comes from the illuminate/support constraint rather than the streaming engine. If resolution fails, composer why-not cerbero/lazy-json will tell you which constraint is blocking.
- How is lazy-json different from json_decode for big JSON files?
- json_decode builds the whole document in memory before you can touch a single node, so peak memory scales with file size. Lazy JSON streams the payload through halaxa/json-machine and yields nodes as an Illuminate LazyCollection, holding only the current item in memory. That makes multi-gigabyte files and HTTP streams practical, at the price of single-pass semantics and slower random access.
- Can lazy-json load JSON from a URL or remote stream?
- Yes, it reads from files, streams and remote sources, which is handy for ingesting third-party feeds. Treat user-supplied URLs as untrusted: allowlist hosts and validate schemes to avoid SSRF, since the parser will follow whatever source you hand it. Some underlying parsers need seekable input, so proxy non-seekable S3 or HTTP streams through a local temp file if you hit read errors.
- How do I select nested nodes with a pointer in lazy-json?
- Pass a dot-notation pointer as the second argument, for example LazyJson::fromFile($path, 'data.items')->collection(), to skip wrapper envelopes and iterate directly over the repeated nodes you care about. Whether keys are preserved and how repeated nested nodes are flattened depends on your document shape, so verify with a small fixture before wiring it into a job. Keep the pointer in configuration rather than hard-coding it across the codebase.
- Does lazy-json support JSON Lines or NDJSON?
- The package targets single-document JSON and delegates parsing to json-machine, so JSON Lines and NDJSON are not its documented use case. For line-delimited data, stream the file line by line yourself and json_decode each line, which is already memory-safe and simpler to reason about. Check the current README before designing an importer around NDJSON support.
- How are mid-stream JSON parse errors handled in lazy-json?
- Because parsing is lazy, malformed JSON usually surfaces as an exception during iteration rather than when the collection is created, meaning part of the payload may already have been processed. Wrap iteration in try/catch, write in chunks, and use transactions or idempotent upserts so a retry after a mid-stream failure is safe. Remote sources can also fail partway through, so handle HTTP errors explicitly instead of assuming the collection ended cleanly.
- Can I use lazy-json without Laravel?
- Yes. The parsing core is framework-agnostic and returns a plain iterator; the Laravel adapter only wraps that output in an Illuminate LazyCollection. You can use it in any Composer project, and within Laravel you can bypass the facade by instantiating the underlying reader directly. That separation also makes it easier to swap the parser out later without touching call sites.
- How do I test code that uses lazy-json LazyCollections?
- Lazy collections are single-pass, so assert on collected results instead of iterating the same instance twice, and materialise items inside the test when you need repeated assertions. Use small fixtures that mirror production nesting, but include at least one realistically large file so you can measure peak memory and wall time against your json_decode baseline. In queued jobs, prefer chunked consumption with progress reporting so failures are observable.
- Is lazy-json production-ready and what are the alternatives?
- Adoption signals are thin: a few hundred GitHub stars, no dependents, a single maintainer, and a transitive dependency on json-machine, so abandonment or a breaking upstream release is a realistic risk. Mitigate by wrapping it in your own small adapter such as a JsonStreamReader returning a LazyCollection, pinning the exact version, and adding it to your vulnerability and abandonment watchlist. If that risk is unacceptable, use halaxa/json-machine directly or move the parsing into a database-native JSON loader.