PHP stream_bucket_append() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Stream

Definition

In PHP, stream_bucket_append() adds a data bucket to the end of a brigade. A brigade is the queue of data chunks that a user-space stream filter works with.

You call it inside a custom filter's filter() method after you finish changing a bucket. Beginners usually meet it together with stream_bucket_make_writeable() when learning how filters transform text as it flows through a stream.

Syntax

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

PHP
stream_bucket_append($out, $bucket);
CallWhat it does
stream_bucket_append($out, $bucket)Puts the finished bucket at the end of the output brigade.
stream_bucket_append($out, stream_bucket_new($this->stream, "!"))Creates a small new bucket and appends it after the other data.
stream_bucket_append($out, $bucket)Used once per bucket you pull from $in, so order stays the same.

Buckets are an advanced stream-filter detail. Everyday code usually uses built-in filters such as string.toupper. You need stream_bucket_append() only when you write your own php_user_filter class.

Library declarations
PHP
stream_bucket_append(resource $brigade, StreamBucket $bucket): void

Parameters

ParameterDescription
brigadeRequired. The output brigade resource passed to your filter as $out.
bucketRequired. The bucket to append. In PHP 8.4+ this is a StreamBucket object; older PHP used a simple object.

Return Value

Return ValueDescription
voidNothing is returned. The bucket is attached to the brigade.

PHP Examples

Example 1 — Append Uppercased Buckets

A tiny custom filter uppercases each chunk, then stream_bucket_append() sends it onward. The demo uses php://memory only.

PHP
<?php
class UpperAppendFilter 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.upper.append", UpperAppendFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.upper.append", STREAM_FILTER_WRITE);
fwrite($fp, "hello buckets");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. The filter class pulls each bucket from $in with stream_bucket_make_writeable().
  2. strtoupper() changes the text inside the bucket.
  3. stream_bucket_append() places that bucket on $out so the stream can continue.
  4. Writing through php://memory shows HELLO BUCKETS after rewind and read.

Example 2 — Append an Extra Marker Bucket

After forwarding the data, append a second bucket made with stream_bucket_new() so a marker appears at the end.

PHP
<?php
class AppendMarkFilter 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);
        }
        if ($closing) {
            stream_bucket_append($out, stream_bucket_new($this->stream, " [END]"));
        }
        return PSFS_PASS_ON;
    }
}

stream_filter_register("demo.append.mark", AppendMarkFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.append.mark", STREAM_FILTER_WRITE);
fwrite($fp, "done");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. Normal buckets are appended unchanged while the stream is open.
  2. When $closing is true, the filter creates one more bucket with the text " [END]".
  3. stream_bucket_append() adds that marker after the real data.
  4. Reading the memory stream prints done [END].

Example 3 — Keep Bucket Order Stable

Append every bucket in the same order you receive it so words stay in sequence.

PHP
<?php
class PassAppendFilter 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("demo.pass.append", PassAppendFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.pass.append", STREAM_FILTER_WRITE);
fwrite($fp, "one ");
fwrite($fp, "two ");
fwrite($fp, "three");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. Three separate fwrite() calls send three pieces of text.
  2. Each piece becomes a bucket that the filter appends in order.
  3. Because we only append, the words stay one two three.
  4. This pass-through pattern is the safest first step when learning brigades.

Frequently Asked Questions

It adds a bucket to the end of a brigade. Inside a custom stream filter, that usually means sending processed data out through $out.
Only when you write a user-space filter that extends php_user_filter. Built-in filters such as string.toupper do not require you to touch buckets.
A brigade is a list of buckets (data chunks) that PHP passes into and out of a filter. $in is the incoming list and $out is the outgoing list.
That chunk never reaches the rest of the stream, so part of the data disappears from the result.
No. Append adds at the end of the brigade. Prepend adds at the front, which can change the order of the data.

Next: stream_bucket_make_writeable()

stream_bucket_make_writeable() takes the next bucket out of a brigade so your custom strea.

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