【PHP8.x】stream_filter_prepend()関数の使い方

Copy
1<?php
2
3/**
4 * PHPストリームフィルタのstream_filter_prepend関数を使用する例。
5 * この関数は、既存のストリームにフィルタを先頭に追加します。
6 *
7 * stream_filter_append との主な違いは、prependがフィルタリストの先頭に、
8 * appendが末尾にフィルタを追加する点です。
9 */
10function demonstrateStreamFilterPrepend(): void
11{
12    // メモリ上のストリームを作成 (読み書きモード)。
13    // これは一時的なメモリ上のファイルとして機能します。
14    $stream = fopen('php://memory', 'r+');
15
16    if ($stream === false) {
17        echo "エラー: ストリームの作成に失敗しました。\n";
18        return;
19    }
20
21    $originalData = "Hello, PHP World!\nThis data will be converted to uppercase.";
22    echo "--- オリジナルデータ ---\n";
23    echo $originalData . "\n\n";
24
25    // オリジナルデータをストリームに書き込む。
26    // この時点では、まだフィルタは適用されていません。
27    fwrite($stream, $originalData);
28
29    // ストリームの読み込み時に 'string.toupper' フィルタを先頭に追加します。
30    // これにより、ストリームからデータを読み出す際に全て大文字に変換されます。
31    // STREAM_FILTER_READ は、読み込み操作にのみフィルタを適用することを示します。
32    $filterResource = stream_filter_prepend($stream, 'string.toupper', STREAM_FILTER_READ);
33
34    if ($filterResource === false) {
35        echo "エラー: フィルタの追加に失敗しました。\n";
36        fclose($stream);
37        return;
38    }
39
40    // ストリームポインタを先頭に戻します。
41    // データを書き込んだ後、フィルタを適用した状態で最初から読み出すために必要です。
42    rewind($stream);
43
44    // フィルタが適用されたデータをストリームから読み込みます。
45    // 'string.toupper' フィルタが機能し、データが大文字に変換されて取得されます。
46    $filteredData = stream_get_contents($stream);
47
48    echo "--- フィルタ適用後のデータ (大文字変換) ---\n";
49    echo $filteredData . "\n";
50
51    // ストリームを閉じ、関連するリソースを解放します。
52    fclose($stream);
53}
54
55// 関数を実行します。
56demonstrateStreamFilterPrepend();
57

PHPのstream_filter_prepend関数は、ファイルやネットワーク接続などの「ストリーム」に対し、データを加工する「フィルタ」を既存のフィルタリストの先頭に追加します。この関数は、フィルタを末尾に追加するstream_filter_appendとは異なり、最も前にフィルタを挿入する点が特徴です。

サンプルコードでは、まずメモリ上に一時ストリームを作成し、元のデータを書き込んでいます。次に、stream_filter_prepend関数を使い、読み込み時にデータを全て大文字に変換するstring.toupperフィルタをストリームの先頭に適用しています。この関数は、対象となるストリーム、適用するフィルタ名、そしてSTREAM_FILTER_READのようなフィルタ適用タイミングを引数にとり、成功時にはフィルタを表すリソースを、失敗時にはfalseを返します。

フィルタ適用後、ストリームの読み込み位置を先頭に戻し、データを読み出すと、string.toupperフィルタによって元のデータが大文字に変換されて取得されることを確認できます。これにより、ストリーム経由のデータ処理を透過的にカスタマイズすることが可能です。

