stream_bucket_append — Funktion · PHP-Referenz

Signatur

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

Beschreibung

stream_bucket_append wird ausschließlich innerhalb von benutzerdefinierten Stream-Filtern verwendet, die von php_user_filter erben. In der filter()-Methode solcher Filter werden Daten als verkettete Liste von sogenannten Buckets geliefert, die in einer Brigade zusammengefasst sind. Mit dieser Funktion kann ein Bucket ans Ende der Ausgabe-Brigade angehängt werden.

Der typische Arbeitsablauf in einem Stream-Filter sieht so aus: Buckets werden nacheinander mit stream_bucket_make_writeable aus der Eingabe-Brigade entnommen, ihr Inhalt ($bucket->data) wird transformiert, und das veränderte Bucket wird anschließend mit stream_bucket_append an die Ausgabe-Brigade angehängt, damit der verarbeitete Datenstrom weitergeleitet werden kann.

Im Unterschied zu stream_bucket_prepend, das ein Bucket an den Anfang der Brigade stellt, sorgt stream_bucket_append dafür, dass die ursprüngliche Reihenfolge der Daten erhalten bleibt – was in den meisten Anwendungsfällen das gewünschte Verhalten ist.

Geeignet für Datentransformationen wie Verschlüsselung, Komprimierung oder Zeichenersetzungen in Datenströmen.
Funktioniert nur innerhalb der filter()-Methode einer php_user_filter-Unterklasse.

Parameter

Name	Typ	Default	Beschreibung
$brigade Pflicht	resource		Die Ausgabe-Bucket-Brigade, an deren Ende das Bucket angehängt wird. Wird in der `filter()`-Methode als Parameter `$out` übergeben.
$bucket Pflicht	object		Das Bucket-Objekt, das an die Brigade angehängt werden soll. Bucket-Objekte werden typischerweise über `stream_bucket_make_writeable` oder `stream_bucket_new` erzeugt und besitzen eine `data`-Eigenschaft mit dem Datenstrom-Inhalt.

Rückgabewert

Typ

void

Beschreibung

Diese Funktion gibt keinen Wert zurück.

Beispiele

Einfacher ROT13-Stream-Filter mit stream_bucket_append

<?php
class Rot13Filter extends php_user_filter
{
    public function filter($in, $out, &$consumed, bool $closing): int
    {
        while ($bucket = stream_bucket_make_writeable($in)) {
            // Daten transformieren
            $bucket->data = str_rot13($bucket->data);
            $consumed += $bucket->datalen;

            // Verarbeitetes Bucket an die Ausgabe-Brigade anhängen
            stream_bucket_append($out, $bucket);
        }

        return PSFS_PASS_ON;
    }
}

// Filter registrieren
stream_filter_register('rot13_custom', 'Rot13Filter');

// Datei schreiben mit Filter
$fp = fopen('php://temp', 'w+');
stream_filter_append($fp, 'rot13_custom');

fwrite($fp, 'Hallo Welt!');
rewind($fp);
echo stream_get_contents($fp);
fclose($fp);

Unyyb Jryg!

Zeilenweise Verarbeitung: Präfix an jede Zeile anhängen

<?php
class PrefixFilter extends php_user_filter
{
    public string $prefix = '[LOG] ';

    public function filter($in, $out, &$consumed, bool $closing): int
    {
        while ($bucket = stream_bucket_make_writeable($in)) {
            // Jede Zeile mit Präfix versehen
            $lines = explode("\n", $bucket->data);
            $bucket->data = implode("\n", array_map(
                fn(string $line) => $line !== '' ? $this->prefix . $line : $line,
                $lines
            ));
            $consumed += $bucket->datalen;

            stream_bucket_append($out, $bucket);
        }

        return PSFS_PASS_ON;
    }
}

stream_filter_register('prefix_filter', 'PrefixFilter');

$fp = fopen('php://temp', 'w+');
stream_filter_append($fp, 'prefix_filter');

fwrite($fp, "Zeile 1\nZeile 2\nZeile 3");
rewind($fp);
echo stream_get_contents($fp);
fclose($fp);

[LOG] Zeile 1 [LOG] Zeile 2 [LOG] Zeile 3

// Wichtig · Fallstricke

Nur innerhalb von Stream-Filtern nutzbar: stream_bucket_append ist ausschließlich innerhalb der filter()-Methode einer Klasse sinnvoll, die php_user_filter erweitert. Ein Aufruf außerhalb dieses Kontexts führt zu undefiniertem Verhalten.

Reihenfolge beachten: Im Gegensatz zu stream_bucket_prepend fügt diese Funktion das Bucket am Ende der Brigade ein. Für die meisten Transformationsfilter ist stream_bucket_append die richtige Wahl, um die Datenreihenfolge zu bewahren.

Datenlänge aktualisieren: Wenn $bucket->data manuell verändert wird und sich dadurch die Länge ändert, sollte $bucket->datalen ebenfalls aktualisiert werden, da $consumed auf dieser Länge basieren kann.

Siehe auch

stream_bucket_prepend stream_bucket_make_writeable stream_bucket_new stream_filter_register stream_filter_append php_user_filter