Stream Laravel Package

Getting Started

Start by installing react/stream via Composer: composer require react/stream. Its core purpose is to provide event-driven, non-blocking streams — essential for building scalable async PHP apps with ReactPHP. First, import the namespace (use React\Stream;) and create a simple readable stream (e.g., from STDIN or a file resource) to begin handling data chunks incrementally. A minimal use case: read STDIN line-by-line without blocking the event loop:

$loop = React\EventLoop\Loop::get();
$stdin = new React\Stream\ReadableResourceStream(STDIN, $loop);
$stdin->on('data', fn($chunk) => echo "Received: $chunk");
$loop->run();

This is the foundational pattern — all higher-level ReactPHP components (e.g., HTTP server, TCP clients) rely on these abstractions. Always check the latest branch: v3 (main) vs stable v1 (1.x branch) — compatibility matters.

Implementation Patterns

• Piping chains: Compose transformations via $source->pipe($transform1)->pipe($transform2)->pipe($dest). Use ThroughStream to implement lightweight filtering/decoding (e.g., JSON line decoder, gzip decompressor).
• Backpressure handling: Always pair pipe() with pause()/resume() for flow control. Example: throttle upload stream when disk I/O lags.
• Duplex echo services: Pipe a connection to itself for echo servers: $connection->pipe($connection).
• Resource wrapping: Wrap PHP resources directly: new ReadableResourceStream(fopen('file.log', 'r'), $loop) or new WritableResourceStream(STDOUT, $loop).
• Composite streams: Combine multiple streams into one via CompositeStream, useful for aggregating inputs (e.g., merging multiple input sources).
• Tested protocols: Use ThroughStream to build message delimiters (e.g., \n-terminated payloads) — emit full lines in data handlers after buffering partial chunks.

Gotchas and Tips

• Event semantics matter: end ≠ close. end signals successful EOF; close signals termination (success or failure). Always handle error to avoid silent hangs.
• Stream state checks: Use isReadable() and isWritable() before operations — writing to a closed stream silently fails and may log warnings.
• .pause() is advisory: The stream may still emit data after pause() (e.g., buffered data). Always guard event handlers: if (!$stream->isReadable()) return;.
• Buffering gotchas: Raw resource streams don’t auto-buffer by line. Implement your own \n-delimited parser with a buffer property.
• Async close handling: Call $dest->close() manually if source closes early (e.g., $source->on('close', fn() => $dest->end())).
• PHP resource lifecycle: Avoid closing wrapped resources manually — the stream owns it and closes on close() or garbage collection. Reusing resources after wrapping often causes issues.
• v3 breaking changes: v3 uses strict types, union types, and removed legacy signatures. If stuck on PHP <8.0, pin to ^1.11. Check changelog for EndStreamException removal and constructor parameter changes.