php_user_filter — Klasse · PHP-Referenz

Signatur

class php_user_filter

Beschreibung

php_user_filter ist die abstrakte Basisklasse, von der alle benutzerdefinierten Stream-Filter erben müssen. Durch das Ableiten dieser Klasse und das Implementieren der Methode filter() lassen sich eigene Datenverarbeitungsschritte in PHP-Streams einbetten – zum Beispiel Verschlüsselung, Kompression oder Zeichensatzkonvertierung.

Der Filter wird mit stream_filter_register() unter einem Namen registriert und kann anschließend über stream_filter_append() oder stream_filter_prepend() an bestehende Streams gehängt werden. Alternativ kann der Filter direkt im Stream-Wrapper-Pfad via php://filter angesprochen werden.

Die Methode onCreate() dient der Initialisierung des Filters (z. B. Speichern von Optionen aus $this->params) und wird einmalig aufgerufen, wenn der Filter an einen Stream gebunden wird. onClose() wird aufgerufen, wenn der Filter vom Stream entfernt oder der Stream geschlossen wird.

Die eigentliche Arbeit findet in filter() statt: Die Methode empfängt einen Bucket-Brigade-Eingang ($in), schreibt verarbeitete Daten in den Ausgang ($out) und signalisiert durch den Rückgabewert (PSFS_PASS_ON, PSFS_FEED_ME, PSFS_ERR_FATAL), was als nächstes zu tun ist.

Beispiele

ROT13-Filter als benutzerdefinierter Stream-Filter

<?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('rot13', 'Rot13Filter');

$fp = fopen('php://memory', 'r+');
stream_filter_append($fp, 'rot13');

fwrite($fp, 'Hello, World!');
rewind($fp);
echo stream_get_contents($fp); // Uryyb, Jbeyq!
fclose($fp);

Uryyb, Jbeyq!

Filter mit onCreate-Initialisierung und php://filter-URL

<?php
class UpperCaseFilter extends php_user_filter
{
    private string $encoding = 'UTF-8';

    public function onCreate(): bool
    {
        if (is_string($this->params)) {
            $this->encoding = $this->params;
        }
        return true; // Filter erfolgreich initialisiert
    }

    public function filter($in, $out, &$consumed, bool $closing): int
    {
        while ($bucket = stream_bucket_make_writeable($in)) {
            $bucket->data = mb_strtoupper($bucket->data, $this->encoding);
            $consumed    += $bucket->datalen;
            stream_bucket_append($out, $bucket);
        }
        return PSFS_PASS_ON;
    }
}

stream_filter_register('uppercase', 'UpperCaseFilter');

// Direkte Nutzung über php://filter
$url = 'php://filter/write=uppercase/resource=php://output';
$fp  = fopen($url, 'w');
fwrite($fp, 'hallo welt');
fclose($fp);

HALLO WELT

// Wichtig · Fallstricke

Rückgabewerte von filter():

PSFS_PASS_ON – Daten wurden verarbeitet und in $out geschrieben.
PSFS_FEED_ME – Es werden mehr Daten benötigt, bevor eine Ausgabe möglich ist (z. B. bei Blockchiffren).
PSFS_ERR_FATAL – Ein nicht behebbarer Fehler ist aufgetreten.

Gibt onCreate() false zurück, schlägt das Anhängen des Filters an den Stream fehl. Wird onCreate() nicht überschrieben, gibt die Standardimplementierung true zurück.

Achtung: Die Klasse stellt die öffentlichen Eigenschaften $filtername, $params und $stream bereit, die automatisch gesetzt werden, bevor onCreate() aufgerufen wird. Diese sollten nur lesend verwendet werden.

Siehe auch

stream_filter_register stream_filter_append stream_filter_prepend stream_bucket_make_writeable stream_bucket_append stream_get_filters