PHP stream_filter_prepend() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Stream

Definition

In PHP, stream_filter_prepend() attaches a named filter at the beginning of a stream's filter chain so it runs before filters that were already there.

Use it when filter order matters. Unlike append, newly prepended filters do not reprocess data that was already sitting in internal buffers.

Syntax

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

PHP
$filter = stream_filter_prepend($stream, "string.toupper");
CallWhat it does
stream_filter_prepend($fp, "string.toupper")Prepends uppercase using the default mode for the stream.
stream_filter_prepend($fp, "string.rot13", STREAM_FILTER_READ)Puts ROT13 first on the read chain.
stream_filter_prepend($fp, "string.tolower", STREAM_FILTER_WRITE)Puts lowercase first on the write chain.

Order is the main reason to choose prepend. If you only need one filter, append and prepend behave the same for new data. For custom filters, register them with stream_filter_register() first.

Library declarations
PHP
stream_filter_prepend(resource $stream, string $filter_name, int $mode = 0, mixed $params = null): resource|false

Parameters

ParameterDescription
streamRequired. The stream resource to filter.
filter_nameRequired. Built-in or registered filter name.
modeOptional. STREAM_FILTER_READ, STREAM_FILTER_WRITE, or STREAM_FILTER_ALL.
paramsOptional. Extra parameters for filters that accept them.

Return Value

Return ValueDescription
resource|falseA filter resource on success, or false on failure.

PHP Examples

Example 1 — Prepend string.toupper on Write

Attach string.toupper at the front of the write chain and write mixed-case text to php://memory.

PHP
<?php
$fp = fopen("php://memory", "w+");
stream_filter_prepend($fp, "string.toupper", STREAM_FILTER_WRITE);

fwrite($fp, "prepend me");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. A memory stream is opened.
  2. string. toupper is prepended for writes.
  3. fwrite() sends the mixed-case phrase through the filter.
  4. Reading back shows PREPEND ME.

Example 2 — Show Prepend Order With Two Filters

Prepend toupper after tolower is already attached, so toupper becomes first in the chain.

PHP
<?php
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "string.tolower", STREAM_FILTER_WRITE);
stream_filter_prepend($fp, "string.toupper", STREAM_FILTER_WRITE);

fwrite($fp, "AbC");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. tolower is appended first.
  2. toupper is then prepended, so it runs before tolower on write.
  3. Data becomes ABC, then abc.
  4. The final stored text is abc.

Example 3 — ROT13 on Read With Prepend

Write plain text first, rewind, prepend ROT13 for reading, then read the transformed view.

PHP
<?php
$fp = fopen("php://memory", "w+");
fwrite($fp, "Hello");
rewind($fp);

stream_filter_prepend($fp, "string.rot13", STREAM_FILTER_READ);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. Plain text Hello is stored without a write filter.
  2. After rewind, ROT13 is prepended on the read chain.
  3. stream_get_contents() reads through that filter.
  4. The printed result is Uryyb.

Frequently Asked Questions

It attaches a filter at the beginning of a stream's filter chain so the filter runs before filters already present.
When the new filter must run first, or when you want the buffer behavior that does not reprocess already-buffered data.
No. Data already in internal buffers is not pushed through a newly prepended filter.
Yes. Names like string.toupper and string.rot13 work without registration.
Keep the resource returned by stream_filter_prepend() and pass it to stream_filter_remove().

Next: stream_filter_register()

stream_filter_register() registers a custom stream filter class under a name you can pass .

stream_filter_register() 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