stream_bucket_prepend — Funktion · PHP-Referenz

Signatur

stream_bucket_prepend(resource $brigade, object $bucket): void

Beschreibung

stream_bucket_prepend() wird ausschließlich innerhalb von benutzerdefinierten Stream-Filtern verwendet, die von php_user_filter abgeleitet sind. Die Funktion fügt ein Bucket-Objekt an den Anfang der übergebenen Brigade ein, sodass es beim nächsten Verarbeitungsschritt als erstes gelesen wird.

Stream-Filter arbeiten mit sogenannten Brigaden (verkettete Listen von Buckets). Jedes Bucket enthält einen Datenpuffer ($bucket->data) und dessen Länge ($bucket->datalen). Während stream_bucket_append() das Bucket ans Ende der Brigade hängt, erlaubt stream_bucket_prepend() das Einfügen am Anfang — nützlich wenn bestimmte Daten (z. B. Header oder Präfixe) vor bereits vorhandenen Daten erscheinen sollen.

Ein neues Bucket-Objekt wird typischerweise mit stream_bucket_new() erstellt. Danach kann es mit stream_bucket_prepend() oder stream_bucket_append() in die Ausgabe-Brigade eingefügt werden. Diese Techniken sind Teil der filter()-Methode in benutzerdefinierten Stream-Filterklassen.

Nutze stream_bucket_prepend(), wenn Daten vor bereits vorhandenen Brigade-Inhalten eingefügt werden sollen.
Nutze stream_bucket_append(), wenn Daten nach vorhandenen Brigade-Inhalten eingefügt werden sollen.

Parameter

Name	Typ	Default	Beschreibung
$brigade Pflicht	resource		Die Ausgabe-Brigade, in die das Bucket eingefügt wird. Wird als Parameter `$out` an die `filter()`-Methode übergeben.
$bucket Pflicht	object		Ein Bucket-Objekt, das die zu verarbeitenden Daten enthält. Typischerweise mit `stream_bucket_new()` erstellt oder aus der Eingabe-Brigade mit `stream_bucket_make_writeable()` entnommen.

Rückgabewert

Typ

void

Beschreibung

Gibt keinen Wert zurück.

Beispiele

Stream-Filter mit Präfix via stream_bucket_prepend

<?php
class PrefixFilter extends php_user_filter
{
    public function filter($in, $out, &$consumed, bool $closing): int
    {
        // Alle eingehenden Buckets verarbeiten
        while ($bucket = stream_bucket_make_writeable($in)) {
            $consumed += $bucket->datalen;
            stream_bucket_append($out, $bucket);
        }

        // Beim letzten Chunk einen Präfix voranstellen
        if ($closing) {
            $prefix = stream_bucket_new($this->stream, "--- START ---\n");
            // Präfix vor alle anderen Buckets einfügen
            stream_bucket_prepend($out, $prefix);
        }

        return PSFS_PASS_ON;
    }
}

stream_filter_register('prefix_filter', 'PrefixFilter');

$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'prefix_filter');
fwrite($fp, "Zeile 1\n");
fwrite($fp, "Zeile 2\n");
fclose($fp);

--- START --- Zeile 1 Zeile 2

Daten transformieren und mit Prepend-Bucket ausgeben

<?php
class UppercaseWithHeaderFilter extends php_user_filter
{
    public function filter($in, $out, &$consumed, bool $closing): int
    {
        $hasData = false;

        while ($bucket = stream_bucket_make_writeable($in)) {
            $bucket->data = strtoupper($bucket->data);
            $consumed += $bucket->datalen;
            $bucket->datalen = strlen($bucket->data);
            stream_bucket_append($out, $bucket);
            $hasData = true;
        }

        if ($hasData) {
            // Header-Bucket ganz vorn einfügen
            $header = stream_bucket_new($this->stream, "[UPPERCASE OUTPUT]\n");
            stream_bucket_prepend($out, $header);
        }

        return PSFS_PASS_ON;
    }
}

stream_filter_register('uc_header', 'UppercaseWithHeaderFilter');

$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'uc_header');
fwrite($fp, "hallo welt\n");
fclose($fp);

[UPPERCASE OUTPUT] HALLO WELT

// Wichtig · Fallstricke

Nur innerhalb von Stream-Filtern verwendbar: stream_bucket_prepend() ist ausschließlich im Kontext der filter()-Methode einer von php_user_filter abgeleiteten Klasse sinnvoll. Ein Aufruf außerhalb dieses Kontexts führt zu undefiniertem Verhalten.

Die Reihenfolge, in der Buckets in die Brigade eingefügt werden, beeinflusst direkt die Ausgabe des Streams. Ein mit stream_bucket_prepend() eingefügtes Bucket erscheint vor allen bereits vorhandenen Buckets in der Brigade. Bei mehrfachem Aufruf kehrt sich die Reihenfolge entsprechend um.

Beachte, dass stream_bucket_new() für das Erstellen neuer Buckets benötigt wird und den Stream-Kontext sowie die Daten als Parameter erwartet.

Siehe auch

stream_bucket_append stream_bucket_new stream_bucket_make_writeable stream_filter_register stream_filter_append php_user_filter