stream_filter_append
(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
stream_filter_append — ストリームにフィルタを付加する
説明
resource
$stream
,string
$filtername
,int
$read_write
= ?,mixed
$params
= ?): resource
filtername
で指定されたフィルタを、
stream
に付加されているフィルタのリストに加えます。
パラメータ
stream
-
対象となるストリーム。
filtername
-
フィルタ名。
read_write
-
デフォルトでは、 stream_filter_append() は ストリームが読み込み用に開かれている場合は (つまり、オープンモードが
r
あるいは+
を伴う場合は)、 フィルタをリードフィルタチェイン
に追加し、 ストリームが書き出し用に開かれている場合は(つまり、オープンモードがw
かa
か、あるいは+
を伴う場合は)、ライトフィルターチェィン
にも追加します。STREAM_FILTER_READ
・STREAM_FILTER_WRITE
・STREAM_FILTER_ALL
をread_write
パラメータに渡すことで、この挙動を変えることができます。 params
-
このフィルタは、指定された
params
と共に、 リストの末尾に追加され、ストリームに対する操作の中で最後に呼び出されます。 フィルタをリストの先頭に加えたいときは、stream_filter_prepend() を使ってください。
戻り値
成功した場合にリソース、失敗した場合に false
を返します。
このリソースは、stream_filter_remove()
をコールする際にこのフィルタインスタンスを参照するために使用可能です。
false
が返されるのは、stream
がリソースではない場合や
filtername
が見つからない場合です。
例
例1 フィルタの適用される場所を制御する
<?php
/* ファイルを読み書き用に開く */
$fp = fopen('test.txt', 'w+');
/* ROT13 フィルタをライトフィルタチェインに付加する。
* リードフィルタチェインには付加しない。*/
stream_filter_append($fp, "string.rot13", STREAM_FILTER_WRITE);
/* 単純な文字列をファイルに書き出す。
* この文字列には、出口で ROT13 変換が適用される。
*/
fwrite($fp, "This is a test\n");
/* ファイルの最初に戻る */
rewind($fp);
/* 書き出した内容を読み戻す。
* もし、フィルタがリードフィルタチェインにも
* 付加されていれば、再び読み出し時に ROT13 が適用され、
* テキストは元の状態に戻るはず。 */
fpassthru($fp);
fclose($fp);
/* 期待される出力
---------------
Guvf vf n grfg
*/
?>
注意
注意: カスタム(ユーザー)フィルタを使うには
カスタムフィルタをfiltername
に指定するためには、 まず stream_filter_register() 関数でそれを登録しておく 必要があります。
注意: ストリームデータは(ローカルおよびリモートの)リソースからチャンク単位で 読み込まれ、内部バッファに保持されます。新しいフィルタがストリームに 追加されると、内部バッファのデータがその時点でフィルタリングされます。 これは stream_filter_prepend() の挙動とは違います。
注意: フィルタが読み込み用および書き込み用に追加されると、フィルタのインスタンスが 2 つ作成されます。両方のフィルタリソースを取得するには、
STREAM_FILTER_READ
とSTREAM_FILTER_WRITE
で stream_filter_append() を 2 回コールしなければなりません。
参考
- stream_filter_register() - ユーザー定義のストリームフィルタを登録する
- stream_filter_prepend() - フィルタをストリームに付加する
- stream_get_filters() - 登録されているフィルタのリストを取得する
User Contributed Notes 2 notes
Note that stream filters applied to STDOUT are not called when outputting via echo or print.
This is easily demonstrated with the standard ROT13 filter:
<?php
stream_filter_append( STDOUT, "string.rot13" );
print "Hello PHP\n";
// Prints "Hello PHP"
fprintf( STDOUT, "Hello PHP\n" );
// Prints "Uryyb CUC"
?>
If you want to filter STDOUT, you may have better luck with an output buffering callback added via ob_start:
http://php.net/manual/en/function.ob-start.php
At the time of this writing, there is an open PHP feature request to support echo and print for stream filters:
https://bugs.php.net/bug.php?id=30583
Hello firends
The difference betweem adding a stream filter first or last in the filte list in only the order they will be applied to streams.
For example, if you're reading data from a file, and a given filter is placed in first place with stream_filter_prepend()the data will be processed by that filter first.
This example reads out file data and the filter is applied at the beginning of the reading operation:
<?php
/* Open a test file for reading */
$fp = fopen("test.txt", "r");
/* Apply the ROT13 filter to the
* read filter chain, but not the
* write filter chain */
stream_filter_prepend($fp, "string.rot13",
STREAM_FILTER_READ);
// read file data
$contents=fread($fp,1024);
// file data is first filtered and stored in $contents
echo $contents;
fclose($fp);
?>
On the other hand, if stream_filter_append() is used, then the filter will be applied at the end of the data operation. The thing about this is only the order filters are applied to streams. Back to the example, it's not the same thing removing new lines from file data and then counting the number of characters, than performing the inverse process. In this case, the order that filters are applied to stream is important.
This example writes a test string to a file. The filter is applied at the end of the writing operation:
<?php
/* Open a test file for writing */
$fp = fopen("test.txt", "w+");
/* Apply the ROT13 filter to the
* write filter chain, but not the
* read filter chain */
stream_filter_append($fp, "string.rot13",
STREAM_FILTER_WRITE);
/* Write a simple string to the file
* it will be ROT13 transformed at the end of the
stream operation
* way out */
fwrite($fp, "This is a test\n"); // string data is
first written, then ROT13 tranformed and lastly
written to file
/* Back up to the beginning of the file */
rewind($fp);
$contents=fread($fp,512);
fclose($fp);
echo $contents;
?>
In the first case, data is transformed at the end of the writing operation, while in the second one, data is first filtered and then stored in $contents.
With Regards
Hossein