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

Copy
1<?php
2
3/**
4 * ユーザーランドストリームフィルターの例。
5 * このフィルターは入力データを加工し、stream_bucket_new を使用して新しいストリームバケットとして出力します。
6 *
7 * stream_bucket_new は、主にストリームフィルター内で新しいデータの塊（バケット）を作成し、
8 * それを出力ストリームに追加する際に利用されます。
9 */
10class MyTransformFilter extends php_user_filter
11{
12    /**
13     * フィルターの主な処理ロジック。
14     * 入力バケットからデータを読み込み、加工後、新しいバケットとして出力ストリームに書き込みます。
15     *
16     * @param resource $in  入力バケットのコレクション。実際には内部的なSplQueueのようなオブジェクト。
17     * @param resource $out 出力バケットのコレクション。同様に内部的なオブジェクト。
18     * @param int      &$consumed 消費されたデータのバイト数。参照渡しで更新します。
19     * @param bool     $closing   ストリームが閉じられようとしているかを示すフラグ。
20     * @return int フィルターのステータス。PSFS_PASS_ONは処理を続行することを示します。
21     */
22    public function filter($in, $out, &$consumed, $closing): int
23    {
24        // 入力バケットを一つずつ処理します
25        while ($bucket = stream_bucket_make_writeable($in)) {
26            // 入力バケットから元のデータを取得
27            $originalData = $bucket->data;
28            // 消費したバイト数を更新
29            $consumed += $bucket->datalen;
30
31            // データを加工します（例: 全て大文字にし、特定のプレフィックスとサフィックスを追加）
32            $processedData = 'TRANSFORMED_[' . strtoupper($originalData) . ']_END';
33
34            // stream_bucket_new を使用して、加工済みのデータで新しいバケットを作成します。
35            // 第1引数には、このフィルターが適用されている基となるストリームリソース（$this->stream）を渡します。
36            // 第2引数には、新しいバケットに含めるデータ文字列を渡します。
37            $newBucket = stream_bucket_new($this->stream, $processedData);
38
39            // 作成した新しいバケットを出力ストリームに追加します
40            stream_bucket_append($out, $newBucket);
41        }
42
43        // データを次のフィルター、または最終的な出力に渡すことを示します
44        return PSFS_PASS_ON;
45    }
46}
47
48// ユーザーランドフィルターをPHPのシステムに登録します。
49// 'my_transform_filter' はこのフィルターの登録名、MyTransformFilter::class はフィルタークラスです。
50stream_filter_register('my_transform_filter', MyTransformFilter::class);
51
52// 一時的なメモリ内ストリームを作成します。これはファイルのように読み書きできる仮想的なストリームです。
53$stream = fopen('php://temp', 'r+');
54
55// stream_set_blocking を使用してストリームのブロッキングモードを設定します。
56//
57// ブロッキングモードとは:
58//   - true (ブロッキング): stream_get_contents や fread などの読み込み関数が、
59//     データが利用可能になるまで（またはタイムアウトするまで）プログラムの実行を一時停止します。
60//   - false (ノンブロッキング): 読み込み関数は、データがすぐに利用できない場合、
61//     すぐに false を返すか、利用可能なデータのみを読み込み、プログラムの実行を停止しません。
62//
63// この例ではノンブロッキングに設定しますが、データがすぐに書き込まれて読み込まれるため、
64// ここでの直接的な効果は限定的です。通常、ノンブロッキングモードは、
65// ネットワークソケット通信やパイプなどで複数のストリームを同時に扱う非同期処理の際に重要になります。
66stream_set_blocking($stream, false);
67
68// 作成したフィルターをストリームに適用します。
69// STREAM_FILTER_WRITE は、書き込み時にこのフィルターが適用されることを意味します。
70stream_filter_append($stream, 'my_transform_filter', STREAM_FILTER_WRITE);
71
72// ストリームにデータを書き込みます。このデータがフィルターによって加工されます。
73echo "元のデータ: Hello PHP Beginners!\n";
74fwrite($stream, 'Hello PHP Beginners!');
75
76// ストリームポインタを先頭に戻します。これにより、書き込んだデータを最初から読み込めるようになります。
77fseek($stream, 0);
78
79// フィルター処理されたデータをストリームから全て読み込みます。
80$filteredData = stream_get_contents($stream);
81
82// 結果を出力します。
83echo "フィルター処理後のデータ:\n" . $filteredData . "\n";
84
85// ストリームを閉じ、関連するリソースを解放します。
86fclose($stream);
87
88?>

