PHP stream_bucket_prepend() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Stream

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.

PHP
stream_bucket_prepend($out, $bucket);
CallWhat 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
PHP
stream_bucket_prepend(resource $brigade, StreamBucket $bucket): void

Parameters

ParameterDescription
brigadeRequired. The brigade to modify, usually the $out argument in filter().
bucketRequired. The bucket to place at the front. PHP 8.4+ expects a StreamBucket instance.

Return Value

Return ValueDescription
voidNothing is returned. The brigade is updated in place.

PHP Examples

Example 1 — Prepend a Prefix Mark

Append the real text, then prepend a mark so the mark appears first in the result.

PHP
<?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

  1. The data bucket holding "title" is appended to $out.
  2. A new "#" bucket is created with stream_bucket_new().
  3. stream_bucket_prepend() moves that mark to the front.
  4. 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
<?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

  1. Here the mark is appended before the data bucket.
  2. For a single chunk, append-before-data matches prepend-after-data.
  3. With several buckets, prepend and append timing diverge.
  4. This sample still prints #title so you can compare the two styles.

Example 3 — Wrap Text With Brackets

Prepend an opening bracket bucket and append a closing one around the payload.

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

stream_filter_register("demo.prepend.wrap", WrapBucketFilter::class);
$fp = fopen("php://memory", "w+");
stream_filter_append($fp, "demo.prepend.wrap", STREAM_FILTER_WRITE);
fwrite($fp, "ok");
rewind($fp);
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);

How It Works

  1. The payload bucket is appended first.
  2. Prepend puts "[" at the front of the brigade.
  3. A final append adds "]" at the end.
  4. The combined result is [ok].

Frequently Asked Questions

It inserts a bucket at the beginning of a brigade so that chunk comes before the buckets already queued.
Use prepend when you need a prefix or any data that must appear before what is already on $out.
Yes, if you call it repeatedly in a loop over many buckets. Practice with one fwrite() first.
It is part of the advanced user-filter toolkit. Most beginners only need built-in filters like string.toupper.
No. It returns void and updates the brigade you pass in.

Next: stream_context_create()

stream_context_create() builds a stream context resource that stores options and parameter.

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