Регистрирует пользовательский фильтр потока

# stream_filter_register

(PHP 5, PHP 7, PHP 8)

stream_filter_register — Регистрирует пользовательский фильтр потока

### Описание

function stream_filter_register(string `$filter_name`, string `$class`): bool

Функция stream_filter_register() разрешает реализовать собственный фильтр для любого зарегистрированного потока, который используется с другими функциями файловой системы (например, fopen(), fread() и т. д.).

### Список параметров

`filter_name`

  Название регистрируемого фильтра.

`class`

  Чтобы реализовать фильтр, необходимо определить класс как расширение php_user_filter c целым рядом функций-членов. При выполнении операций чтения или записи на потоке, к которому прикреплён пользовательский фильтр, PHP будет передавать данные через пользовательский фильтр (и через любые другие фильтры, прикреплённые к потоку), так что данные могут быть изменены как требуется. Реализовать методы необходимо точно так, как описывает документация к классу php_user_filter, иначе это приведёт к неопределённому поведению.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Функция stream_filter_register() будет возвращать `false`, если фильтр с именем `filter_name` уже определили.

### Примеры

Пример #1 Фильтр для перевода букв в верхний регистр в потоке файла foo-bar.txt

Следующий пример реализует фильтр с названием `strtoupper` для потока файла foo-bar.txt. Фильтр будет приводить к верхнему регистру каждый буквенный символ, который запишут в поток или прочитают из потока.

    <?php

    /* Определяем пользовательский класс фильтра */
    class strtoupper_filter extends php_user_filter
    {
        function filter($in, $out, &$consumed, $closing)
        {
            while ($bucket = stream_bucket_make_writeable($in)) {
                $bucket->data = strtoupper($bucket->data);
                $consumed += $bucket->datalen;
                stream_bucket_append($out, $bucket);
            }

            return PSFS_PASS_ON;
        }
    }

    /* Регистрируем пользовательский фильтр в PHP */
    stream_filter_register("strtoupper", "strtoupper_filter")
        or die("Не удалось зарегистрировать фильтр")
    ;

    $fp = fopen("foo-bar.txt", "w");

    /* Присоединяем зарегистрированный фильтр к только что открытому потоку */
    stream_filter_append($fp, "strtoupper");

    fwrite($fp, "Line1\n");
    fwrite($fp, "Word - 2\n");
    fwrite($fp, "Easy As 123\n");

    fclose($fp);

    /* Читаем содержимое снова
     */
    readfile("foo-bar.txt");

Результат выполнения приведённого примера:

    LINE1
    WORD - 2
    EASY AS 123

Пример #2 Пример регистрации стандартного фильтра, который соответствует множественным именам фильтров.

    <?php

    /* Определяем пользовательский класс фильтра */
    class string_filter extends php_user_filter
    {
        var $mode;

        function filter($in, $out, &$consumed, $closing)
        {
            while ($bucket = stream_bucket_make_writeable($in)) {
                if ($this->mode == 1) {
                    $bucket->data = strtoupper($bucket->data);
                } elseif ($this->mode == 0) {
                    $bucket->data = strtolower($bucket->data);
                }

                $consumed += $bucket->datalen;
                stream_bucket_append($out, $bucket);
            }

            return PSFS_PASS_ON;
        }

        function onCreate()
        {
            if ($this->filtername == 'str.toupper') {
                $this->mode = 1;
            } elseif ($this->filtername == 'str.tolower') {
                $this->mode = 0;
            } else {
                /* Вызвали какой-то другой фильтр str.*,
             возвращаем ошибку, чтобы  PHP мог продолжить его поиск */
                return false;
            }

            return true;
        }
    }

    /* Регистрируем пользовательский фильтр в PHP */
    stream_filter_register("str.*", "string_filter")
        or die("Не удалось зарегистрировать фильтр")
    ;

    $fp = fopen("foo-bar.txt", "w");

    /* Присоединяем зарегистрированный фильтр к только что открытому потоку
       Здесь можно было бы использовать фильтр str.tolower */
    stream_filter_append($fp, "str.toupper");

    fwrite($fp, "Line1\n");
    fwrite($fp, "Word - 2\n");
    fwrite($fp, "Easy As 123\n");

    fclose($fp);

    /* Читаем содержимое снова
     */
    readfile("foo-bar.txt");

    ?>

Результат выполнения приведённого примера:

    LINE1
    WORD - 2
    EASY AS 123

### Смотрите также

- stream_wrapper_register() - Регистрирует URL-обёртку, которую реализовали как PHP-класс
- stream_filter_append() - Прикрепляет фильтр к потоку
- stream_filter_prepend() - Прикрепляет фильтр к потоку

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open