Signatur
Beschreibung
stream_bucket_new() erstellt ein neues Bucket-Objekt, das einen Datenpuffer für einen Stream repräsentiert. Buckets werden innerhalb von benutzerdefinierten Stream-Filtern (Klassen, die php_user_filter erweitern) verwendet, um Daten in der Methode filter() zu verarbeiten und weiterzugeben.
Ein Bucket kapselt einen Datenblock ($buffer) zusammen mit einer Längenangabe ($datalen) und einer Referenz auf den zugehörigen Stream. Der erzeugte Bucket kann anschließend mit stream_bucket_append() oder stream_bucket_prepend() in eine Bucket-Brigade eingefügt werden, die dann an den nächsten Filter oder die Anwendung weitergeleitet wird.
Diese Funktion ist besonders nützlich, wenn man in einem Stream-Filter neue oder veränderte Daten produziert, die nicht direkt aus dem eingehenden Bucket-Strom stammen – beispielsweise beim Einfügen von Präfixen, Suffixen oder beim Ersetzen von Inhalten während des Lese- oder Schreibvorgangs.
- stream_bucket_append(): Hängt einen Bucket ans Ende einer Brigade an.
- stream_bucket_prepend(): Fügt einen Bucket am Anfang einer Brigade ein.
- stream_bucket_make_writeable(): Entnimmt den nächsten Bucket aus einer Brigade zur Bearbeitung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $stream Pflicht | resource | Der Stream, für den das Bucket erzeugt werden soll. Innerhalb von php_user_filter::filter() steht hierfür das Attribut $this->stream zur Verfügung. |
|
| $buffer Pflicht | string | Der Dateninhalt (Puffer), den das neue Bucket enthalten soll. Die Länge wird automatisch ermittelt und im Attribut $bucket->datalen gespeichert. |
Rückgabewert
data (der Pufferinhalt als String) und datalen (die Länge des Puffers als Integer).Beispiele
Einfacher Stream-Filter mit stream_bucket_new
<?php
class UpperCaseFilter extends php_user_filter {
public function filter($in, $out, &$consumed, bool $closing): int {
while ($bucket = stream_bucket_make_writeable($in)) {
$consumed += $bucket->datalen;
// Neues Bucket mit veränderten Daten erzeugen
$newBucket = stream_bucket_new($this->stream, strtoupper($bucket->data));
stream_bucket_append($out, $newBucket);
}
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);Präfix an jeden Datenblock 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;
// Präfix-Bucket voranstellen
$prefix = stream_bucket_new($this->stream, '[LOG] ');
stream_bucket_append($out, $prefix);
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}
}
stream_filter_register('prefix', 'PrefixFilter');
$fp = fopen('php://memory', 'r+');
fwrite($fp, 'Datenbankfehler aufgetreten.');
rewind($fp);
stream_filter_append($fp, 'prefix');
echo stream_get_contents($fp);
fclose($fp);// Wichtig · Fallstricke
Verwendungskontext: stream_bucket_new() ist ausschließlich sinnvoll innerhalb der filter()-Methode eines benutzerdefinierten Stream-Filters (Klasse, die php_user_filter erweitert). Außerhalb dieses Kontexts hat die Funktion keinen praktischen Nutzen.
Speicherverwaltung: Die erzeugten Bucket-Objekte werden intern von PHP verwaltet. Es ist nicht notwendig, sie manuell zu zerstören. Allerdings sollte darauf geachtet werden, dass alle erzeugten Buckets entweder in die ausgehende Brigade eingefügt oder verworfen werden, um Speicherlecks zu vermeiden.
PHP-Version: Die genaue interne Implementierung und das Verhalten von Bucket-Objekten können zwischen PHP-Versionen leicht variieren. Die Eigenschaften data und datalen sind jedoch stabil und zuverlässig verfügbar.