PHP stream_bucket_new() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Stream

Definition

In PHP, stream_bucket_new() builds a brand-new bucket holding a string, ready to append or prepend inside a custom stream filter.

Use it when your filter must inject extra bytes that did not come from the input brigade, such as a prefix, suffix, or replacement chunk. The first argument is usually $this->stream from your filter object.

Syntax

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

PHP
$bucket = stream_bucket_new($this->stream, "EXTRA");
CallWhat it does
stream_bucket_new($this->stream, "!")Creates a one-character bucket to append as a marker.
stream_bucket_new($this->stream, PHP_EOL)Creates a bucket that adds a newline.
stream_bucket_append($out, stream_bucket_new($this->stream, "ok"))Builds a bucket and sends it out in one step.

stream_bucket_new() is only useful inside user filters. For normal string work, just use string functions. From PHP 8.4 the return value is a StreamBucket object.

Library declarations
PHP
stream_bucket_new(resource $stream, string $buffer): StreamBucket

Parameters

ParameterDescription
streamRequired. The stream resource the filter is attached to. Inside a filter, use $this->stream.
bufferRequired. The string content to store in the new bucket.

Return Value

Return ValueDescription
StreamBucketA new bucket object containing the buffer text.

PHP Examples

Example 1 — Append a Suffix Bucket

Forward the original data, then create a new bucket with a suffix when the filter closes.

PHP
<?php
class SuffixBucketFilter 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, "!"));
        }
        return PSFS_PASS_ON;
    }
}

stream_filter_register("demo.new.suffix", SuffixBucketFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.new.suffix", STREAM_FILTER_WRITE);
fwrite($fp, "ready");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. Incoming buckets are passed through unchanged.
  2. On close, stream_bucket_new() builds a bucket holding "!".
  3. stream_bucket_append() places that suffix after the text.
  4. The memory stream reads as ready!.

Example 2 — Replace Data With a Fresh Bucket

Consume the input buckets, then emit only a new bucket you create yourself.

PHP
<?php
class ReplaceBucketFilter extends php_user_filter
{
    public function filter($in, $out, &$consumed, $closing): int
    {
        while ($bucket = stream_bucket_make_writeable($in)) {
            $consumed += $bucket->datalen;
            // Drop the original bucket on purpose.
        }
        stream_bucket_append($out, stream_bucket_new($this->stream, "REPLACED"));
        return PSFS_PASS_ON;
    }
}

stream_filter_register("demo.new.replace", ReplaceBucketFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.new.replace", STREAM_FILTER_WRITE);
fwrite($fp, "original text");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. We still call make_writeable() so PHP knows the input was consumed.
  2. The original buckets are not appended, so their text is discarded.
  3. stream_bucket_new() supplies the only output text.
  4. Reading the stream shows REPLACED.

Example 3 — Inject a Prefix Bucket

Create a prefix with stream_bucket_new() and prepend it before the real data.

PHP
<?php
class PrefixBucketFilter 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);
            stream_bucket_prepend($out, stream_bucket_new($this->stream, ">"));
        }
        return PSFS_PASS_ON;
    }
}

stream_filter_register("demo.new.prefix", PrefixBucketFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.new.prefix", STREAM_FILTER_WRITE);
fwrite($fp, "go");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. The data bucket for "go" is appended first.
  2. stream_bucket_new() creates a one-character prefix bucket.
  3. stream_bucket_prepend() moves that prefix to the front of $out.
  4. The final text is >go.

Frequently Asked Questions

It creates a new bucket containing a string you choose. Custom stream filters use it to inject extra data into the output brigade.
Inside a filter class, pass $this->stream. That property points at the stream your filter is attached to.
No. It only builds a bucket object. You still need stream_bucket_append() or stream_bucket_prepend().
When you need bytes that were never in the input, such as a header, footer, or full replacement string.
No. Built-in filters already manage buckets for you. stream_bucket_new() is for custom php_user_filter classes.

Next: stream_bucket_prepend()

stream_bucket_prepend() adds a data bucket to the front of a brigade, so that chunk is pro.

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