Json Stream Polyfill Laravel Package

Product Decisions This Supports

• Large-payload ingestion without memory blowups. Any roadmap item that involves importing/exporting large JSON (catalog syncs, CRM dumps, analytics event batches, third-party report downloads) is gated on whether you can parse incrementally. This package is the shim that lets you write that feature against the json_stream API without forcing every environment to compile a PECL extension.
• Build vs. buy vs. "adopt a shim." The realistic alternative isn't building a streaming parser in-house — it's either (a) requiring ext-json_stream and losing deploy targets, or (b) pulling a full userland streaming parser like halaxa/json-machine. This polyfill sits in between: it lets a dependency declare ext-json_stream as a soft requirement and still resolve on stock PHP.
• Deployment target decisions. If your portfolio includes Laravel Vapor, shared hosting, or customer-managed on-prem installs where you cannot install PECL extensions, adopting a polyfill strategy is what keeps one codebase shippable everywhere. Conversely, if you own every runtime image, this package is a decision not to make.
• Queue and worker sizing. Streaming parse changes the memory-per-job calculus for queue workers (Horizon supervisors, Lambda memory tiers). A polyfill makes the feature portable but with materially different throughput — a cost decision, not just a compatibility one.
• Transitive-dependency due diligence. With 0 stars and 0 dependents, adopting this is a bet on a single maintainer's parity work. That belongs in your dependency-risk register, and it should be a conscious "acceptable because it's a thin, replaceable shim" call.

When to Consider This Package

• A library you already want (or already depend on) requires or suggests ext-json_stream, and you want Composer to resolve on environments without the extension.
• You must support heterogeneous runtimes — some with the native extension, some without — and you want identical code paths in both.
• You want a stopgap to unblock a feature now while the platform team schedules a base-image change.
• You are comfortable pinning an exact version and accepting that the polyfill is slower than the C extension by a wide margin; the win is compatibility, not speed.

Look elsewhere when:

• You control the runtime. Install ext-json_stream (or just use json_decode with sane payload limits) and skip the dependency entirely.
• Streaming JSON is a primary product capability rather than plumbing. Mature userland parsers (halaxa/json-machine, salsify/json-streaming-parser) have years of field use, real test suites, and active maintenance; a 0-star polyfill does not.
• You need behavioral guarantees. Polyfills diverge at edge cases — malformed input handling, numeric precision, buffer semantics. Undocumented divergence in a parser is a data-corruption risk, not a performance one.
• Your org has a minimum-maintenance bar (stars, dependents, release cadence, security policy). This fails all of them; the release date being in the future also warrants a sanity check before you pin it.
• You need JSONPath, SIMD-accelerated parsing, or schema validation — different problem, different tool.

How to Pitch It (Stakeholders)

One line: A small, MIT-licensed compatibility shim that lets us use streaming JSON parsing on platforms where we can't install the native PHP extension — unblocking large-payload features without a platform migration.

To executives: It removes a deployment blocker. Today, "parse a 400MB JSON export without exhausting memory" either requires us to control the runtime image or to rewrite the feature. This shim buys us the option to ship on Vapor, shared hosting, and on-prem installs from the same codebase. Cost is one dependency, no license fee, and the exit path is trivial — delete it the day we standardize on the native extension.

To engineering: Treat it as an adapter, not a foundation. Wrap it behind our own small parser interface so we can swap in ext-json_stream or a mature streaming parser later without touching call sites. Pin the version exactly, add it to the dependency-risk list, and benchmark it — a pure-PHP parser will be an order of magnitude slower than the C extension, so the worker/memory sizing we assume in staging must be re-measured in production. Do not let it silently become the only parser we test against; CI must exercise the native-extension path too, or we will ship bugs that only appear where the extension exists.

Honest caveat to include: zero stars, zero dependents, single maintainer. The right posture is "cheap, reversible enabler with a named owner and a removal plan," not "strategic infrastructure."