StreamBucket — Klasse · PHP-Referenz

Signatur

class StreamBucket

Beschreibung

StreamBucket ist eine interne PHP-Klasse, die innerhalb von benutzerdefinierten Stream-Filtern (Unterklassen von php_user_filter) verwendet wird. Ein Objekt dieser Klasse repräsentiert einen einzelnen Datenblock, der durch die Filter-Pipeline fließt. Stream-Filter verarbeiten Daten in solchen Buckets, wenn sie aus einem Stream gelesen oder in einen Stream geschrieben werden.

Objekte vom Typ StreamBucket werden nicht direkt vom Entwickler instanziiert, sondern automatisch von der PHP-Engine erzeugt und über die Brigade-Methoden stream_bucket_make_writeable() bzw. stream_bucket_append() bereitgestellt. Ein Bucket besitzt die Eigenschaften $data (den Inhalt des Blocks als String) sowie $datalen (die Länge der Daten in Bytes).

Innerhalb der filter()-Methode eines benutzerdefinierten Filters können Buckets aus der eingehenden Brigade entnommen, der Inhalt verändert und anschließend an die ausgehende Brigade angehängt werden. Dies ermöglicht eine effiziente, blockweise Verarbeitung von Datenströmen, ohne den gesamten Inhalt auf einmal in den Speicher laden zu müssen.

Typische Anwendungsfälle sind das transparente Verschlüsseln, Komprimieren, Konvertieren (z. B. ROT13, Base64) oder Filtern von Daten beim Lesen aus oder Schreiben in Dateien und Netzwerk-Sockets.

Beispiele

Einfacher Stream-Filter mit StreamBucket: ROT13-Transformation

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

            // Verarbeiteten Bucket an die ausgehende Brigade anhängen
            stream_bucket_append($out, $bucket);
        }

        return PSFS_PASS_ON;
    }
}

// Filter registrieren
stream_filter_register('rot13.custom', 'Rot13Filter');

// Datei mit Filter öffnen
$fp = fopen('php://memory', 'r+');
fwrite($fp, 'Hallo Welt!');
rewind($fp);

stream_filter_append($fp, 'rot13.custom');

echo stream_get_contents($fp);
// Ausgabe: Unyy Jryg!
fclose($fp);

Unyy Jryg!

Neuen Bucket erzeugen und an ausgehende Brigade anhängen

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

            // Neuen Bucket mit Präfix erzeugen und anhängen
            $newBucket = stream_bucket_new($this->stream, '[GEFILTERT] ' . $bucket->data);
            stream_bucket_append($out, $newBucket);
        }

        return PSFS_PASS_ON;
    }
}

stream_filter_register('prefix.filter', 'PrefixFilter');

$fp = fopen('php://memory', 'r+');
fwrite($fp, 'Zeile eins');
rewind($fp);

stream_filter_append($fp, 'prefix.filter');

echo stream_get_contents($fp);
// Ausgabe: [GEFILTERT] Zeile eins
fclose($fp);

[GEFILTERT] Zeile eins

// Wichtig · Fallstricke

Eigenschaften: Die wichtigsten öffentlichen Eigenschaften eines StreamBucket-Objekts sind:

$data – Der Inhalt des Datenblocks als string. Kann innerhalb der filter()-Methode direkt verändert werden.
$datalen – Die Länge der Daten in Bytes (int). Sollte nach einer Änderung von $data aktualisiert werden, damit $consumed korrekt berechnet werden kann.

Nicht direkt instanziieren: StreamBucket-Objekte dürfen nicht mit new StreamBucket() erzeugt werden. Für neue Buckets steht die Funktion stream_bucket_new() zur Verfügung.

Achtung bei $datalen: Wenn $bucket->data verändert wird, muss $bucket->datalen manuell auf strlen($bucket->data) gesetzt werden, da die Engine diesen Wert nicht automatisch aktualisiert. Andernfalls kann es zu inkorrekten $consumed-Werten und unerwarteten Puffer-Problemen kommen.

Siehe auch

php_user_filter stream_filter_register stream_filter_append stream_bucket_make_writeable stream_bucket_append stream_bucket_new stream_bucket_prepend