PHPのstream_bucket_new関数は、主にデータの流れを途中で加工する「ストリームフィルター」という仕組みの中で使われる特別な関数です。この関数は、加工済みのデータから新しいデータの塊（バケット）を作り出す役割を担います。

引数としては、第1引数 $stream にそのフィルターが適用されているストリームリソースを、第2引数 $buffer には新しいバケットに含める文字列データを指定します。この関数は、指定されたデータを持つ新しいストリームバケットオブジェクトを戻り値として返します。

サンプルコードでは、ユーザーランドフィルター内で入力データを全て大文字に変換し、特定の文字列を追加して加工しています。そして、この加工済みのデータをstream_bucket_newに渡すことで新しいバケットを生成し、それを次の処理へと送り出しています。

また、stream_set_blocking関数は、ストリームからの読み込み時にデータが利用可能になるまでプログラムの実行を停止するかどうか（ブロッキングモードかノンブロッキングモードか）を設定するもので、特にネットワーク通信などの非同期処理で重要となります。

Copy
1<?php
2
3/**
4 * カスタムストリームフィルターを定義するクラス。
5 * `php_user_filter` を継承し、ストリームのデータを操作します。
6 * このフィルターは、ストリームコンテキストから取得したプレフィックスをデータに追加します。
7 */
8class MyStreamFilter extends php_user_filter
9{
10    /**
11     * フィルター処理を実行するメソッド。
12     * ここで `stream_bucket_new` を使用して新しいストリームバケットを作成し、データを操作します。
13     *
14     * @param resource $in 入力バケットのハンドル
15     * @param resource $out 出力バケットのハンドル
16     * @param int $consumed 処理されたバイト数（参照渡し）
17     * @param bool $closing ストリームが閉じられようとしているかを示すフラグ
18     * @return int フィルター処理の結果ステータス（PSFS_PASS_ON, PSFS_FEED_ME, PSFS_ERR_FATAL）
19     */
20    public function filter($in, $out, &$consumed, bool $closing): int
21    {
22        // 現在のストリームからコンテキストオプションを取得します。
23        // `stream_context_create` で設定されたオプションをここで参照できます。
24        $context_options = stream_context_get_options($this->stream);
25        $prefix = $context_options['my_stream_filter']['prefix'] ?? '';
26
27        while ($bucket = stream_bucket_make_writeable($in)) {
28            // 入力バケットの内容を取得し、修正します。
29            $original_data = $bucket->data;
30            $modified_data = $prefix . $original_data;
31
32            // `stream_bucket_new` を使用して、修正されたデータを含む新しいストリームバケットを作成します。
33            // `$this->stream` は、このフィルターが適用されているストリームリソースです。
34            $new_bucket = stream_bucket_new($this->stream, $modified_data);
35
36            // 作成した新しいバケットを出力ストリームに追加します。
37            stream_bucket_append($out, $new_bucket);
38
39            // 元のデータ量を消費されたバイト数として加算します。
40            $consumed += strlen($original_data);
41        }
42
43        // フィルタリング処理が成功し、データをストリームに渡すことを示します。
44        return PSFS_PASS_ON;
45    }
46}
47
48/**
49 * メイン処理。
50 * カスタムストリームフィルターとストリームコンテキストの使用例を示します。
51 */
52function demonstrateStreamBucketAndContext(): void
53{
54    // 1. カスタムストリームフィルターを登録します。
55    // 'my_filter' という名前で MyStreamFilter クラスがストリームフィルターとして利用可能になります。
56    stream_filter_register('my_filter', MyStreamFilter::class);
57    echo "--- ストリームフィルター 'my_filter' 登録完了 ---\n";
58
59    // 2. ストリームコンテキストを作成します。
60    // このコンテキストには、カスタムフィルターが使用するオプションを含めることができます。
61    // `stream_bucket_new` を使用するフィルターは、このオプションを読み取って挙動を変えます。
62    $context_options = [
63        'my_stream_filter' => [
64            'prefix' => '[CONTEXT_MODIFIED] ', // フィルターがデータに追加するプレフィックス
65        ],
66    ];
67    $context = stream_context_create($context_options);
68    echo "--- ストリームコンテキスト作成完了 ---\n";
69    echo "  設定されたオプション: " . json_encode($context_options['my_stream_filter']) . "\n";
70
71    // 3. 一時的なストリーム（ファイル）を開き、作成したコンテキストを適用します。
72    // 'php://temp' はメモリまたは一時ファイルを使用するストリームで、テストに適しています。
73    $fp = fopen('php://temp', 'r+', false, $context);
74    if (!$fp) {
75        echo "エラー: ストリームを開けませんでした。\n";
76        return;
77    }
78    echo "--- ストリームオープン完了 (php://temp) ---\n";
79
80    // 4. 開いたストリームにカスタムフィルターを追加します。
81    // `STREAM_FILTER_READ` は、このストリームからデータを読み込む際にフィルターが適用されることを意味します。
82    stream_filter_append($fp, 'my_filter', STREAM_FILTER_READ);
83    echo "--- カスタムフィルター 'my_filter' をストリームに追加完了 (読み込み時) ---\n";
84
85    // 5. ストリームに元のデータを書き込みます。
86    $original_data = "Hello, PHP Stream World!";
87    fwrite($fp, $original_data);
88    echo "--- データ書き込み完了: \"{$original_data}\" ---\n";
89
90    // 6. ストリームポインタをデータの先頭に戻します。
91    fseek($fp, 0);
92
93    // 7. ストリームからデータを読み込みます。
94    // この時点で、登録された 'my_filter' が適用され、データがコンテキストに基づいて変更されます。
95    echo "--- ストリームからデータを読み込み中... ---\n";
96    $filtered_data = stream_get_contents($fp);
97
98    // 8. 結果を表示します。
99    echo "--- 読み込み結果 ---\n";
100    echo "元のデータ: \"{$original_data}\"\n";
101    echo "フィルター後のデータ: \"{$filtered_data}\"\n";
102
103    // 9. ストリームを閉じ、リソースを解放します。
104    fclose($fp);
105    echo "--- ストリームクローズ完了 ---\n";
106}
107
108// サンプルコードを実行します。
109demonstrateStreamBucketAndContext();

