<?php
namespace Clue\StreamFilter;
/**
 * Append a filter callback to the given stream.
 *
 * 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:
 *
 * ```php
 * $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:
 *
 * ```php
 * $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`:
 *
 * ```php
 * 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:
 *
 * ```php
 * 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:
 *
 * ```php
 * 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:
 *
 * ```php
 * 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()`](#remove).
 *
 * > Note that once a filter has been added to stream, the stream can no longer be passed to
 * > [`stream_select()`](https://www.php.net/manual/en/function.stream-select.php)
 * > (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()`](#fun) function.
 *
 * @param resource $stream
 * @param callable $callback
 * @param int $read_write
 * @return resource filter resource which can be used for `remove()`
 * @throws \Exception on error
 * @uses stream_filter_append()
 */

function append($stream, $callback, $read_write = STREAM_FILTER_ALL)
{
    $errstr = '';
    \set_error_handler(function ($_, $error) use (&$errstr) {
        $errstr = $error; 
    });
    try {
        $ret = \stream_filter_append($stream, register(), $read_write, $callback);
    } catch (\TypeError $e) { 
        \restore_error_handler();
        throw $e;
    } 
    \restore_error_handler();
    if ($ret === false) {
        throw new \RuntimeException('Unable to append filter: ' . $errstr);
    }
    return $ret;
}
function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL)
{
    $errstr = '';
    \set_error_handler(function ($_, $error) use (&$errstr) {
        $errstr = $error; 
    });
    try {
        $ret = \stream_filter_prepend($stream, register(), $read_write, $callback);
    } catch (\TypeError $e) { 
        \restore_error_handler();
        throw $e;
    } 
    \restore_error_handler();
    if ($ret === false) {
        throw new \RuntimeException('Unable to prepend filter: ' . $errstr);
    }
    return $ret;
}
function fun($filter, $parameters = null)
{
    $fp = \fopen('php://memory', 'w');
    $errstr = '';
    \set_error_handler(function ($_, $error) use (&$errstr) {
        $errstr = $error;
    });
    if (\func_num_args() === 1) {
        $filter = \stream_filter_append($fp, $filter, \STREAM_FILTER_WRITE);
    } else {
        $filter = \stream_filter_append($fp, $filter, \STREAM_FILTER_WRITE, $parameters);
    }
    \restore_error_handler();
    if ($filter === false) {
        \fclose($fp);
        throw new \RuntimeException('Unable to access built-in filter: ' . $errstr);
    }
    $buffer = '';
    append($fp, function ($chunk) use (&$buffer) {
        $buffer .= $chunk;
        return '';
    }, \STREAM_FILTER_WRITE);
    $closed = false;
    return function ($chunk = null) use ($fp, $filter, &$buffer, &$closed) {
        if ($closed) {
            throw new \RuntimeException('Unable to perform operation on closed stream');
        }
        if ($chunk === null) {
            $closed = true;
            $buffer = '';
            \fclose($fp);
            return $buffer;
        }
        $buffer = '';
        \fwrite($fp, $chunk);
        return $buffer;
    };
}
function remove($filter)
{
    $errstr = '';
    \set_error_handler(function ($_, $error) use (&$errstr) {
        $errstr = $error;
    });
    try {
        $ret = \stream_filter_remove($filter);
    } catch (\TypeError $e) { 
        \restore_error_handler();
        throw $e;
    } 
    \restore_error_handler();
    if ($ret === false) {
        throw new \RuntimeException('Unable to remove filter: ' . $errstr);
    }
}
function register()
{
    static $registered = null;
    if ($registered === null) {
        $registered = 'stream-callback';
        \stream_filter_register($registered, __NAMESPACE__ . '\CallbackFilter');
    }
    return $registered;
}