Signatur
Beschreibung
stream_bucket_make_writeable() wird innerhalb von benutzerdefinierten Stream-Filtern verwendet, die die abstrakte Klasse php_user_filter erweitern. Sie entnimmt das erste verfügbare Bucket aus der übergebenen Brigade (einer verketteten Liste von Datenpuffern) und gibt es als beschreibbares Objekt zurück.
Ein Bucket repräsentiert einen einzelnen Datenpuffer innerhalb einer Brigade. Das zurückgegebene Objekt besitzt die Eigenschaften data (der eigentliche Inhalt als String) und datalen (die Länge der Daten). Durch Manipulation dieser Eigenschaften kann der Filterinhalt vor der Weitergabe verändert werden.
Typischerweise wird die Funktion in einer Schleife innerhalb der filter()-Methode eines benutzerdefinierten Stream-Filters aufgerufen: Solange die Brigade Buckets enthält, werden diese der Reihe nach entnommen, bearbeitet und anschließend mit stream_bucket_append() oder stream_bucket_prepend() in die Ausgabe-Brigade eingefügt.
Dieses Muster erlaubt eine effiziente, chunk-basierte Transformation von Datenströmen, beispielsweise für Verschlüsselung, Kompression oder Zeichenkodierung, ohne den gesamten Stream auf einmal in den Speicher laden zu müssen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $brigade Pflicht | resource | Die Eingabe-Brigade, aus der das erste Bucket entnommen wird. Wird typischerweise als Parameter der filter()-Methode eines php_user_filter übergeben. |
Rückgabewert
data (string) und datalen (int) zurück, wenn ein Bucket in der Brigade verfügbar ist. Gibt null zurück, wenn die Brigade leer ist.Beispiele
Einfacher Stream-Filter, der Text in Großbuchstaben umwandelt
<?php
class UpperCaseFilter extends php_user_filter {
public function filter($in, $out, &$consumed, bool $closing): int {
while ($bucket = stream_bucket_make_writeable($in)) {
// Daten manipulieren
$bucket->data = strtoupper($bucket->data);
$consumed += $bucket->datalen;
// Bucket in die Ausgabe-Brigade einfügen
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}
}
stream_filter_register('uppercase', 'UpperCaseFilter');
$fp = fopen('php://memory', 'r+');
fwrite($fp, 'Hallo Welt!');
rewind($fp);
stream_filter_append($fp, 'uppercase');
echo stream_get_contents($fp);
// Ausgabe: HALLO WELT!
fclose($fp);ROT13-Filter mit stream_bucket_make_writeable
<?php
class Rot13Filter extends php_user_filter {
public function filter($in, $out, &$consumed, bool $closing): int {
while ($bucket = stream_bucket_make_writeable($in)) {
$bucket->data = str_rot13($bucket->data);
$consumed += $bucket->datalen;
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}
}
stream_filter_register('rot13filter', 'Rot13Filter');
$stream = fopen('php://memory', 'r+');
fwrite($stream, 'PHP ist toll');
rewind($stream);
stream_filter_append($stream, 'rot13filter');
$result = stream_get_contents($stream);
fclose($stream);
echo $result;// Wichtig · Fallstricke
Achtung: stream_bucket_make_writeable() darf nur innerhalb der filter()-Methode eines benutzerdefinierten Stream-Filters (Unterklasse von php_user_filter) aufgerufen werden. Ein Aufruf außerhalb dieses Kontexts führt zu undefiniertem Verhalten oder Fehlern.
Die Eigenschaft datalen des Bucket-Objekts wird nicht automatisch aktualisiert, wenn data manuell geändert wird. Wenn die Länge der Daten nach der Manipulation abweicht, sollte datalen ebenfalls manuell auf strlen($bucket->data) gesetzt werden, damit der korrekte Wert zu $consumed addiert werden kann.
Da Buckets Referenzen auf interne PHP-Speicherpuffer sind, sollte man die Objekte nach dem Einfügen in die Ausgabe-Brigade nicht weiter verwenden.