Copy
1<?php
2
3/**
4 * このクラスは、ストリームを通過するデータをすべて大文字に変換する
5 * カスタムフィルターを定義します。
6 * PHPの標準機能である`php_user_filter`を継承して作成します。
7 */
8class MyUpperCaseFilter extends php_user_filter
9{
10    /**
11     * ストリームに流れるデータがこのメソッドで処理されます。
12     *
13     * @param resource $in  入力バケットブリゲード。元のデータが含まれています。
14     * @param resource $out 出力バケットブリゲード。処理後のデータをここに追加します。
15     * @param int $consumed これまでに処理されたバイト数の合計を追跡します。
16     * @param bool $closing ストリームが閉じられようとしているかを示します。
17     * @return int フィルター処理の結果を示します。PSFS_PASS_ON は処理成功で次に渡すことを意味します。
18     */
19    public function filter($in, $out, &$consumed, bool $closing): int
20    {
21        // 入力バケットブリゲードからデータバケットを一つずつ取り出します。
22        while ($bucket = stream_bucket_make_writeable($in)) {
23            // バケット内のデータをすべて大文字に変換します。
24            $bucket->data = strtoupper($bucket->data);
25
26            // 処理したバイト数（データの長さ）を合計に追加します。
27            $consumed += $bucket->datalen;
28
29            // 変換後のバケットを出力バケットブリゲードに追加します。
30            stream_bucket_append($out, $bucket);
31        }
32
33        // フィルター処理が正常に完了し、データを次の段階に渡すことをシステムに伝えます。
34        return PSFS_PASS_ON;
35    }
36}
37
38// --- メイン処理 ---
39
40// カスタムフィルターをPHPのストリームフィルターシステムに登録します。
41// 'my.uppercase' という名前で MyUpperCaseFilter クラスが使えるようになります。
42if (!stream_filter_register('my.uppercase', MyUpperCaseFilter::class)) {
43    die("カスタムフィルター 'my.uppercase' の登録に失敗しました。\n");
44}
45echo "カスタムフィルター 'my.uppercase' が正常に登録されました。\n\n";
46
47// 一時的なメモリ上のストリーム（ファイルのようにデータを読み書きできる場所）を作成します。
48// 'r+' は読み書きモードを意味し、ストリームの先頭にシークできます。
49$stream = fopen('php://temp', 'r+');
50if (!$stream) {
51    die("一時ストリームの作成に失敗しました。\n");
52}
53echo "一時ストリーム ('php://temp') が作成されました。\n";
54
55// 作成したストリームに、先ほど登録したカスタムフィルターを「前置」します。
56// これにより、このストリームへの書き込み/読み込み操作が行われる際に、
57// 'my.uppercase' フィルターが最初に適用されるようになります。
58$filter = stream_filter_prepend($stream, 'my.uppercase');
59if (!$filter) {
60    fclose($stream);
61    die("フィルター 'my.uppercase' のストリームへの前置に失敗しました。\n");
62}
63echo "フィルター 'my.uppercase' がストリームに前置されました。\n\n";
64
65// ストリームに書き込む元の文字列です。
66$originalString = "Hello, World! This is a PHP stream filter example.";
67echo "元の文字列: " . $originalString . "\n";
68
69// ストリームにデータを書き込みます。
70// `stream_filter_prepend`で前置されたフィルターにより、
71// この文字列はストリームに格納される前に自動的に大文字に変換されます。
72fwrite($stream, $originalString);
73echo "元の文字列がストリームに書き込まれました。\n";
74
75// ストリームの読み書きカーソルを先頭に戻します。
76// これにより、書き込んだデータを最初から読み直すことができます。
77fseek($stream, 0);
78
79// フィルターが適用された後のデータをストリームからすべて読み込みます。
80$filteredContent = stream_get_contents($stream);
81echo "フィルター適用後の内容: " . $filteredContent . "\n\n";
82
83// ストリームを閉じ、関連するリソースを解放します。
84fclose($stream);
85echo "ストリームが閉じられました。\n";
86
87?>

stream_filter_prependは、PHPのストリーム（ファイルやネットワーク接続など、連続するデータの流れ）に対して、データが読み書きされる前に特定の処理を行うフィルターを適用する関数です。特に「prepend（前置）」の名の通り、既に適用されている他のフィルターやデフォルトの処理よりも優先して、最初にフィルターが適用されるように設定できます。

この関数は、最初の引数$streamにフィルターを適用したいストリームリソース、次にstring $filter_nameに適用するフィルターの名前を指定します。このフィルター名は、事前にstream_filter_register関数で登録されたカスタムフィルターや、PHPが提供する組み込みフィルターのいずれかである必要があります。オプションの引数int $modeはフィルターの適用モード（読み込み、書き込み、または両方）を、mixed $paramsはフィルターに渡す追加パラメータを指定できます。

処理が成功すると、この関数は新しく追加されたフィルターのリソースを返します。これにより、後からフィルターを削除するなどの操作が可能になります。失敗した場合はfalseを返します。サンプルコードでは、事前に登録した「my.uppercase」というカスタムフィルターを一時ストリームに前置することで、ストリームに書き込まれるデータが自動的にすべて大文字に変換される様子を示しています。これにより、開発者は個々の読み書き処理に変換ロジックを直接記述することなく、ストリームレベルで透過的にデータを加工できます。