Home PHP Stream stream_bucket_prepend() PHP stream_bucket_prepend() Function Definition In PHP, stream_bucket_prepend() adds a data bucket to the front of a brigade, so that chunk is processed or written before the buckets already waiting there.
Custom stream filters use it to inject a prefix or to reverse the usual append order. For most learning demos, append is enough; prepend is the tool you reach for when order at the front matters.
Syntax Call stream_bucket_prepend() with the values you need. Start with this line.
stream_bucket_prepend($out, $bucket); Call What it does stream_bucket_prepend($out, $mark)Places $mark before any buckets already on $out. stream_bucket_prepend($out, stream_bucket_new($this->stream, "["))Creates a prefix bucket and puts it at the front. stream_bucket_append($out, $bucket)Often used after prepend so the real data follows the prefix.
Prepend changes order. If you prepend on every loop iteration for many buckets, earlier marks can end up further forward than you expect. Start with one bucket of sample text while you learn.
Library declarations stream_bucket_prepend(resource $brigade, StreamBucket $bucket): void Parameters Parameter Description brigade Required. The brigade to modify, usually the $out argument in filter(). bucket Required. The bucket to place at the front. PHP 8.4+ expects a StreamBucket instance.
Return Value Return Value Description void Nothing is returned. The brigade is updated in place.
PHP Examples 1. Prepend a Prefix Mark 2. Compare Append-Only Output 3. Wrap Text With Brackets Example 1 — Prepend a Prefix Mark Append the real text, then prepend a mark so the mark appears first in the result.
<?php
class PrependMarkFilter 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.prepend.mark", PrependMarkFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.prepend.mark", STREAM_FILTER_WRITE);
fwrite($fp, "title");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp); How It Works The data bucket holding "title" is appended to $out. A new "#" bucket is created with stream_bucket_new(). stream_bucket_prepend() moves that mark to the front. Reading php://memory prints #title. Example 2 — Compare Append-Only Output The same filter without prepend shows why prepend is needed for a leading mark.
<?php
class AppendOnlyFilter 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, stream_bucket_new($this->stream, "#"));
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}
}
stream_filter_register("demo.prepend.vs", AppendOnlyFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.prepend.vs", STREAM_FILTER_WRITE);
fwrite($fp, "title");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp); How It Works Here the mark is appended before the data bucket. For a single chunk, append-before-data matches prepend-after-data. With several buckets, prepend and append timing diverge. This sample still prints #title so you can compare the two styles. Frequently Asked Questions What does stream_bucket_prepend() do in PHP? It inserts a bucket at the beginning of a brigade so that chunk comes before the buckets already queued.
When should I use prepend instead of append? Use prepend when you need a prefix or any data that must appear before what is already on $out.
Can prepend scramble my output? Yes, if you call it repeatedly in a loop over many buckets. Practice with one fwrite() first.
Is stream_bucket_prepend() for beginners? It is part of the advanced user-filter toolkit. Most beginners only need built-in filters like string.toupper.
Does prepend return the new brigade? No. It returns void and updates the brigade you pass in.
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