Stream Decorators Laravel Package

Getting Started

Start by installing via Composer (composer require zbateson/stream-decorators), then identify a concrete use case—e.g., rate-limiting uploads or trimming output before writing to a log. Begin with one of the included decorators like LimitStream or BufferStream. The easiest first step: wrap a file stream to read only the first N bytes:

use ZBateson\StreamDecorators\LimitStream;

$stream = fopen('php://temp', 'r+');
fwrite($stream, 'Hello, this is a test string.');
rewind($stream);

$limited = new LimitStream($stream, 5); // Read only 5 bytes
echo stream_get_contents($limited); // Outputs: Hello

Check the src/ directory for decorator classes and read README.md (if present) for the most common patterns and constructor signatures.

Implementation Patterns

• Chaining decorators: Build composable pipelines by nesting decorators (e.g., new LoggingStream(new LimitStream($base, 1024))). Each decorator wraps another stream, preserving StreamInterface semantics.
• Stateless transformations: Use decorators like TrimStream to normalize input before processing (e.g., for CSV parsing or webhook payload handling).
• Dynamic behavior injection: In CLI tools, wrap php://stdin with BufferStream to avoid partial reads, or apply ChunkStream for streaming large files without memory exhaustion.
• Testing with mocks: Decorators make stream-based logic testable—decorate php://memory streams in unit tests to assert exact read/write behavior without file I/O.
• Framework integration: In Laravel, wrap request/response streams (e.g., ResponseFactory output) with RateLimitStream to enforce throughput caps before sending responses.

Gotchas and Tips

• Stream position: Decorators like LimitStream and SeekableStream may alter ftell() behavior—always verify stream position after operations, especially when seeking or wrapping non-seekable streams (e.g., php://input).
• Read/write proxying: Only methods explicitly overridden by the decorator are intercepted; others (e.g., stream_set_timeout(), stream_context_get()) fall back to the underlying stream. Test edge cases with context-aware operations.
• Constructor expectations: Decorators expect a StreamInterface or valid resource. Passing null or invalid streams causes silent failures—validate wrapped streams first.
• Memory vs. performance: Buffering decorators (e.g., BufferStream) trade memory for throughput—avoid wrapping huge streams in memory buffers in production unless necessary.
• Extending: To add custom logic (e.g., encryption or compression), extend StreamDecoratorTrait and implement only the methods you need (e.g., read(), write()) rather than reinventing StreamInterface.
• Non-seekable caveats: LimitStream’s behavior is undefined when seeking before the current position on non-seekable streams—plan fallbacks (e.g., discard via read() instead of seek()).