Ndjson React Laravel Package

Getting Started

Install via Composer (composer require clue/ndjson-react) and start by wrapping ReactPHP streams with Decoder for parsing or Encoder for serializing. The core use case is streaming NDJSON over stdin/stdout for CLI tools or network IPC. For example, parse line-by-line JSON logs from a stream:

$stdin = new React\Stream\ReadableResourceStream(STDIN);
$decoder = new Clue\React\NDJson\Decoder($stdin);
$decoder->on('data', fn($record) => processRecord($record));

Or write structured events to stdout:

$stdout = new React\Stream\WritableResourceStream(STDOUT);
$encoder = new Clue\React\NDJson\Encoder($stdout);
$encoder->write(['timestamp' => time(), 'message' => 'Started']);

Implementation Patterns

• Log Aggregation Pipelines: Chain ZlibCompressionStream → NDJson\Decoder to process .ndjson.gz logs without loading entire files.
• RPC over Streams: Wrap socket connections with Decoder and Encoder to send/receive JSON-RPC-style messages frame-by-frame.
• Buffering for Backpressure: Use pipe() to stream decoded data through filters (e.g., map/filter with map streams), respecting ReactPHP’s backpressure automatically.
• Configuration Consistency: Reuse json_decode/json_encode options across components (e.g., JSON_UNESCAPED_UNICODE) by passing them to Decoder/Encoder constructors.
• CLI Integration: Pair with react/stream to build command-line tools that consume/process NDJSON streams from other processes (e.g., php producer.php | php consumer.php).

Gotchas and Tips

• Avoid JSON_PRETTY_PRINT: Passing this to Encoder throws InvalidArgumentException; NDJSON requires one JSON object per line.
• Buffer Overflows: Default 64KiB line-length limit can be increased via the 5th constructor parameter if processing unusually long records (e.g., new Decoder($stream, false, 512, 0, 1024 * 1024)).
• Unicode Handling: Use JSON_UNESCAPED_UNICODE in Encoder for human-readable output; by default, non-ASCII chars get escaped (e.g., "wörld" → "w\u00f6rld").
• Error Resilience: Always attach an error listener—invalid JSON or stream failures will emit exceptions and close the stream. Log errors before allowing silent exits.
• Pipe Pitfalls: Decoder emits decoded objects, but most writable streams expect string chunks. Use Encoder (or manual json_encode) when piping decoded data back to streams.
• Backward Compatibility: While the package supports PHP 5.3+, use modern PHP versions (8.0+) to avoid subtle json_decode edge-case behaviors (e.g., integer overflows).