stream_filter_register

(PHP 5, PHP 7, PHP 8)

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

説明

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

参考

関連キーワード:  フィルタ, ストリーム, filter, 登録, stream, 定義, ユーザー, register, 実装, 付加