Byte Stream Laravel Package

Getting Started

Start by installing the package via Composer:

composer require amphp/byte-stream

Then, familiarize yourself with the two core interfaces: Amp\ByteStream\ReadableStream and Amp\ByteStream\WritableStream. The simplest first use case is wrapping a socket resource (e.g., from stream_socket_client()) with the provided ResourceStream adapter to convert it into a non-blocking stream:

use Amp\ByteStream\ResourceStream;
use Amp\Loop;

Loop::run(function () {
    $socket = stream_socket_client('tcp://example.com:80');
    $stream = new ResourceStream($socket);

    // Write request
    yield $stream->write("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n");
    
    // Read response in chunks
    while ($chunk = yield $stream->read()) {
        echo $chunk;
    }
});

Check the examples/ directory in the repo for minimal working demos.

Implementation Patterns

• Stream Composition: Use BufferedStream to decouple reader/writer rates and avoid partial reads/writes:

  use Amp\ByteStream\BufferedStream;
  
  $buffered = new BufferedStream($underlyingStream);
  $data = yield $buffered->read(); // Reads full chunks or buffers until delimiter
  

• Backpressure Handling: Leverage onOverrun()/onUnderrun() callbacks when building custom writable streams (e.g., a rate-limited HTTP client sink).
• Pipeline Construction: Chain streams for text/byte transformations:

  $pipeline = (new Pipeline())
      ->pipe(new Filter\HexDecode())
      ->pipe(new Filter\Gunzip());
  yield $pipeline->write($hexEncodedGzip);
  

• Integration with Amp HTTP: Use ResourceStream for raw socket I/O, and Pipe to proxy data between client/server streams in reverse proxies or HTTP/2 gateways.
• File Streams: Wrap fopen() handles with ResourceStream for non-blocking file reads/writes inside Loop::run() contexts.

Gotchas and Tips

• Memory Safety: Avoid large unbounded BufferedStream usage—pair with LimitStream or manual backpressure signaling to prevent OOM in high-throughput systems.
• EOF Handling: read() returns null on EOF, not ''. Always check: if ($chunk === null) { break; }.
• Resource Cleanup: Manually close streams via close() in finally blocks—PHP’s GC may not promptly release underlying resources.
• Blocking Fallbacks: ResourceStream for pipes/stdin/stdout may block on non-blocking streams if not properly set via stream_set_blocking(false). Always validate.
• Custom Streams: Implement ReadableStreamInterface/WritableStreamInterface carefully—ensure cancel() terminates pending operations cleanly to prevent leaks.
• Testing: Mock streams using CallableStream or InMemoryStream (if available in your version) for predictable unit tests without sockets/files.