Description
bool
stream_filter_register ( string filtername, string classname )
stream_filter_register() vous permet d'implémenter
votre propre filtre de flux, Ã utiliser avec les fonctions d'accès
aux données externes (comme fopen(),
fread(), etc.).
Pour ce faire, vous devez définir une classe qui étend la classe
php_user_fitler avec les membres et méthodes définies
ci-dessous. Lorsque vous réalisez des opérations de lecture et d'écriture
dans le flux auquel votre filtre est attaché, PHP passera les données
à travers votre filtre (et tous les autres filtres attachés), de façon
à ce que les données soient modifiées telles que désiré. Vous devez
implémenter les méthodes telles que décrit ci-dessous, sous peine de
comportements indéfinis.
stream_filter_register() retourne FALSE si le nom
de filtre filtername est déjà utilisé.
int
filter ( resource in, resource out, int &consumed, bool closing )
Cette méthode est appelée à chaque fois que des données sont lues ou écrites
dans le flux attaché (avec des fonctions comme fread() ou
fwrite()).
Le paramètre in est une ressource
qui pointe sur une bucket brigade qui contient un ou plusieurs
objet bucket contenant les données à filtrer.
out est une autre ressource
qui pointe sur une bucket brigade
dans laquelle les données seront placées.
consumed, qui doit toujours
être déclaré par référence, doit être incrémenté de la taille de données que
votre filtre lit et modifie. Dans la plupart des cas, cela signifie que vous
devrez incrémenter consumed avec $bucket->datalen
pour chaque $bucket.
Si le flux est en cours de fermeture (et, par conséquent, cela sera le dernier
passage dans la chaîne de filtres), le paramètre closing
vaudra TRUE La méthode filter doit retourner l'une
des trois valeurs suivantes :
bool
onCreate ( void )
Cette méthode est appelée durant l'instanciation du filtre. Si votre
filtre alloue ou initialise d'autres ressources (comme des
buffers), c'est le moment de le faire. Votre implémentation de cette méthode doit retourner
FALSE en cas d'erreur et TRUE en cas de succès.
Lorsque votre filtre est instancié pour la première fois
et que yourfilter->onCreate() est appelé, un nombre
de propriétés est disponible comme montré dans la table ci-dessous.
void
onClose ( void )
Cette méthode est appelée durant l'extinction du filtre (généralement,
lorsque le flux est fermé), et est exécutée après
l'appel de la fonction flush. Si aucune ressource
n'a été allouée ou créée durant onCreate(),
c'est le moment de les libérer.
L'exemple ci-dessous implémente un filtre appelé
rot13, sur le flux foo-bar.txt,
qui réalise un chiffrement de type ROT-13 sur toutes les lettres
lues ou écrites dans le flux.
Exemple 1. Filtre sur les lettres majuscules sur le flux foo-bar.txt
<?php
/* Définition de la classe */
class strtoupper_filter extends php_user_filter {
function filter($in, $out, &$consumed, $closing)
{
while ($bucket = stream_bucket_make_writeable($in)) {
$bucket->data = strtoupper($bucket->data);
$consumed += $bucket->datalen;
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}
}
/* Enregistrement de notre filtre avec PHP */
stream_filter_register("strtoupper", "strtoupper_filter")
or die("Erreur lors de l'enregistrement du filtre");
$fp = fopen("foo-bar.txt", "w");
/* Attachement du filtre enregistré au flux que l'on vient d'ouvrir */
stream_filter_append($fp, "strtoupper");
fwrite($fp, "Ligne1\n");
fwrite($fp, "Mot - 2\n");
fwrite($fp, "Facile comme 123\n");
fclose($fp);
/* Lecture du contenu
*/
readfile("foo-bar.txt");
?>
|
L'exemple ci-dessus va afficher : LIGNE1
MOT - 2
FACILE COMME 123 |
|
Exemple 2. Enregistrement d'une classe de filtre générique pour correspondre
avec de multiples noms de filtres.
<?php
/* Définition de la classe*/
class string_filter extends php_user_filter {
var $mode;
function filter($in, $out, &$consumed, $closing)
{
while ($bucket = stream_bucket_make_writeable($in)) {
if ($this->mode == 1) {
$bucket->data = strtoupper($bucket->data);
} elseif ($this->mode == 0) {
$bucket->data = strtolower($bucket->data);
}
$consumed += $bucket->datalen;
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}
function onCreate()
{
if ($this->filtername == 'str.toupper') {
$this->mode = 1;
} elseif ($this->filtername == 'str.tolower') {
$this->mode = 0;
} else {
/* Quelques autres filtres str.* sont demandés,
traitement de l'erreur avec PHP */
return false;
}
return true;
}
}
/* Enregistrement de notre filtre avec PHP */
stream_filter_register("str.*", "string_filter")
or die("Failed to register filter");
$fp = fopen("foo-bar.txt", "w");
/* Attachement du filtre enregistré au flux que l'on vient d'ouvrir
Nous pouvons alternativement passer à str.tolower ici */
stream_filter_append($fp, "str.toupper");
fwrite($fp, "Ligne1\n");
fwrite($fp, "Mot - 2\n");
fwrite($fp, "Facile comme 123\n");
fclose($fp);
/* Lecture du contenu
*/
readfile("foo-bar.txt");
?>
|
L'exemple ci-dessus va afficher : LINE1
MOT - 2
FACILE COMME 123 |
|
Voir aussi
stream_wrapper_register(),
stream_filter_prepend() et
stream_filter_append().
