Json Stream Polyfill Laravel Package

Technical Evaluation

Architecture fit

• The package is a pure-PHP polyfill for the PECL json_stream extension, meaning it is designed as a transparent shim over JsonStream\Reader / JsonStream\Writer-style APIs rather than a new abstraction. Architecturally this is a compatibility layer, not a parser library — value is realized only if the codebase (or a dependency) already targets the extension API.
• Fit is strongest where you want "native when available, portable otherwise": a Composer-installed namespace that mirrors the extension's classes, so application code calls one API and the runtime resolves native vs. polyfilled implementation.
• Fit is weak as a general-purpose streaming JSON library. If the goal is "parse big JSON without loading it all," a purpose-built library (e.g., a pull-parser or NDJSON line reader) is a clearer dependency than an extension polyfill.
• Coupling is minimal: no framework bindings, no service providers required, PSR-4 autoload, MIT license. Suitable for Laravel via a small adapter/service binding rather than deep integration.

Integration feasibility

• composer require joelwurtz/json-stream-polyfill is low-friction; no compilation, no PECL, no CI image changes. This is the main selling point versus requiring ext-json_stream on every developer machine and CI runner.
• Blocking unknowns: PHP version floor, whether the polyfill is guarded against the native extension being present (class-already-declared handling), and whether it is a functional polyfill or a partial one.
• Evidence of production use is effectively zero (0 stars, 0 dependents). Treat as pre-adoption: budget for reading the source, not for trusting a track record.

Technical risk

• Performance risk (high): a pure-PHP implementation of tokenizing/encoding will be materially slower than the C extension — plausibly an order of magnitude on parse-heavy workloads. Any design that assumes extension-grade throughput must be re-benchmarked.
• Semantic risk (high): "streaming" is a behavioral contract, not just an API shape. If the polyfill buffers internally to satisfy the interface, peak memory can be worse than json_decode on large documents while appearing to be a drop-in fix.
• Parity risk (medium): JSON edge cases are where polyfills diverge — integer precision beyond PHP_INT_MAX, duplicate keys, depth limits, invalid UTF-8, BOM handling, trailing data, exception classes/hierarchy, and option flags passed to reader/writer constructors.
• Provenance risk (medium): the recorded last release date (2026-07-27) is not credible as-is and should be verified against the actual tag history before pinning; 0 stars/0 dependents also implies single-maintainer, low-bus-factor stewardship.
• License risk (low): MIT is compatible with Laravel/PHP commercial codebases.

Key questions

1. Which version of the json_stream extension API does the polyfill target, and how completely (methods, options, exceptions)?
2. Does it genuinely stream (constant memory) or buffer? What are the measured peak-memory curves vs. the extension and vs. json_decode?
3. What is the PHP version support matrix, and is ext-json the only hard requirement?
4. How is the native-vs-polyfill resolution done — explicit class_exists check, Composer provide/replace, or manual wiring?
5. Is there a test suite, and does it cover the edge cases above?
6. Who maintains it, what is the change cadence, and is there an upstream extension maintainer relationship?

Integration Approach

Stack fit

• Laravel/PHP 8.x+ with Composer: clean fit, no framework coupling. The natural pattern is a thin application-level adapter (JsonStreamFactory) that returns either the native classes or the polyfilled ones, bound in a service provider so call sites never reference the package namespace directly.
• Best-fit use cases: CLI/batch importers, queue workers processing large payloads, webhook/NDJSON ingestion, and export writers — i.e., long-lived or memory-constrained jobs rather than per-request hot paths.
• Poor fit: high-QPS HTTP request parsing, where json_decode on realistically sized bodies is almost certainly faster than a PHP tokenizer.

Migration path

• Do not migrate existing json_decode/json_encode call sites wholesale. Introduce the abstraction first, ship it with the native extension (or existing code path) as the default, and register the polyfill only as a fallback.
• Prefer a strangler approach: one consumer at a time, starting with the lowest-risk batch job, with the polyfill selectable via config/env flag.
• Keep an explicit escape hatch: if the polyfill misbehaves, config flips back to the existing implementation without a deploy.

Compatibility

• Verify no class-name collisions when ext-json_stream is installed in some environments and not others (dev laptop vs. production container). The resolution logic must be deterministic across the fleet, otherwise you get environment-specific behavior — the single most common failure mode for this class of package.
• Pin an exact version in composer.json and commit a lockfile; do not use a floating constraint on a 0-star single-maintainer package.
• Confirm the polyfill does not require the extension in its own composer.json (which would defeat the purpose) and does not replace it in a way that masks a genuinely missing extension.

Sequencing

1. Spike (1–2 days): read the source, confirm API surface and streaming behavior; write a micro-benchmark comparing polyfill, extension, and json_decode on representative payloads (throughput + peak memory).
2. Adapter: add the factory/interface and service binding; no behavior change.
3. Golden-file tests: pin expected output for the edge cases (big ints, UTF-8, depth, malformed input) so native and polyfill are provably equivalent on your data.
4. Shadow/canary: run the polyfill in one non-critical worker path, compare outputs against the incumbent, watch memory and error rates.
5. Decide: either standardize on the polyfill (if the extension is operationally painful) or keep it as fallback-only and document that the extension is the performance path.

Operational Impact

Maintenance

• Single-maintainer, near-zero-adoption package: assume you may need to fork or vendor-patch. Budget modest ongoing time to track upstream and re-verify parity on PHP minor upgrades (PHP's JSON handling and type-juggling behavior does shift across versions).
• Add it to the dependency-review list and pin it; the cost of an unnoticed breaking commit on a floating constraint exceeds the cost of periodic manual bumps.
• Record the license and provenance in your SBOM; verify the release history against Packagist, not the reported metadata.

Support

• No commercial support, no vendor escalation path. Internal ownership must be assigned explicitly, with runbook documentation for the failure modes below.
• Onboarding docs should state clearly: which code paths use streaming, why, and what happens when the extension is or isn't present.

Scaling

• CPU-bound: expect significantly higher per-document cost than the C extension. Validate against your actual payload sizes; the crossover point where streaming beats json_decode depends on document size and memory limits, not on the API.
• Horizontally, this is easy to scale (stateless, per-process); the constraint is per-worker throughput, so size queue worker pools accordingly.
• Memory: this is the whole justification, so instrument it. Emit peak-memory metrics for streaming jobs before and after, and alert on regression — that is the signal that streaming semantics have silently degraded.

Failure modes

• Memory exhaustion under the guise of streaming — polyfill buffers, job OOMs at a payload size that previously worked.
• Silent output divergence — numeric precision loss (large IDs from external systems are a classic), key ordering, or escaping differences between polyfill and extension.
• Exception-type mismatch — code catching extension-specific exceptions misses polyfill exceptions, so malformed input crashes instead of being handled.
• Environment skew — extension present in prod, absent in CI (or vice versa), so tests pass while production behavior differs.
• Stream handling defects — half-read handles, no clean close on error, partial writes leaving corrupt export files.
• Abandonment — no upstream fix for a newly discovered parsing bug; mitigation is fork-and-patch capability.

Ramp-up

• Low for developers: the API mirrors the extension and is familiar to anyone who has used a pull-parser. The real ramp-up cost is conceptual — engineers must understand that the interface promises streaming but the implementation may not deliver it, and must therefore reason about payload sizes and memory budgets rather than treating it as a drop-in json_decode replacement.
• Estimate roughly a day of engineer time to become productive, plus the benchmark harness upfront. The dominant risk is not learning curve but unverified behavioral parity — which is why step 3 of the sequencing plan is non-negotiable.