【PHP8.x】php_user_filter::streamプロパティの使い方

Copy
1<?php
2
3/**
4 * カスタムストリームフィルタの例。
5 * ストリームに関連付けられたコンテキストオプションから接頭辞を取得し、
6 * 各データの先頭にその接頭辞を追加します。
7 */
8class PrefixAddingFilter 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, $closing)
20    {
21        // $this->stream は、このフィルタがアタッチされている基となるストリームリソースです。
22        // stream_context_create で作成・適用されたコンテキストのオプションをここから取得できます。
23        $contextOptions = stream_context_get_options($this->stream);
24
25        // コンテキストオプションから、フィルタに渡されたカスタムの接頭辞を取得します。
26        // 'filter_options' => ['prefix' => '...'] の形式で設定されていることを期待します。
27        $prefix = isset($contextOptions['filter_options']['prefix'])
28            ? $contextOptions['filter_options']['prefix']
29            : '[デフォルト接頭辞] '; // オプションが設定されていない場合のデフォルト値
30
31        // 入力バッファからストリームバケットを1つずつ取り出し、加工して出力バッファへ追加します。
32        while ($bucket = stream_bucket_make_writeable($in)) {
33            // バケットのデータに接頭辞を追加します。
34            $bucket->data = $prefix . $bucket->data;
35            // 消費されたバイト数を更新します。
36            $consumed += $bucket->datalen;
37            // 加工済みのバケットを出力バッファに追加します。
38            stream_bucket_append($out, $bucket);
39        }
40
41        // 処理を継続し、次のフィルタまたは実際のストリームにデータを渡すことを示します。
42        return PSFS_PASS_ON;
43    }
44}
45
46// -----------------------------------------------------------
47// フィルタの登録と利用
48// -----------------------------------------------------------
49
50// 1. カスタムフィルタクラスをシステムに登録します。
51// これにより、"prefix_filter" という名前で PrefixAddingFilter クラスが使えるようになります。
52stream_filter_register("prefix_filter", PrefixAddingFilter::class);
53
54// 2. ストリームコンテキストを作成します。
55// このコンテキストには、フィルタが利用するカスタムオプションを含めます。
56$contextOptions = [
57    'filter_options' => [
58        'prefix' => '>>> ', // フィルタに渡したいカスタムの接頭辞
59    ],
60];
61$context = stream_context_create($contextOptions);
62
63// 3. 一時メモリ上に読み書き可能なストリームを開きます。
64// `fopen` 関数の第四引数で、上で作成したストリームコンテキストを適用します。
65$stream = fopen('php://temp', 'r+', false, $context);
66if (!$stream) {
67    die("エラー: ストリームのオープンに失敗しました。\n");
68}
69
70// 4. 開いたストリームにカスタムフィルタをアタッチします。
71// これにより、このストリームへの書き込みデータがフィルタによって加工されるようになります。
72stream_filter_append($stream, 'prefix_filter', STREAM_FILTER_WRITE);
73
74// 5. ストリームにデータを書き込みます。
75// この書き込み時に PrefixAddingFilter::filter メソッドが実行され、データが加工されます。
76fwrite($stream, "Hello, World!\n");
77fwrite($stream, "PHP stream filters are powerful.\n");
78
79// 6. ストリームポインタを先頭に戻し、フィルタが適用されたデータを読み込みます。
80fseek($stream, 0);
81echo "--- フィルタ適用後のデータ ---\n";
82echo stream_get_contents($stream);
83echo "------------------------------\n";
84
85// 7. ストリームを閉じ、リソースを解放します。
86fclose($stream);
87
88?>

PHPのストリームフィルタは、ファイルやネットワーク通信などのデータ（ストリーム）を読み書きする際に、データを途中で加工するための強力な機能です。php_user_filterクラスを継承することで、独自のデータ加工ロジックを持つカスタムフィルタを作成できます。

php_user_filterクラスのstreamプロパティは、このフィルタがアタッチされている「元のストリームリソース」を指します。このプロパティは引数を持たず、ストリームの操作に利用できるresource型の値を返します。サンプルコードでは、この$this->streamを利用してstream_context_get_options()関数を呼び出し、フィルタが関連付けられているストリームコンテキストのオプションを取得しています。

作成されたPrefixAddingFilterクラスは、filterメソッド内でこのストリームコンテキストから取得したカスタムの接頭辞を、書き込まれる各データに追加する役割を持っています。filterメソッドは、入力バッファ$inからデータを取り出し、加工して出力バッファ$outに書き戻します。この処理が完了すると、PSFS_PASS_ONを返して次のフィルタや実際のストリームへデータを渡すことを示します。

