Documentation

functions.php

Table of Contents

Functions

append()  : resource
Append a filter callback to the given stream.
prepend()  : resource
Prepend a filter callback to the given stream.
fun()  : callable
Create a filter function which uses the given built-in `$filter`.
remove()  : bool
Remove a filter previously added via `append()` or `prepend()`.
register()  : string
Registers the callback filter and returns the resulting filter name

Functions

append()

Append a filter callback to the given stream.

append(resource $stream, callable $callback[, int $read_write = STREAM_FILTER_ALL ]) : resource

Each stream can have a list of filters attached. This function appends a filter to the end of this list.

If the given filter can not be added, it throws an Exception.

The $stream can be any valid stream resource, such as:

$stream = fopen('demo.txt', 'w+');

The $callback should be a valid callable function which accepts an individual chunk of data and should return the updated chunk:

$filter = Clue\StreamFilter\append($stream, function ($chunk) {
    // will be called each time you read or write a $chunk to/from the stream
    return $chunk;
});

As such, you can also use native PHP functions or any other callable:

Clue\StreamFilter\append($stream, 'strtoupper');

// will write "HELLO" to the underlying stream
fwrite($stream, 'hello');

If the $callback accepts invocation without parameters, then this signature will be invoked once ending (flushing) the filter:

Clue\StreamFilter\append($stream, function ($chunk = null) {
    if ($chunk === null) {
        // will be called once ending the filter
        return 'end';
    }
    // will be called each time you read or write a $chunk to/from the stream
    return $chunk;
});

fclose($stream);

Note: Legacy PHP versions (PHP < 5.4) do not support passing additional data from the end signal handler if the stream is being closed.

If your callback throws an Exception, then the filter process will be aborted. In order to play nice with PHP's stream handling, the Exception will be transformed to a PHP warning instead:

Clue\StreamFilter\append($stream, function ($chunk) {
    throw new \RuntimeException('Unexpected chunk');
});

// raises an E_USER_WARNING with "Error invoking filter: Unexpected chunk"
fwrite($stream, 'hello');

The optional $read_write parameter can be used to only invoke the $callback when either writing to the stream or only when reading from the stream:

Clue\StreamFilter\append($stream, function ($chunk) {
    // will be called each time you write to the stream
    return $chunk;
}, STREAM_FILTER_WRITE);

Clue\StreamFilter\append($stream, function ($chunk) {
    // will be called each time you read from the stream
    return $chunk;
}, STREAM_FILTER_READ);

This function returns a filter resource which can be passed to remove().

Note that once a filter has been added to stream, the stream can no longer be passed to stream_select() (and family).

Warning: stream_select(): cannot cast a filtered stream on this system in {file} on line {line}

This is due to limitations of PHP's stream filter support, as it can no longer reliably tell when the underlying stream resource is actually ready. As an alternative, consider calling stream_select() on the unfiltered stream and then pass the unfiltered data through the fun() function.

Parameters
$stream : resource
$callback : callable
$read_write : int = STREAM_FILTER_ALL
Tags
throws
Exception

on error

uses
stream_filter_append()
Return values
resource —

filter resource which can be used for remove()

prepend()

Prepend a filter callback to the given stream.

prepend(resource $stream, callable $callback[, int $read_write = STREAM_FILTER_ALL ]) : resource

Each stream can have a list of filters attached. This function prepends a filter to the start of this list.

If the given filter can not be added, it throws an Exception.

$filter = Clue\StreamFilter\prepend($stream, function ($chunk) {
    // will be called each time you read or write a $chunk to/from the stream
    return $chunk;
});

This function returns a filter resource which can be passed to remove().

Except for the position in the list of filters, this function behaves exactly like the append() function. For more details about its behavior, see also the append() function.

Parameters
$stream : resource
$callback : callable
$read_write : int = STREAM_FILTER_ALL
Tags
throws
Exception

on error

uses
stream_filter_prepend()
Return values
resource —

filter resource which can be used for remove()

fun()

Create a filter function which uses the given built-in `$filter`.

fun(string $filter[, mixed $parameters = null ]) : callable

PHP comes with a useful set of built-in filters. Using fun() makes accessing these as easy as passing an input string to filter and getting the filtered output string.

$fun = Clue\StreamFilter\fun('string.rot13');

assert('grfg' === $fun('test'));
assert('test' === $fun($fun('test'));

Please note that not all filter functions may be available depending on installed PHP extensions and the PHP version in use. In particular, HHVM may not offer the same filter functions or parameters as Zend PHP. Accessing an unknown filter function will result in a RuntimeException:

Clue\StreamFilter\fun('unknown'); // throws RuntimeException

Some filters may accept or require additional filter parameters – most filters do not require filter parameters. If given, the optional $parameters argument will be passed to the underlying filter handler as-is. In particular, note how not passing this parameter at all differs from explicitly passing a null value (which many filters do not accept). Please refer to the individual filter definition for more details. For example, the string.strip_tags filter can be invoked like this:

$fun = Clue\StreamFilter\fun('string.strip_tags', '<a><b>');

$ret = $fun('<b>h<br>i</b>');
assert('<b>hi</b>' === $ret);

Under the hood, this function allocates a temporary memory stream, so it's recommended to clean up the filter function after use. Also, some filter functions (in particular the zlib compression filters) may use internal buffers and may emit a final data chunk on close. The filter function can be closed by invoking without any arguments:

$fun = Clue\StreamFilter\fun('zlib.deflate');

$ret = $fun('hello') . $fun('world') . $fun();
assert('helloworld' === gzinflate($ret));

The filter function must not be used anymore after it has been closed. Doing so will result in a RuntimeException:

$fun = Clue\StreamFilter\fun('string.rot13');
$fun();

$fun('test'); // throws RuntimeException

Note: If you're using the zlib compression filters, then you should be wary about engine inconsistencies between different PHP versions and HHVM. These inconsistencies exist in the underlying PHP engines and there's little we can do about this in this library. Our test suite contains several test cases that exhibit these issues. If you feel some test case is missing or outdated, we're happy to accept PRs! :)

Parameters
$filter : string

built-in filter name. See stream_get_filters() or http://php.net/manual/en/filters.php

$parameters : mixed = null

(optional) parameters to pass to the built-in filter as-is

Tags
throws
RuntimeException

on error

link
http://php.net/manual/en/filters.php
see
stream_get_filters()
see
append()
Return values
callable —

a filter callback which can be append()'ed or prepend()'ed

remove()

Remove a filter previously added via `append()` or `prepend()`.

remove(resource $filter) : bool 
$filter = Clue\StreamFilter\append($stream, function () {
    // …
});
Clue\StreamFilter\remove($filter);
Parameters
$filter : resource
Tags
throws
RuntimeException

on error

uses
stream_filter_remove()
Return values
bool —

true on success or false on error

register()

Registers the callback filter and returns the resulting filter name

register() : string

There should be little reason to call this function manually.

Tags
uses
CallbackFilter
Return values
string —

filter name


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results