PHP stream_bucket_make_writeable() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Stream

Definition

In PHP, stream_bucket_make_writeable() takes the next bucket out of a brigade so your custom stream filter can read and change its data.

It is almost always called in a while loop inside php_user_filter::filter(). When no buckets remain, it returns null and the loop stops. This is advanced filter plumbing, not an everyday string function.

Syntax

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

PHP
while ($bucket = stream_bucket_make_writeable($in)) { /* ... */ }
CallWhat it does
stream_bucket_make_writeable($in)Pulls the next writable bucket from the input brigade, or null when empty.
$bucket->data = strtoupper($bucket->data)Typical next step: change the text stored in the bucket.
$consumed += $bucket->datalenTell PHP how many bytes you consumed from that bucket.

The spelling is make_writeable (with an e). After PHP 8.4 the return type is StreamBucket; older versions returned a plain object with data and datalen properties.

Library declarations
PHP
stream_bucket_make_writeable(resource $brigade): ?StreamBucket

Parameters

ParameterDescription
brigadeRequired. The input brigade resource, usually the $in argument of your filter() method.

Return Value

Return ValueDescription
StreamBucket|nullThe next bucket to edit, or null when the brigade has no more buckets.

PHP Examples

Example 1 — Read Buckets and Uppercase Them

Pull each bucket, change its data, then send it out. php://memory keeps the demo offline.

PHP
<?php
class MakeWriteableUpperFilter 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;
    }
}

stream_filter_register("demo.mw.upper", MakeWriteableUpperFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.mw.upper", STREAM_FILTER_WRITE);
fwrite($fp, "make writeable");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. stream_bucket_make_writeable($in) returns one bucket at a time.
  2. We replace $bucket->data with an uppercase copy.
  3. stream_bucket_append() returns the bucket to the stream pipeline.
  4. Reading the memory stream prints MAKE WRITEABLE.

Example 2 — Stop When the Brigade Is Empty

When make_writeable() returns null, the while loop ends. An empty write still works safely.

PHP
<?php
class CountBucketsFilter extends php_user_filter
{
    public function filter($in, $out, &$consumed, $closing): int
    {
        $count = 0;
        while ($bucket = stream_bucket_make_writeable($in)) {
            $count++;
            $consumed += $bucket->datalen;
            stream_bucket_append($out, $bucket);
        }
        if ($closing) {
            stream_bucket_append($out, stream_bucket_new($this->stream, " buckets=" . $count));
        }
        return PSFS_PASS_ON;
    }
}

stream_filter_register("demo.mw.count", CountBucketsFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.mw.count", STREAM_FILTER_WRITE);
fwrite($fp, "abc");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. The loop runs once for the single data bucket from fwrite().
  2. When no buckets remain, make_writeable() returns null and the loop stops.
  3. On close we append a short note that shows how many buckets we saw.
  4. The sample output is abc buckets=1.

Example 3 — Replace Digits While Reading Buckets

Use make_writeable() as the entry point, then edit the text before appending.

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

stream_filter_register("demo.mw.mask", MaskDigitsBucketFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.mw.mask", STREAM_FILTER_WRITE);
fwrite($fp, "id=42 user=7");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. Each bucket is taken with stream_bucket_make_writeable().
  2. preg_replace() turns every digit into a star.
  3. The edited bucket is appended to $out.
  4. The memory stream now holds id=** user=*.

Frequently Asked Questions

It removes the next bucket from a brigade and returns it so your custom filter can change the data. When the brigade is empty it returns null.
That is the historical PHP function name. Use stream_bucket_make_writeable exactly as written.
You mainly use data (the string chunk) and datalen (its length). In PHP 8.4+ the object is a StreamBucket instance.
Yes for most apps. Prefer built-in filters like string.toupper. Learn make_writeable only when you need a custom filter class.
PHP passes it into your filter() method when data flows through a stream that has your filter attached.

Next: stream_bucket_new()

stream_bucket_new() builds a brand-new bucket holding a string, ready to append or prepend.

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