フィルタを利用するには、まずstream_filter_register()でカスタムフィルタをシステムに登録します。次に、stream_context_create()関数を使って、フィルタに渡したいオプション（ここではfilter_options内のprefix）を設定したストリームコンテキストを作成します。このコンテキストをfopen()でストリームを開く際に適用し、stream_filter_append()でフィルタをストリームにアタッチします。これにより、fwrite()でストリームに書き込まれるデータは、自動的にフィルタによって加工され、stream_get_contents()で読み出す際に加工済みのデータが得られます。

Copy
1<?php
2
3/**
4 * MyStreamInspectorFilter クラスは、php_user_filter を継承したカスタムストリームフィルタです。
5 * このフィルタは、データの内容を変更せず、フィルタが適用されている元のストリームリソース（$this->stream）
6 * から stream_get_contents を使用してデータを一時的に読み取る方法を示します。
7 *
8 * システムエンジニアを目指す初心者の方へ：
9 * PHPのストリームフィルタは、ファイルやネットワーク接続などのストリームを読み書きする際に、
10 * データを加工する機能です。`php_user_filter` クラスを継承してカスタムフィルタを作成し、
11 * `filter` メソッドに加工ロジックを実装します。
12 * `$this->stream` プロパティは、このフィルタが適用されている「元の」ストリームそのものを指します。
13 * `stream_get_contents()` 関数は、指定されたストリームの残りの内容を全て読み取るために使用されます。
14 */
15class MyStreamInspectorFilter extends php_user_filter
16{
17    /**
18     * ストリームフィルタリング処理を実行します。
19     * ストリームからの読み込みまたは書き込みが発生するたびにこのメソッドが呼び出されます。
20     *
21     * @param resource $in 入力バケットブリッジ。フィルタが処理すべきデータが含まれます。
22     * @param resource $out 出力バケットブリッジ。処理されたデータがここに書き込まれます。
23     * @param int $consumed 処理されたバイト数を格納するための参照引数。
24     * @param bool $closing ストリームが閉じられているかどうかを示すブール値。
25     * @return int フィルタリングのステータスコード。
26     *             PSFS_PASS_ON: フィルタリングが成功し、データを次に渡します。
27     *             PSFS_FEED_ME: フィルタリング処理を継続するために、より多くのデータが必要です。
28     *             PSFS_ERR_FATAL: 致命的なエラーが発生しました。
29     */
30    public function filter($in, $out, &$consumed, $closing)
31    {
32        // $this->stream は、このフィルタが適用されている元のストリームリソース（例：fopenで開かれたファイル）です。
33        // stream_get_contents() を使用して、このリソースからデータを読み取ることができます。
34        //
35        // 注意：フィルタリング処理中に $this->stream から直接読み取ることは、通常は推奨されません。
36        // これは、元のストリームの内部ポインタを移動させ、その後のストリーム操作や他のフィルタの動作に
37        // 予期せぬ影響を与える可能性があるためです。
38        //
39        // この例では、`$this->stream` が `resource` 型であり、`stream_get_contents()` の引数として
40        // 渡せることを示すために、デバッグ目的で一時的に少量のデータを読み取っています。
41        if (is_resource($this->stream)) {
42            // 現在のストリームポインタの位置を保存します。
43            $current_pos = ftell($this->stream);
44            
45            // ストリームの先頭に移動し、最初の10バイトだけを読み取ります。
46            // これにより、フィルタリング処理中に元のストリームの全体を読み込んでしまうのを防ぎます。
47            fseek($this->stream, 0);
48            $first_few_bytes = stream_get_contents($this->stream, 10);
49            
50            // 読み取り後、元のストリームポインタの位置に戻します。
51            // これにより、データフローへの影響を最小限に抑えます。
52            fseek($this->stream, $current_pos);
53            
54            // 読み取った内容は、PHPのエラーログに出力します。
55            // 実際のデータフローには影響を与えず、フィルタの動作確認に役立ちます。
56            error_log("Debug: Original stream's first 10 bytes (from \$this->stream): '" . $first_few_bytes . "'");
57        }
58
59        // ここからが主要なフィルタリング処理です。
60        // この例では、入力ストリーム（$in）からデータを読み取り、加工せずにそのまま出力ストリーム（$out）に渡します。
61        // これを「透過フィルタ」と呼びます。
62        while ($bucket = stream_bucket_make_writeable($in)) {
63            // `$bucket->data` にフィルタリング対象のデータが含まれます。
64            // 通常、ここでデータの加工ロジックを記述します。
65            // 例: $bucket->data = strtoupper($bucket->data); // 全て大文字に変換
66            
67            // 処理されたバイト数を更新します。
68            $consumed += $bucket->datalen;
69            
70            // 加工済みのデータバケットを出力ストリームに追加します。
71            stream_bucket_append($out, $bucket);
72        }
73
74        // フィルタリング処理が正常に完了し、データを次に渡すことを示します。
75        return PSFS_PASS_ON;
76    }
77}
78
79// 1. カスタムストリームフィルタを登録します。
80// "stream_inspector" という名前で MyStreamInspectorFilter クラスを登録します。
81stream_filter_register("stream_inspector", MyStreamInspectorFilter::class)
82    or die("Failed to register filter.");
83
84// 2. フィルタを適用するためのストリーム（例として一時メモリ）を作成します。
85// "php://temp" はメモリ上のテンポラリストリームで、ファイルI/Oのように扱えます。
86$stream = fopen("php://temp", "r+");
87if (!$stream) {
88    die("Failed to open php://temp stream.");
89}
90
91// 3. ストリームに初期データを書き込みます。
92$original_data = "This is some example data for the stream filter demonstration.";
93fwrite($stream, $original_data);
94
95// 4. ストリームポインタを先頭に戻します。
96// これにより、読み込み操作を最初から開始できます。
97fseek($stream, 0);
98
99// 5. 作成したストリームにカスタムフィルタを適用します。
100// `STREAM_FILTER_READ` は、ストリームからデータを読み込む際にフィルタが適用されることを意味します。
101stream_filter_append($stream, "stream_inspector", STREAM_FILTER_READ);
102
103// 6. フィルタリングされた内容（この例では元のまま）をストリームから読み取ります。
104// この `stream_get_contents()` の呼び出し中に、登録したフィルタの `filter` メソッドが実行されます。
105// `filter` メソッド内で `error_log` に出力されたデバッグメッセージは、この読み取りプロセス中に発生します。
106$read_content = stream_get_contents($stream);
107
108// 7. 結果を出力します。
109echo "--- Stream Filter Demonstration ---\n";
110echo "Original Data: " . $original_data . "\n";
111echo "Read Data (after transparent filtering): " . $read_content . "\n";
112echo "\n";
113echo ">>> 上記データ読み取り中に、フィルタの内部で `$this->stream` を使って\n";
114echo ">>> `stream_get_contents()` が呼び出されました。\n";
115echo ">>> PHPのエラーログ (php_error.logなど) を確認してください。\n";
116echo ">>> そこに「Debug: Original stream's first 10 bytes...」というメッセージが出力されています。\n";
117
118// 8. ストリームを閉じます。
119fclose($stream);
120
121?>

