stream_filter_prepend — Funktion · PHP-Referenz

Signatur

stream_filter_prepend(resource $stream, string $filtername, int $read_write = STREAM_FILTER_READ, mixed $params = null): resource|false

Beschreibung

stream_filter_prepend() fügt einen benannten Stream-Filter an den Beginn der Filterkette eines geöffneten Streams ein. Im Gegensatz zu stream_filter_append(), das den Filter ans Ende der Kette hängt, wird der mit stream_filter_prepend() hinzugefügte Filter als erster ausgeführt, wenn Daten den Stream durchlaufen. Das ist wichtig, wenn die Reihenfolge der Filterverarbeitung (z. B. erst komprimieren, dann verschlüsseln) eine Rolle spielt.

Der Parameter read_write steuert, ob der Filter auf den Lesepuffer (STREAM_FILTER_READ), den Schreibpuffer (STREAM_FILTER_WRITE) oder auf beide (STREAM_FILTER_ALL) angewendet wird. Wird kein Wert angegeben, richtet sich das Standardverhalten nach dem Öffnungsmodus des Streams.

Typische Einsatzszenarien sind das transparente De-/Komprimieren von Daten (z. B. mit zlib.inflate oder bzip2.decompress), die Zeichensatz-Konvertierung (convert.iconv.*) oder das Bereinigen von Eingaben (string.strip_tags). Die Funktion gibt eine Ressource zurück, über die der Filter später mit stream_filter_remove() wieder entfernt werden kann.

Verfügbare Filter lassen sich mit stream_get_filters() abfragen. Eigene Filter können über stream_filter_register() registriert werden.

Parameter

Name	Typ	Default	Beschreibung
$stream Pflicht	resource		Ein geöffneter Stream, an den der Filter gehängt werden soll (z. B. Rückgabewert von `fopen()`).
$filtername Pflicht	string		Name des anzuhängenden Filters, z. B. `'zlib.inflate'`, `'string.toupper'` oder `'convert.iconv.UTF-8/ISO-8859-1'`. Alle verfügbaren Filter liefert `stream_get_filters()`.
$read_write	int	STREAM_FILTER_READ	Bestimmt, auf welche Richtung der Filter angewendet wird: `STREAM_FILTER_READ`, `STREAM_FILTER_WRITE` oder `STREAM_FILTER_ALL`.
$params	mixed	null	Optionale Parameter, die an den Filter übergeben werden. Kann ein skalarer Wert, ein Array oder `null` sein. Die Interpretation obliegt dem jeweiligen Filter.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt bei Erfolg eine Ressource zurück, die den angehängten Filter repräsentiert und z. B. an stream_filter_remove() übergeben werden kann. Bei einem Fehler (z. B. unbekannter Filtername) wird false zurückgegeben.

Beispiele

Großbuchstaben-Filter an Lese-Stream voranstellen

<?php
// Temporären Stream erzeugen und Text hineinschreiben
$stream = fopen('php://temp', 'r+');
fwrite($stream, 'Hallo Welt');
rewind($stream);

// Filter an den Anfang der Lesekette hängen
$filter = stream_filter_prepend($stream, 'string.toupper', STREAM_FILTER_READ);

// Gefilterten Inhalt lesen
echo stream_get_contents($stream); // Ausgabe: HALLO WELT

// Filter wieder entfernen
stream_filter_remove($filter);
fclose($stream);

HALLO WELT

zlib-Kompression beim Schreiben voranstellen

<?php
// Datei zum Schreiben öffnen
$stream = fopen('output.zlib', 'wb');

// Kompressionsfilter an den Anfang der Schreib-Filterkette hängen
stream_filter_prepend($stream, 'zlib.deflate', STREAM_FILTER_WRITE, 6);

fwrite($stream, 'Das sind komprimierte Daten.');
fclose($stream);

// Datei wieder lesen und dekomprimieren
$in = fopen('output.zlib', 'rb');
stream_filter_prepend($in, 'zlib.inflate', STREAM_FILTER_READ);
echo stream_get_contents($in);
fclose($in);

Das sind komprimierte Daten.

Reihenfolge von prepend vs. append verstehen

<?php
$stream = fopen('php://temp', 'r+');
fwrite($stream, 'hello world');
rewind($stream);

// Erst append: string.toupper (kommt in der Kette an zweiter Stelle)
stream_filter_append($stream, 'string.toupper', STREAM_FILTER_READ);

// Dann prepend: string.rot13 (wird VOR toupper ausgeführt)
stream_filter_prepend($stream, 'string.rot13', STREAM_FILTER_READ);

// Reihenfolge: rot13 -> toupper
// 'hello world' -> rot13 -> 'uryyb jbeyq' -> toupper -> 'URYYB JBEYQ'
echo stream_get_contents($stream);
fclose($stream);

URYYB JBEYQ

// Wichtig · Fallstricke

Filterreihenfolge: Werden mehrere Filter mit stream_filter_prepend() nacheinander registriert, wird der zuletzt vorangestellte Filter als erster ausgeführt. Die Reihenfolge der Filterausführung kann schwer nachzuvollziehen sein — ein Kommentar im Code ist empfehlenswert.

Unbekannte Filter: Wird ein nicht registrierter Filtername übergeben, gibt die Funktion false zurück und erzeugt eine PHP-Warnung. Mit stream_get_filters() lässt sich vorab prüfen, welche Filter verfügbar sind.

Sicherheit: Filter wie string.strip_tags oder convert.quoted-printable-decode sollten nicht als einzige Sicherheitsmaßnahme gegen XSS oder Injection eingesetzt werden. Sie ersetzen keine gezielte Validierung und Ausgabekodierung.

Siehe auch

stream_filter_append stream_filter_remove stream_filter_register stream_get_filters stream_context_create