stream_filter_append

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_filter_append — ストリームにフィルタを付加する

説明

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() - 登録されているフィルタのリストを取得する

Improve This Page

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 2 notes

down

Dan J ¶

8 years ago

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

down

net_navard at yahoo dot com ¶

18 years ago

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

＋add a note