Stream Filter Laravel Package

Getting Started

Start by installing via Composer:

composer require clue/stream-filter

Then import the functions:

use function Clue\StreamFilter\append;
use function Clue\StreamFilter\fun;
use function Clue\StreamFilter\remove;

The most common first use case is applying simple transformations to streams — e.g., converting text to uppercase on write:

$stream = fopen('php://temp', 'r+');
append($stream, 'strtoupper');
fwrite($stream, 'hello'); // writes "HELLO" to the stream
rewind($stream);
echo stream_get_contents($stream); // "HELLO"

Implementation Patterns

• Stream-specific transformations: Use append() or prepend() to inject callbacks on existing streams (e.g., file, socket, php://output) for on-the-fly encoding/decoding, logging, or validation. Separate STREAM_FILTER_READ and STREAM_FILTER_WRITE modes for bidirectional control.
• Reusable filter functions: Use fun() to wrap built-in filters (zlib.deflate, string.rot13, convert.base64-encode, string.strip_tags) as pure callable functions for non-stream operations:

  $encode = fun('convert.base64-encode');
  echo $encode('data'); // 'ZGF0YQ=='
  

• Manual cleanup: Store filter resources returned by append()/prepend() and pass them to remove() to cleanly detach filters before closing streams (especially important when reusing streams or debugging).
• Buffer flushing: Leverage the optional $chunk = null signature in callbacks for append()/prepend() to handle final flushes (e.g., closing gzip output, finalizing compression).

Gotchas and Tips

• stream_select() incompatibility: Once any filter is attached via this package, the stream can no longer be used with stream_select(). Workaround: perform stream_select() on the unfiltered resource and pipe data through fun() manually.
• Error handling: Exceptions thrown inside filter callbacks are converted to E_USER_WARNING — use try/catch around stream operations or custom error handlers for debugging.
• Filter parameter gotcha: Passing null as a filter parameter explicitly (e.g., fun('filter', null)) may cause issues; omit the parameter entirely if the filter doesn’t require it (fixed in v1.4.0+).
• PHP version quirks: Avoid using $callback(null) flushing signature in PHP < 5.4. Tests confirm PHP 5.3–8.3 compatibility, but prefer modern PHP.
• Temporary stream usage: fun() uses an internal temp stream — close filters by invoking them with no arguments ($fun()) once done to avoid leaks (especially critical for compression filters).
• Namespace clarity: Functions live under Clue\StreamFilter\, not a class — ensure your use statements include function, not class.