Json Stream Laravel Package

Product Decisions This Supports

• Memory-bounded ingestion (build the feature vs. defer it). The package parses JSON incrementally: you feed it chunks, it hands back complete decoded values one at a time. This turns "we can't process 200 MB exports inside a 128 MB PHP-FPM worker" from a rewrite into a small integration — a concrete input to capacity and infra-cost decisions.
• NDJSON / JSON Lines ingestion. A large and growing share of data feeds are newline-delimited JSON: log drains, analytics and warehouse exports, bulk-search payloads, and batch-API result files from LLM providers. If the roadmap includes "import customer's export" or "consume vendor's batch results," this is the cheap enabler.
• Handling concatenated JSON. Feeds that emit {...}{...}{...} with no separator defeat naive explode("\n") parsing. Supporting that format is a scope decision this package makes nearly free.
• Non-seekable sources. Because it's a pure parser with no I/O of its own, it composes with anything that yields bytes — HTTP chunked responses, pipes, sockets, ReactPHP streams. That shapes whether we ship "live tail" style features or stick to uploaded files.
• Build vs. buy. Correct incremental parsing means buffering partial tokens that straddle chunk boundaries — a classic source of subtle, intermittent bugs. The package is small, MIT-licensed, and dependency-light, so buying (adopting) is the obvious call over hand-rolling this logic.
• Scoping the ticket. It parses only. It does not do transport, retries, schema validation, or recovery policy for malformed records. The PM-level takeaway: budget for the surrounding error-handling work, don't assume the library covers it.

When to Consider This Package

Adopt when most of these hold:

• Input is NDJSON/JSONL or concatenated JSON, and payloads can plausibly exceed available memory or arrive over a socket.
• You want per-record delivery — commit or discard record-by-record, report progress, fail fast on record N rather than after loading everything.
• You only need parsing; your own code owns the HTTP client, filesystem, queueing, and retry logic.
• You're already on Composer and want no runtime dependencies beyond core PHP.

Look elsewhere (or skip) when:

• Payloads are small. A few megabytes or less: json_decode on the whole body is simpler, faster to ship, and one fewer dependency.
• Records are reliably one-per-line and well-formed. explode("\n") + json_decode is zero-dependency and often adequate. This package earns its place when chunk boundaries, concatenation, or malformed-record handling actually bite.
• You need querying or validation. If you need "give me only these fields from a 2 GB file" or schema enforcement, a richer streaming library (e.g. halaxa/json-machine) or a validator is a better fit.
• You need maintenance guarantees. Only 24 stars, single maintainer, last release December 2020. No security-response SLA, no active issue triage. If your org requires supported dependencies, either vendor/fork it deliberately or pick an actively maintained alternative.
• You need batteries-included stream plumbing. This is a primitive, not a framework; expect to write the wiring.

How to Pitch It (Stakeholders)

To executives: A small, free (MIT) library that lets us ingest very large JSON data feeds — customer exports, vendor batch results — without provisioning bigger workers or rewriting our queue pipeline. Adoption cost is one Composer dependency and roughly a day of integration. The main caveat is that the project is quiet (last release 2020, small community), so we'd pin the version, wrap it behind our own interface, and treat it as a vendored utility we can fork if needed — no licensing or lock-in concern.

To engineering: It's a pure incremental JSON parser: push($chunk), get back an array of complete decoded values. It correctly handles tokens split across chunk boundaries and both concatenated and newline-delimited framing, and it has no I/O and no real dependencies. That replaces the buffer-stitching code we'd otherwise write and test ourselves. Constraints to plan around: it parses only — no transport, no validation, no malformed-record recovery — and it's unmaintained since 2020, so keep it behind an internal adapter and treat halaxa/json-machine as the drop-in escape hatch if requirements grow.