このPHPのサンプルコードは、stream_bucket_new関数を使用してカスタムストリームフィルターを作成し、ストリームのデータを動的に加工する仕組みを示しています。stream_bucket_newは、指定されたストリームリソース（$stream）に関連付けられた新しいストリームバケットオブジェクトを、渡されたデータ（$buffer）で作成する関数です。この関数が返すストリームバケットオブジェクトは、ストリーム処理の途中でデータを保持し、次のフィルター処理や最終的な出力へと引き渡す役割を担います。

サンプルコードでは、MyStreamFilterというカスタムフィルタークラスが定義されており、その中でstream_bucket_newが使われています。このフィルターは、stream_context_create関数で事前に作成されたストリームコンテキストから「プレフィックス」オプションをstream_context_get_optionsで読み込みます。そして、入力されたストリームデータにそのプレフィックスを付加した新しいデータを作成し、stream_bucket_new($this->stream, $modified_data)によって新しいストリームバケットとして生成しています。ここで$this->streamは、現在フィルターが適用されているストリームそのものを指します。生成された新しいバケットはstream_bucket_appendを通じて出力ストリームへ渡され、最終的にユーザーが読み込むデータが加工されて表示されます。

このように、stream_bucket_newはカスタムフィルター内でストリームデータを加工する際に、加工後のデータを格納するための新しいバケットを生成し、柔軟なデータ操作を可能にする機能です。