- How do I install joelwurtz/json-stream-polyfill in a Laravel application?
- Install it with composer require joelwurtz/json-stream-polyfill. There is no service provider, config file, or PECL build step, and classes are autoloaded via PSR-4. In Laravel you would typically bind a small factory or adapter in one of your own service providers so your application code never references the package namespace directly.
- Does this polyfill actually stream JSON, or does it buffer the whole document in memory?
- The stated intent is incremental encoding and decoding so large documents never have to be fully materialized, mirroring the json_stream extension API. However, a pure-PHP polyfill can buffer internally to satisfy the interface, which would make peak memory worse than json_decode while still looking like a drop-in fix. Before relying on it, measure memory_get_peak_usage against a large fixture and read the reader/writer source to confirm it reads from a stream in chunks.
- What is the difference between this package and the json_stream PECL extension?
- The PECL extension is a C implementation of the JsonStream reader/writer API; this package is a pure-PHP polyfill that exposes the same class shapes for environments where compiling or installing the extension is impractical. That makes it useful for developers on older PHP versions, restricted hosting, or CI images you do not want to rebuild. The trade-off is throughput: pure PHP tokenizing will be materially slower than the C extension.
- Which PHP versions does joelwurtz/json-stream-polyfill support?
- The PHP version floor is not clearly documented in the available package information, so check the require constraints in composer.json before adopting. The only expected hard dependency is ext-json, which is bundled and enabled by default in modern PHP builds. If you need a specific Laravel version, confirm its minimum PHP requirement lines up with the polyfill's constraint.
- How do I write Laravel code that works with either the native extension or the polyfill?
- Put the resolution in one place, typically a JsonStreamFactory class bound as a singleton in a service provider. That factory can use class_exists or extension_loaded to return the native implementation when present and the polyfilled one otherwise. Your controllers, jobs, and commands should depend on your own interface or on the shared JsonStream API rather than on the package namespace.
- Is the polyfill API-complete compared to the extension, including options and exceptions?
- Completeness is unverified, and API parity is the most common place extension polyfills diverge. Watch for JSON edge cases such as integers beyond PHP_INT_MAX, duplicate keys, depth limits, invalid UTF-8, BOM handling, trailing data, and the exception class hierarchy thrown on malformed input. Read the source and write tests against these cases before trusting it in production.
- Will this pure-PHP polyfill be fast enough for production workloads?
- Expect it to be significantly slower than the C extension, plausibly by an order of magnitude on parse-heavy workloads. It fits background and memory-constrained work such as queue jobs, CLI importers, and export writers far better than high-QPS per-request hot paths. Benchmark your actual payloads on both the polyfill and the extension before committing to either.
- Can I use it for NDJSON ingestion, webhook payloads, or large file imports in Laravel?
- Those are the best-fit scenarios: batch importers, queue workers handling large payloads, webhook ingestion, and export generation where the whole document should not sit in memory. Laravel integration is thin, so wrap it in a job or command rather than wiring it into every request. If your format is strictly newline-delimited JSON, a simple line reader may be a clearer dependency than an extension polyfill.
- How should I test JSON streaming code that uses this polyfill?
- Use fixture files that cover large arrays, deep nesting, oversized integers, invalid UTF-8, and truncated input, and assert both the parsed result and the exception type. Add a test that records memory_get_peak_usage around a read of a multi-megabyte file to catch accidental buffering. If your factory supports both paths, run the suite once with the native extension enabled and once with only the polyfill.
- Is joelwurtz/json-stream-polyfill maintained, and what should I use instead if not?
- The package shows zero stars and zero dependents, so treat it as pre-adoption with a single-maintainer bus factor and verify the actual tag history before pinning a version. Pin an exact version, review the source, and keep it behind your own adapter so you can swap implementations. Alternatives include requiring the native json_stream extension where you control the runtime, or a purpose-built pull parser or NDJSON line reader if you simply need to process large JSON without loading it all.