Fonctions sur les flux
PHP Manual

stream_filter_register

(PHP 5)

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

Liste de paramètres

filtername

Le nom du filtre à enregistrer.

classname

Pour créer une classe de filtre, vous devez définir une classe qui étend la classe php_user_fitler avec les membres et méthodes définis 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 tel que désiré. Vous devez implémenter les méthodes tel que décrit ci-dessous, sous peine de comportements indéfinis.

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 Filtre traité avec succès ; les données sont disponibles dans le paramètre out de la bucket brigade.
PSFS_FEED_ME Filtre traité avec succès ; aucune donnée disponible. Plus de données sont nécessaires depuis le flux ou avant le filtre.
PSFS_ERR_FATAL (default) Le filtre a rencontré une erreur fatale, et ne peut plus continuer.

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 votrefiltre->onCreate() est appelée, un nombre de propriétés est disponible comme montré dans la table ci-dessous.

Propriétés 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 quel nom est utilisé.
FilterClass->params Le contenu du paramètre params passé à la fonction stream_filter_append() ou la fonction stream_filter_prepend().
FilterClass->stream La ressource de flux qui est filtrée. Peut être disponible uniquement durant l'appel de la méthode filter(), lorsque le paramètre closing vaut FALSE.

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.

Valeurs de retour

Cette fonction retourne TRUE en cas de succès ou FALSE si une erreur survient.

stream_filter_register() doit toujours retourner FALSE si le paramètre filtername est déjà défini.

Exemples

Exemple #1 Filtre sur les lettres majuscules sur le flux foo-bar.txt

L'exemple ci-dessous implémente un filtre appelé strtoupper, sur le flux foo-bar.txt, qui passe en majuscule toutes les lettres écrites/lues depuis ce flux.

<?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


Fonctions sur les flux
PHP Manual