stream_filter_register

(PHP 5, PHP 7, PHP 8)

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

Описание

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() - Прикрепляет фильтр к потоку