PHPのphp_user_filterクラスは、ファイルやネットワーク接続などのストリームデータに対して独自の加工処理を適用するためのカスタムフィルタを作成する際に継承する基底クラスです。このクラスを継承して作成するカスタムフィルタでは、filterメソッド内にデータの加工ロジックを実装します。filterメソッドは、ストリームからデータが読み込まれる（または書き込まれる）たびに呼び出され、入力データを処理して出力データに変換する役割を担います。

$this->streamプロパティは、php_user_filterクラスの内部で利用できる特別なプロパティで、このフィルタが現在適用されている「元の」ストリームリソースそのものを指します。このプロパティの戻り値はresource型であり、ファイルポインタやネットワークソケットといったストリーム操作可能な実体を表します。サンプルコードでは、この$this->streamに格納されたリソースを引数として、stream_get_contents()関数を使用しています。stream_get_contents()は、指定されたストリームの残りの内容を全て読み込むための関数です。

通常、filterメソッドの内部で$this->streamから直接データを読み取ることは、ストリームの内部ポインタが移動し、他のフィルタや後続のストリーム操作に予期せぬ影響を与える可能性があるため推奨されません。しかし、このサンプルコードでは、$this->streamがresource型であり、stream_get_contents()のようなストリーム操作関数に渡せることを示すデモンストレーションとして、一時的にストリームの先頭から少量のデータを読み取っています。このデバッグ情報はPHPのエラーログに出力されるため、実際のストリームデータフローには影響を与えず、$this->streamプロパティの機能とstream_get_contents()の基本的な利用方法を理解するのに役立ちます。