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

# stream_filter_register

(PHP 5, PHP 7)

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

### 説明

stream_filter_register ( string `$filtername` , string `$classname` ) : bool

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

### パラメータ

`filtername`

  登録するフィルタ名。

`classname`

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

### 返り値

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

stream_filter_register() は、 指定された `filtername` がすでに定義されている場合、 `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() - フィルタをストリームに付加する