Home PHP Stream stream_bucket_new() PHP stream_bucket_new() Function 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.
$bucket = stream_bucket_new($this->stream, "EXTRA"); Call What 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 stream_bucket_new(resource $stream, string $buffer): StreamBucket Parameters Parameter Description stream Required. The stream resource the filter is attached to. Inside a filter, use $this->stream. buffer Required. The string content to store in the new bucket.
Return Value Return Value Description StreamBucket A new bucket object containing the buffer text.
PHP Examples 1. Append a Suffix Bucket 2. Replace Data With a Fresh Bucket 3. Inject a Prefix Bucket Example 1 — Append a Suffix Bucket Forward the original data, then create a new bucket with a suffix when the filter closes.
<?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 Incoming buckets are passed through unchanged. On close, stream_bucket_new() builds a bucket holding "!". stream_bucket_append() places that suffix after the text. 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
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 We still call make_writeable() so PHP knows the input was consumed. The original buckets are not appended, so their text is discarded. stream_bucket_new() supplies the only output text. Reading the stream shows REPLACED. Frequently Asked Questions What does stream_bucket_new() do in PHP? It creates a new bucket containing a string you choose. Custom stream filters use it to inject extra data into the output brigade.
What should I pass as the stream argument? Inside a filter class, pass $this->stream. That property points at the stream your filter is attached to.
Does stream_bucket_new() write to the stream by itself? No. It only builds a bucket object. You still need stream_bucket_append() or stream_bucket_prepend().
When would I create a new bucket instead of editing one? When you need bytes that were never in the input, such as a header, footer, or full replacement string.
Is this required for string.toupper? No. Built-in filters already manage buckets for you. stream_bucket_new() is for custom php_user_filter classes.
About the author Developer, cloud engineer, and technical writer
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
Helpful Share Copy link Suggestion