stream_filter_register() は、fopen() や fread() などのファイルシステムの関数で利用可能な 登録されているどの種類のストリームとも一緒に使うことのできる カスタムフィルタを登録します。
フィルタを実装するには、まず、php_user_fitler を継承したクラスの下記に示されたメンバ関数を実装しなくてはなりません。 PHP は、書き込みまたは読み出し操作を カスタムフィルタの付加されたストリームに対して行う際に、まず データをそのフィルタに(そして、付加されている他のすべてのフィルタにも) 渡し、指示どおりストリームのデータが変更されるようにします。 下記のメソッドは、説明の通り実装されなくてはなりません。 さもないと、定義されていない動作をします。
stream_filter_register() は、 指定された filtername がすでに定義されている場合、 FALSE を返します。
int filter ( resource in, resource out, int &consumed, boolean closing)
このメソッドは、fread() や fwrite()
等の関数で、付加されたストリームからデータを読み出す時や、
データを書き込む度に呼ばれます。
in は、bucket brigade (バケツリレー隊) を指すポインターです。
これは、フィルタの対象になるデータを含む複数の
bucket オブジェクトから成っています。
out は、変更されたバケットが渡される
bucket brigade を示しています。
consumed は、参照渡しされるパラメータで、
ここには、フィルタが実際に処理した元のデータ長を加算します。
ほとんどの場合、それぞれのバケットについて、そのデータ長
$bucket->datalen を、そこに足すだけでいいはずです。
もし、ストリームが閉じようとしている時 (すなわちフィルタ連鎖の中の
最後の呼び出しだった時)、closing パラメータは、
TRUE となります。filter
パラメータは、さらに、
次の値のいずれかを終了時に返さなくてはなりません。
PSFS_PASS_ON は、処理に成功し、
out の バケツ隊 に
データが渡されたことを示します。PSFS_FEED_ME は、
その時点では返すデータがなく、ストリームからのより多くの入力データを
必要としていることを示します。
PSFS_ERR_FATAL は、フィルタにおいて、
復旧不可能なエラーが発生し、処理を継続できないことを示します。
もし、返値が返されなかった場合、 PSFS_ERR_FATAL が
想定されます。
このメソッドは、フィルタクラスのオブジェクトが実体化されるときに 呼び出されます。もし、フィルタがバッファなど他のリソースを 確保したり初期化しなくてはならない場合、この時点で行ってください。
void onclose ( void )このメソッドは、フィルタが遮断される時(通常、ストリームが遮断 される時)に呼ばれます。また、同様に、flush メソッドが 呼ばれた後に呼び出されます。 もし、何らかのリソースが、oncreate メソッドの 呼び出し時に確保されていた場合は、それらをここで廃棄するのが いいでしょう。
下記の例は、読み込まれたり書き出されたりするデータに含まれるすべての英文字を 大文字化する strtoupper ストリームを実装し、foo-bar.txt ストリームに適用するものです。
stream_wrapper_register(), stream_filter_prepend(), stream_filter_append() も参照下さい。