ユーザー定義のストリームフィルタを登録する

# stream_filter_register

(PHP 5, PHP 7, PHP 8)

stream_filter_register — ユーザー定義のストリームフィルタを登録する

### 説明

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

stream_filter_register() は、fopen() や fread() などのファイルシステムの関数で利用可能な 登録されているどの種類のストリームとも一緒に使うことのできる カスタムフィルタを登録します。

### パラメータ

`filter_name`

  登録するフィルタ名。

`class`

  フィルタを実装するには、まず、php_user_filter を継承したクラスのメンバ関数を実装しなくてはなりません。 `PHP` は、書き込みまたは読み出し操作を カスタムフィルタの付加されたストリームに対して行う際に、まず データをそのフィルタに(そして、付加されている他のすべてのフィルタにも) 渡し、指示どおりストリームのデータが変更されるようにします。 メソッドの実装は、php_user_filter の説明の通りにしなければなりません。 さもないと、定義されていない動作をします。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

stream_filter_register() は、 指定された `filter_name` がすでに定義されている場合、 `false` を返します。

### 例

例1 foo-bar.txt ストリームの文字を大文字化するフィルタ

下記の例は、読み込まれたり書き出されたりするデータに含まれるすべての英文字を 大文字化する `strtoupper` ストリームを実装し、`foo-bar.txt` ストリームに適用するものです。

    <?php

    /* フィルタクラスを定義する */
    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;
      }
    }

    /* PHP にフィルタを登録する */
    stream_filter_register("strtoupper", "strtoupper_filter")
        or die("Failed to register filter");

    $fp = fopen("foo-bar.txt", "w");

    /* フィルタを開いたストリームに付加する */
    stream_filter_append($fp, "strtoupper");

    fwrite($fp, "Line1\n");
    fwrite($fp, "Word - 2\n");
    fwrite($fp, "Easy As 123\n");

    fclose($fp);

    /* ファイルを読み出し出力する
     */
    readfile("foo-bar.txt");

    ?>

上の例の出力は以下となります。

    LINE1
    WORD - 2
    EASY AS 123

例2 複数のフィルタ名に対応する一般的なフィルタクラスを登録する

    <?php

    /* フィルタクラスを定義する */
    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 {
          /* その他の str.* フィルタが問い合わせられた場合は
             失敗を報告し、PHP が検索を続けられるようにする */
          return false;
        }

        return true;
      }
    }

    /* PHP にフィルタを登録する */
    stream_filter_register("str.*", "string_filter")
        or die("Failed to register filter");

    $fp = fopen("foo-bar.txt", "w");

    /* フィルタを開いたストリームに付加する
       ここで str.tolower をバインドすることも可能 */
    stream_filter_append($fp, "str.toupper");

    fwrite($fp, "Line1\n");
    fwrite($fp, "Word - 2\n");
    fwrite($fp, "Easy As 123\n");

    fclose($fp);

    /* ファイルを読み出し出力する
     */
    readfile("foo-bar.txt");
    ?>

上の例の出力は以下となります。

    LINE1
    WORD - 2
    EASY AS 123

### 参考

- stream_wrapper_register() - PHP のクラスとして実装された URL ラッパーを登録する
- stream_filter_append() - ストリームにフィルタを付加する
- stream_filter_prepend() - フィルタをストリームに付加する

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