PHP stream_filter_register() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Stream

Definition

In PHP, stream_filter_register() registers a custom stream filter class under a name you can pass to stream_filter_append() or stream_filter_prepend().

The class must extend php_user_filter and implement filter(). Registration only publishes the name; you still attach the filter to each stream you want to transform.

Syntax

Call stream_filter_register() with the values you need. Start with this line.

PHP
stream_filter_register("my.upper", UpperFilter::class);
CallWhat it does
stream_filter_register("my.upper", "UpperFilter")Registers the class under the filter name my.upper.
stream_filter_register("str.*", "StringFilter")Registers a wildcard family; onCreate() decides which names succeed.
stream_filter_append($fp, "my.upper")Attaches the registered filter to a stream after registration.

Register once per request before you append or prepend the filter. Built-in filters such as string.toupper do not need registration. Custom filters usually use stream_bucket_make_writeable() and stream_bucket_append() inside filter().

Library declarations
PHP
stream_filter_register(string $filter_name, string $class): bool

Parameters

ParameterDescription
filter_nameRequired. The public name for the filter, for example my.upper. Wildcards like str.* are allowed.
classRequired. Name of a class that extends php_user_filter.

Return Value

Return ValueDescription
booltrue on success, false on failure (for example when the name is already registered).

PHP Examples

Example 1 — Register and Use an Uppercase Filter

Define a small filter class, register it, then write through php://memory.

PHP
<?php
class TutorialUpperFilter extends php_user_filter
{
    public function filter($in, $out, &$consumed, $closing): int
    {
        while ($bucket = stream_bucket_make_writeable($in)) {
            $bucket->data = strtoupper($bucket->data);
            $consumed += $bucket->datalen;
            stream_bucket_append($out, $bucket);
        }
        return PSFS_PASS_ON;
    }
}

$ok = stream_filter_register("tutorial.upper", TutorialUpperFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "tutorial.upper", STREAM_FILTER_WRITE);
fwrite($fp, "register me");
rewind($fp);

echo $ok ? "registered" : "failed", PHP_EOL;
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. The class extends php_user_filter and uppercases each bucket.
  2. stream_filter_register() publishes the name tutorial. upper.
  3. stream_filter_append() attaches that name to the memory stream.
  4. Writing and reading shows REGISTER ME.

Example 2 — Registration Fails When the Name Exists

Register the same name twice and print both boolean results.

PHP
<?php
class OnceFilter extends php_user_filter
{
    public function filter($in, $out, &$consumed, $closing): int
    {
        while ($bucket = stream_bucket_make_writeable($in)) {
            $consumed += $bucket->datalen;
            stream_bucket_append($out, $bucket);
        }
        return PSFS_PASS_ON;
    }
}

$first = stream_filter_register("tutorial.once", OnceFilter::class);
$second = stream_filter_register("tutorial.once", OnceFilter::class);

echo $first ? "first=1" : "first=0", PHP_EOL;
echo $second ? "second=1" : "second=0", PHP_EOL;

How It Works

  1. The first registration succeeds and returns true.
  2. The second attempt uses the same filter name.
  3. PHP rejects the duplicate and returns false.
  4. Always check the return value when registering.

Example 3 — Register Then List Filters

After registration, confirm your filter name appears in stream_get_filters().

PHP
<?php
class ListMeFilter extends php_user_filter
{
    public function filter($in, $out, &$consumed, $closing): int
    {
        while ($bucket = stream_bucket_make_writeable($in)) {
            $consumed += $bucket->datalen;
            stream_bucket_append($out, $bucket);
        }
        return PSFS_PASS_ON;
    }
}

stream_filter_register("tutorial.listme", ListMeFilter::class);
$filters = stream_get_filters();
echo in_array("tutorial.listme", $filters, true) ? "found" : "missing", PHP_EOL;
echo in_array("string.toupper", $filters, true) ? "has_toupper" : "no_toupper", PHP_EOL;

How It Works

  1. A pass-through filter class is registered as tutorial. listme.
  2. stream_get_filters() returns the known filter names.
  3. in_array() checks for the custom name.
  4. The built-in string. toupper name is present too.

Frequently Asked Questions

It registers a custom php_user_filter class under a filter name so you can attach it with append or prepend.
No. Filters such as string.toupper are already available.
It must extend php_user_filter and implement filter($in, $out, &$consumed, $closing), usually returning PSFS_PASS_ON.
The name may already be registered, or the class may be missing or invalid.
No. After registration you still call stream_filter_append() or stream_filter_prepend() on each stream.

Next: stream_filter_remove()

stream_filter_remove() takes a filter resource you got from stream_filter_append() or stre.

stream_filter_remove() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful