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

Copy
1<?php
2
3/**
4 * カスタムストリームフィルターを定義するクラス。
5 * php_user_filterを継承し、ストリームを通じて渡される全てのデータを大文字に変換するフィルターを作成します。
6 */
7class SimpleUpperCaseFilter extends php_user_filter
8{
9    /**
10     * フィルター処理を実行するメソッド。
11     * このメソッドは、ストリームにデータが書き込まれるか読み込まれるたびに呼び出されます。
12     *
13     * @param resource $in 読み込み元のバケットリスト (brigade)。ここから元のデータを取り出します。
14     * @param resource $out 書き込み先のバケットリスト (brigade)。ここに処理後のデータを追加します。
15     * @param int      &$consumed 消費されたデータのバイト数を累積します。
16     * @param bool     $closing ストリームが閉じられている最中であるかどうかのフラグ。
17     * @return int フィルター処理の結果を表す定数 (PSFS_PASS_ON, PSFS_FEED_MEなど)。
18     */
19    public function filter($in, $out, &$consumed, $closing)
20    {
21        // 読み込み元のブリゲード ($in) からバケットを一つずつ取り出し、処理します。
22        // stream_bucket_make_writeable($in) は以下の処理を行います。
23        // 1. $in ブリゲードから次のバケットを取り出します。
24        // 2. そのバケットのデータを基に、新しい「書き込み可能な」StreamBucketオブジェクトを生成して返します。
25        //    これにより、取り出したバケットの内容を安全に変更できるようになります。
26        //    元のバケットは $in ブリゲードから消費されます。
27        while ($bucket = stream_bucket_make_writeable($in)) {
28            // 取り出したバケットのデータを大文字に変換します。
29            // $bucket->data は、このバケットが保持する文字列データです。
30            $bucket->data = strtoupper($bucket->data);
31
32            // このバケットで処理したデータのバイト数を、全体の消費バイト数に加算します。
33            $consumed += $bucket->datalen;
34
35            // 処理済みのバケットを書き込み先のブリゲード ($out) に追加します。
36            // これにより、変更されたデータがストリームの次の段階（または最終的な出力）に渡されます。
37            stream_bucket_append($out, $bucket);
38        }
39
40        // フィルター処理が成功し、データが次のフィルターまたはストリームに渡されることを示します。
41        return PSFS_PASS_ON;
42    }
43}
44
45// カスタムフィルターを "uppercase_filter" という名前でPHPのストリームフィルターシステムに登録します。
46// これにより、この名前を使ってフィルターをストリームに適用できるようになります。
47stream_filter_register("uppercase_filter", "SimpleUpperCaseFilter");
48
49// 一時的なメモリ上のストリームを作成します。
50// "r+" は読み書きモードを意味し、ファイルのように扱うことができますが、実際にはメモリ上で動作します。
51$stream = fopen("php://temp", "r+");
52
53// 作成したストリームに、先ほど登録した "uppercase_filter" を追加します。
54// このフィルターは、ストリームへの「書き込み時」に適用されます（デフォルトの動作）。
55stream_filter_append($stream, "uppercase_filter");
56
57// ストリームにいくつかの文字列を書き込みます。
58// これらのデータは "uppercase_filter" によって自動的に大文字に変換されてメモリに保存されます。
59echo "元の文字列をストリームに書き込み中...\n";
60fwrite($stream, "hello, php streams!\n");
61fwrite($stream, "this is a test line.");
62
63// ストリームポインタをファイルの先頭（書き込み開始位置）に戻します。
64// これにより、書き込まれたデータを最初から読み出す準備ができます。
65rewind($stream);
66
67// フィルターが適用されたストリームから全てのコンテンツを読み込みます。
68// 読み出されるコンテンツは、フィルターによって大文字に変換された後のものです。
69$filteredContent = stream_get_contents($stream);
70
71echo "\nフィルター後のストリーム内容:\n";
72// フィルタリングされた内容を出力します。
73echo $filteredContent;
74
75// ストリームを閉じ、使用していたシステムリソースを解放します。
76fclose($stream);
77
78?>

このPHPのサンプルコードは、stream_bucket_make_writeable関数を活用し、カスタムストリームフィルターを通じてデータを処理する方法を示しています。stream_bucket_make_writeable関数は、ストリームフィルターのfilterメソッド内で使用されることが多く、引数として渡された「バケットリスト（brigade）」から次のデータバケットを取り出します。この関数は、取り出したバケットのデータを基に、内容を安全に書き換え可能なStreamBucketオブジェクトを戻り値として返します。これにより、フィルターはストリームを流れる個々のデータチャンクを検査し、必要に応じて変更することが可能になります。

サンプルコードでは、SimpleUpperCaseFilterというカスタムフィルターを定義しています。このフィルターは、filterメソッド内でstream_bucket_make_writeable($in)を繰り返し呼び出すことで、読み込み元のバケットリスト$inからデータバケットを順次取得しています。取得したStreamBucketオブジェクトのdataプロパティにアクセスし、strtoupper関数で文字列を大文字に変換しています。データ変換後、stream_bucket_append関数を用いて、変更されたバケットを書き込み先のバケットリスト$outに追加し、ストリームの次の段階へデータを渡しています。

最終的に、このカスタムフィルターをphp://tempストリームに適用し、書き込まれた文字列がフィルターによって自動的に大文字に変換されて読み出される様子を確認しています。stream_bucket_make_writeableは、ストリームデータをきめ細かく制御し、独自の処理ロジックを適用する上で中心的な役割を果たす関数です。

Copy
1<?php
2
3/**
4 * カスタムストリームフィルターの例: 入力データを逆順にします。
5 * stream_bucket_make_writeable 関数を使って、ストリームバケットの内容を操作します。
6 * これは、システムエンジニアを目指す初心者の方が、PHPのストリームフィルターが
7 * どのようにデータの流れを操作するかを理解するための一例です。
8 */
9class ReverseStreamFilter extends php_user_filter
10{
11    /**
12     * ストリームフィルターの主要なロジックを実装します。
13     * このメソッドは、ストリームを通過するデータが利用可能になったときに呼び出されます。
14     *
15     * @param resource $in 入力ブリゲード (StreamBucket オブジェクトのキュー)
16     * @param resource $out 出力ブリゲード (処理済みの StreamBucket オブジェクトを追加する場所)
17     * @param int $consumed 処理されたバイト数のカウンタ (参照渡し)
18     * @param bool $closing ストリームが閉じられようとしているか
19     * @return int フィルターの次の動作 (PSFS_PASS_ON, PSFS_FEED_ME, PSFS_ERR など)
20     */
21    public function filter($in, $out, &$consumed, $closing): int
22    {
23        // 入力ブリゲードから利用可能なすべてのバケットを処理します。
24        while ($bucket = stream_bucket_make_writeable($in)) {
25            // stream_bucket_make_writeable は入力ブリゲードから次のバケットを取り出し、
26            // その内容を直接変更できる StreamBucket オブジェクトとして返します。
27            // $bucket->data プロパティを読み書きしてデータを操作できます。
28            
29            // バケットのデータ（文字列）を逆順に変換します。
30            $bucket->data = strrev($bucket->data);
31            
32            // 処理したバイト数を合計に追加します。
33            $consumed += $bucket->datalen;
34
35            // 処理が完了したバケットを出力ブリゲードに追加します。
36            // このバケットは次のフィルターや最終的な宛先に渡されます。
37            stream_bucket_append($out, $bucket);
38        }
39
40        // フィルタリング処理を継続することを示します。
41        // すべての入力バケットが処理された後でも、さらにデータが来る可能性があります。
42        return PSFS_PASS_ON;
43    }
44}
45
46// カスタムフィルターを "reverse_filter" という名前でPHPに登録します。
47// これにより、stream_filter_append() などの関数でこのフィルターを利用できるようになります。
48stream_filter_register("reverse_filter", ReverseStreamFilter::class);
49
50// メモリ上に一時的なファイルを作成し、読み書き可能モードで開きます。
51$fp = fopen("php://memory", "r+");
52
53// 書き込み操作時に "reverse_filter" を適用するように設定します。
54// STREAM_FILTER_WRITE は、ストリームへの書き込み時にフィルターが適用されることを指定します。
55stream_filter_append($fp, "reverse_filter", STREAM_FILTER_WRITE);
56
57// データを書き込みます。この際、フィルターによってデータが逆順に変換されます。
58fwrite($fp, "Hello, PHP!");
59fwrite($fp, " Stream Filter!");
60
61// ファイルポインタを先頭に戻し、書き込んだ内容を最初から読み込めるようにします。
62fseek($fp, 0);
63
64// フィルタリングされた結果をすべて読み込み、出力します。
65echo "元の文字列を逆順にした結果:\n";
66echo stream_get_contents($fp);
67
68// ファイルリソースを閉じ、関連するリソースを解放します。
69fclose($fp);

PHPのstream_bucket_make_writeable関数は、ストリームフィルター内でデータの塊である「バケット」を直接操作可能にするための機能です。この関数は、引数として渡された入力ブリゲード（ストリームバケットのキュー）から、次に処理すべきバケットを取り出し、その内容を変更できるStreamBucketオブジェクトとして返します。バケットがもうない場合はnullを返します。

サンプルコードでは、入力データを逆順にするカスタムストリームフィルターReverseStreamFilterが実装されています。フィルターの主要なロジックを担うfilterメソッド内で、while ($bucket = stream_bucket_make_writeable($in))と記述し、入力ブリゲード$inから順にデータバケットを取得しています。取得した$bucketオブジェクトのdataプロパティには、ストリームを流れてきた生データが文字列として格納されており、これをstrrev()関数で逆順に変換しています。データの変更が完了したら、stream_bucket_append()関数を使って、変更済みのバケットを出力ブリゲード$outに追加し、次の処理へ渡します。

このコードは、php://memoryストリームにカスタムフィルターを適用し、"Hello, PHP! Stream Filter!"という文字列を書き込んだ際に、フィルターがどのようにデータを逆順に加工し、最終的に"!!retliF maertS !PHP ,olleH"のような結果が得られるかを示しています。stream_bucket_make_writeable関数は、PHPのストリームフィルター機能において、データを柔軟に加工する上で非常に重要な役割を果たすことを理解できます。