Signatur
Beschreibung
stream_filter_append() fügt einen Filter ans Ende der Filterkette eines Streams an. Filter werden in der Reihenfolge abgearbeitet, in der sie zur Kette hinzugefügt wurden – daher verarbeitet ein angehängter Filter Daten nach bereits vorhandenen Filtern. Um einen Filter an den Anfang zu setzen, steht stream_filter_prepend() zur Verfügung.
Der Parameter read_write bestimmt, ob der Filter auf den Lese-Datenstrom (STREAM_FILTER_READ), den Schreib-Datenstrom (STREAM_FILTER_WRITE) oder auf beide (STREAM_FILTER_ALL) angewendet wird. Wird kein Wert übergeben, wird der Filter standardmäßig nur auf den Lese-Datenstrom angehängt, sofern der Stream zum Lesen geöffnet wurde, oder auf den Schreib-Datenstrom bei einem Schreib-Stream.
PHP bringt eine Reihe eingebauter Filter mit, etwa string.rot13, string.toupper, convert.base64-encode oder zlib.deflate. Alle verfügbaren Filter lassen sich mit stream_get_filters() auflisten. Eigene Filter können über stream_filter_register() registriert werden.
Die zurückgegebene Filter-Ressource kann später an stream_filter_remove() übergeben werden, um den Filter dynamisch wieder aus der Kette zu entfernen. Dies ist besonders nützlich, wenn derselbe Stream abwechselnd gefiltert und ungefiltert verwendet werden soll.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $stream Pflicht | resource | Der Ziel-Stream, an den der Filter angehängt werden soll. Muss eine gültige Stream-Ressource sein (z. B. von fopen() oder fsockopen() zurückgegeben). |
|
| $filtername Pflicht | string | Der Name des Filters, z. B. "string.rot13", "convert.base64-encode" oder ein selbst registrierter Filtername. |
|
| $read_write | int | STREAM_FILTER_READ | Gibt an, auf welche Richtung der Filter angewendet wird. Mögliche Werte: STREAM_FILTER_READ, STREAM_FILTER_WRITE oder STREAM_FILTER_ALL. |
| $params | mixed | null | Optionale Parameter, die an den Filter übergeben werden. Können ein beliebiger PHP-Wert (z. B. ein Array oder ein String) sein; der Filter erhält sie über $this->params. |
Rückgabewert
stream_filter_remove() verwendet werden kann. Bei einem Fehler wird false zurückgegeben, z. B. wenn der angegebene Filter nicht existiert.Beispiele
Base64-Kodierung beim Schreiben in eine Datei
<?php
// Datei zum Schreiben öffnen
$fp = fopen('encoded.txt', 'w');
// Base64-Enkodierungsfilter auf den Schreib-Datenstrom hängen
stream_filter_append($fp, 'convert.base64-encode', STREAM_FILTER_WRITE);
// Dieser Text wird Base64-kodiert in die Datei geschrieben
fwrite($fp, 'Hallo, das ist ein Test!');
fclose($fp);
// Dateiinhalt prüfen
echo file_get_contents('encoded.txt');
Filter dynamisch entfernen mit der zurückgegebenen Ressource
<?php
$fp = fopen('php://temp', 'r+');
// ROT13-Filter anhängen und Ressource speichern
$filter = stream_filter_append($fp, 'string.rot13', STREAM_FILTER_WRITE);
fwrite($fp, 'Geheimtext');
rewind($fp);
echo fread($fp, 20); // Gibt ROT13-kodierten Inhalt aus
// Filter wieder entfernen
stream_filter_remove($filter);
rewind($fp);
ftruncate($fp, 0);
fwrite($fp, 'Klartext');
rewind($fp);
echo PHP_EOL . fread($fp, 20); // Gibt unkodierten Inhalt aus
fclose($fp);
Alle verfügbaren Stream-Filter auflisten
<?php
// Alle registrierten Filter anzeigen
$filters = stream_get_filters();
foreach ($filters as $filter) {
echo $filter . PHP_EOL;
}
// Wichtig · Fallstricke
Reihenfolge der Filter: Mehrere mit stream_filter_append() hinzugefügte Filter werden in der Reihenfolge ihrer Registrierung ausgeführt. Soll ein Filter mit höherer Priorität zuerst greifen, ist stream_filter_prepend() zu verwenden.
Sicherheitshinweis: Filter wie zlib.inflate oder convert.base64-decode sollten nicht unkritisch auf nicht vertrauenswürdige Eingaben angewendet werden, da manipulierte Daten zu unerwartetem Verhalten oder hohem Speicherverbrauch führen können (Zip-Bomb-Angriffe).
Fehlerbehandlung: Seit PHP 8.0 löst die Funktion bei ungültigem $stream-Argument eine TypeError-Exception aus. In älteren Versionen wurde lediglich eine Warnung ausgegeben und false zurückgegeben. Es empfiehlt sich daher, den Rückgabewert stets zu prüfen.