Enregistre un filtre de flux

# stream_filter_register

(PHP 5, PHP 7, PHP 8)

stream_filter_register — Enregistre un filtre de flux

### Description

function stream_filter_register(string `$filter_name`, string `$class`): bool

stream_filter_register() permet d'implémenter son propre filtre de flux, à utiliser avec les fonctions d'accès aux données externes (comme fopen(), fread(), etc.).

### Liste de paramètres

`filter_name`

  Le nom du filtre à enregistrer.

`class`

  Pour créer une classe de filtre, il faut définir une classe qui étend la classe php_user_filter. Lorsque l'on réalise des opérations de lecture et d'écriture dans le flux auquel le filtre est attaché, PHP passera les données à travers le filtre (et tous les autres filtres attachés), de façon à ce que les données soient modifiées tel que désiré. Il faut implémenter les méthodes telles que décrites dans php_user_filter, sous peine de comportements indéfinis.

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

    LIGNE1
    MOT - 2
    FACILE COMME 123

### Voir aussi

- stream_wrapper_register() - Enregistre un gestionnaire d'URL
- stream_filter_append() - Attache un filtre à un flux en fin de liste
- stream_filter_prepend() - Attache un filtre à un flux en début de liste

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open