Manuel PHP
Précédent |  | Suivant

# stream_filter_register

(PHP 5)

stream_filter_register -- Enregistre un filtre de flux

## 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 :

Valeur retournée | Signification
--- | ---
`PSFS_PASS_ON` | Indique la réussite ; les données sont dans le paramètre `out`, une `bucket brigade`.
`PSFS_FEED_ME` | Indique que le filtre n'a aucune donnée à retourner, et requiert d'autres données du flux.
`PSFS_ERR_FATAL` (défaut) | Indique que le flux a rencontré une erreur fatale, et ne peut continuer. Si aucune valeur n'est retournée par cette méthode, `PSFS_ERR_FATAL` est utilisé.

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.

Propriété | Contenu
--- | ---
`FilterClass->filtername` | Une chaîne contenant le nom du filtre est instanciée. Les filtres peuvent être enregistrés sous de noms multiples ainsi qu'avec des jokers. Utilisez cette propriété pour déterminer qu'elle est le nom utilisé.
`FilterClass->params` | Le contenu du paramètre passé `params` à la fonction stream_filter_append() ou la fonction stream_filter_prepend().

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().

Précédent | Sommaire | Suivant
stream_filter_prepend | Niveau supérieur | stream_filter_remove