PHP Function Reference

PHP stream_filter_register() Function



The PHP stream_filter_register() function registers a user defined stream filter. It allows to implement user defined filter on any registered stream used with all the other filesystem functions, such as fopen(), fread() etc.

Syntax

stream_filter_register(filter_name, class)

Parameters

filter_name Required. Specify the filter name to be registered.
class Required. To implement a filter, It is required to define a class as an extension of php_user_filter with a number of member functions. When performing read/write operations on the stream to which the filter is attached, PHP will pass the data through this filter (and any other filters attached to that stream) to modify the data as desired.

Return Value

Returns true on success or false on failure. Return false if the filter_name is already defined.

Example: filter for capitalizing characters on given stream

The example below implements a filter called StrToUpper on the test.txt stream which capitalizes all letter characters written to/read from this stream.

<?php
//defining the filter class
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;
  }
}

//registering the filter
stream_filter_register("StrToUpper", "StrToUpper_filter");

$fp = fopen("test.txt", "w");

//attaching the registered filter to the stream
stream_filter_append($fp, "StrToUpper");

//writing some content to the stream
fwrite($fp, "This is a test file.\n");
fwrite($fp, "It contains dummy content.\n");
fwrite($fp, "Line number 3 is added.\n");

//closing the file
fclose($fp);

//reading the content of the file
readfile("test.txt");
?>

The output of the above code will be:

THIS IS A TEST FILE.
IT CONTAINS DUMMY CONTENT.
LINE NUMBER 3 IS ADDED.

Example: registering a generic filter class to match multiple filter names

Consider one more example which illustrates on registering a generic filter class to match multiple filter names.

<?php
//defining the filter class
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 {
      //some other str.* filter is called, returns false
      return false;
    }

    return true;
  }
}

//registering the filter
stream_filter_register("str.*", "string_filter");

$fp = fopen("test.txt", "w");

//attach the registered filter to the stream
stream_filter_append($fp, "str.tolower");

//writing some content to the stream
fwrite($fp, "This is a test file.\n");
fwrite($fp, "It contains dummy content.\n");
fwrite($fp, "Line number 3 is added.\n");

//closing the file
fclose($fp);

//reading the content of the file
readfile("test.txt");
?>

The output of the above code will be:

this is a test file.
it contains dummy content.
line number 3 is added.

❮ PHP Streams Reference