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

Copy
1<?php
2
3/**
4 * MyPrependFilter クラスは php_user_filter を継承し、カスタムストリームフィルタを定義します。
5 * このフィルタは、ストリームから読み込まれる各バケットの前に特定のコンテンツを先頭に追加します。
6 */
7class MyPrependFilter extends php_user_filter
8{
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, PSFS_FEED_ME, PSFS_ERR_FATAL)
18     */
19    public function filter($in, $out, &$consumed, bool $closing): int
20    {
21        // ストリームの各バケットの前に挿入したいコンテンツを定義します。
22        $prependContent = "--- [PREPENDED BY FILTER] ---\n";
23
24        // stream_bucket_new() を使用して、挿入したいコンテンツを含む新しいデータバケットを作成します。
25        // $this->stream は、フィルタがアタッチされている元のストリームです。
26        $newBucket = stream_bucket_new($this->stream, $prependContent);
27
28        // stream_bucket_prepend() を使用して、作成した新しいバケットを出力ブリゲードの先頭に追加します。
29        // これにより、このバケットの内容がストリームの元のデータより前に出力されます。
30        // $out: データを追加するバケットブリゲード。
31        // $newBucket: 追加するバケットオブジェクト。
32        stream_bucket_prepend($out, $newBucket);
33
34        // 入力ブリゲード ($in) から利用可能なすべてのデータバケットを処理します。
35        while ($bucket = stream_bucket_make_writeable($in)) {
36            // $bucket->data には、入力ストリームから読み込まれた元のデータが含まれます。
37            // 必要に応じて、ここで $bucket->data を変更することで、元のデータを加工できます。
38            // この例では、元のデータはそのまま出力します。
39
40            // 処理されたバイト数を更新します。
41            $consumed += $bucket->datalen;
42
43            // 処理済みの（または加工された）バケットを出力ブリゲード ($out) に追加します。
44            stream_bucket_append($out, $bucket);
45        }
46
47        // フィルタリング処理を続行し、データを次のフィルタまたは最終出力に渡すことを示します。
48        return PSFS_PASS_ON;
49    }
50}
51
52// カスタムフィルタをシステムに登録します。
53// これにより、"my_prepend_filter" という名前で MyPrependFilter クラスを使用できるようになります。
54if (!stream_filter_register("my_prepend_filter", "MyPrependFilter")) {
55    die("エラー: フィルタ 'my_prepend_filter' の登録に失敗しました。\n");
56}
57
58// テスト用の一時ファイルを作成し、サンプルデータを書き込みます。
59$tempFile = tempnam(sys_get_temp_dir(), 'php_filter_example_');
60if ($tempFile === false) {
61    die("エラー: 一時ファイルの作成に失敗しました。\n");
62}
63$originalContent = "これは元のファイルコンテンツの1行目です。\nこれは元のファイルコンテンツの2行目です。\n";
64file_put_contents($tempFile, $originalContent);
65
66echo "--- 元のファイルコンテンツ ---\n";
67echo file_get_contents($tempFile);
68echo "------------------------------\n\n";
69
70// ファイルを読み込みモードで開きます。
71$handle = fopen($tempFile, 'r');
72if (!$handle) {
73    die("エラー: ファイル '{$tempFile}' のオープンに失敗しました。\n");
74}
75
76// ストリームにカスタムフィルタを先頭に追加します。
77// `stream_filter_prepend` は、ストリームにフィルタを適用する際に、既存のフィルタよりも先に処理されるようにします。
78// これにより、`MyPrependFilter` の `filter` メソッドが読み込み処理の最初に適用されます。
79if (!stream_filter_prepend($handle, "my_prepend_filter")) {
80    die("エラー: ストリームへのフィルタ 'my_prepend_filter' の追加に失敗しました。\n");
81}
82
83echo "--- フィルタ適用後のコンテンツ ---\n";
84// フィルタが適用されたストリームからデータを読み込み、出力します。
85// 各行の読み込み（実際には各バケットの処理）の前に、
86// stream_bucket_prepend() で追加された「--- [PREPENDED BY FILTER] ---」が表示されます。
87while (!feof($handle)) {
88    echo fgets($handle);
89}
90echo "------------------------------\n";
91
92// ストリームを閉じます。
93fclose($handle);
94
95// テスト用の一時ファイルを削除します。
96unlink($tempFile);
97
98?>

PHP 8のstream_bucket_prepend関数は、ストリームフィルタ内で、データバケットの集合である「ブリゲード」の先頭に新しいバケットを追加します。カスタムストリームフィルタ内で、元のデータ処理の前に情報を挿入する際に特に活用されます。

引数 $brigade には、バケットを追加したい出力ブリゲードリソースを指定します。 引数 $bucket には、stream_bucket_new関数などで作成された、追加するデータを含むバケットオブジェクトを指定します。 戻り値は bool で、処理の成功時には true、失敗時には false を返します。

サンプルコードでは、MyPrependFilterカスタムフィルタのfilterメソッド内で、特定の文字列「--- [PREPENDED BY FILTER] ---」を含むバケットを作成し、stream_bucket_prependを用いて出力ブリゲードの先頭に挿入しています。これにより、ストリームからデータが読み込まれるたびに、元のコンテンツの前にこの文字列が自動的に付加される動作が実現されます。

Copy
1<?php
2
3/**
4 * MyPrependFilter クラスは php_user_filter を継承し、カスタムストリームフィルタを実装します。
5 * このフィルタは、入力された各データブロックの先頭に特定の文字列を追加し、
6 * その後で元のデータブロックも出力します。
7 */
8class MyPrependFilter extends php_user_filter
9{
10    /**
11     * ストリームフィルタリングのロジックを実装します。
12     * 入力バケットを処理し、出力バケットをbrigadeに追加します。
13     *
14     * @param resource $in 入力バケットのbrigade (stream_bucket_object のリスト)
15     * @param resource $out 出力バケットのbrigade (stream_bucket_object のリスト)
16     * @param int $consumed 処理されたバイト数 (参照渡し)
17     * @param bool $closing ストリームが閉じられようとしているかを示すフラグ
18     * @return int 成功時は PSFS_PASS_ON (または PSFS_FEED_ME, PSFS_ERR), 失敗時は PSFS_ERR
19     */
20    public function filter($in, $out, &$consumed, $closing): int
21    {
22        // 入力brigadeから利用可能なバケットがある限り処理を続けます
23        while ($bucket = stream_bucket_make_writable($in)) {
24            // 入力バケットのデータを取得します
25            $data = $bucket->data;
26
27            // 新しいデータを作成します (例: プレフィックスを追加)
28            $prependedData = "PREPENDED_CONTENT: " . $data;
29
30            // stream_bucket_new を使用して、加工済みデータを持つ新しいバケットを作成します
31            $newBucket = stream_bucket_new($this->stream, $prependedData);
32
33            // stream_bucket_prepend を使用して、この新しいバケットを$out brigadeの先頭に追加します。
34            // これにより、オリジナルのデータよりも先に加工されたデータが出力されます。
35            stream_bucket_prepend($out, $newBucket);
36
37            // オリジナルの入力データも出力したい場合は、
38            // 元のバケットをそのまま出力brigadeに追加します。
39            stream_bucket_append($out, $bucket);
40
41            // 処理したバイト数を更新します
42            $consumed += strlen($data);
43        }
44
45        // フィルタリング処理が成功し、出力brigadeにデータが渡されたことをPHPに伝えます
46        return PSFS_PASS_ON;
47    }
48}
49
50// カスタムフィルタをPHPのストリームフィルタシステムに登録します
51stream_filter_register('my_prepend_filter', MyPrependFilter::class);
52
53// 一時的なメモリ上のストリームを開きます。これはファイルのように読み書きできる仮想的なストリームです。
54$stream = fopen('php://memory', 'r+');
55
56// 作成したカスタムフィルタをストリームに適用します。
57// 'STREAM_FILTER_WRITE' は、書き込み操作時にこのフィルタが適用されることを意味します。
58stream_filter_append($stream, 'my_prepend_filter', STREAM_FILTER_WRITE);
59
60// キーワード `stream_set_write_buffer` を考慮し、ストリームの書き込みバッファリングを設定します。
61// ここではバッファサイズを0に設定してバッファリングを無効にします。
62// これにより、`fwrite()`が呼び出されるたびに、すぐにフィルタにデータが渡されるようになります。
63// (通常、stream_set_write_bufferはパフォーマンス向上のために使われますが、
64// ここではフィルタの動作との関連を示すために明示的に設定しています。)
65if (stream_set_write_buffer($stream, 0) === 0) {
66    echo "--- 書き込みバッファリングを無効に設定しました ---\n";
67} else {
68    echo "--- 書き込みバッファリングの設定に失敗しました ---\n";
69}
70
71// ストリームにデータを書き込みます。
72// この書き込み操作中に、`my_prepend_filter`が適用されます。
73echo "--- ストリームにデータを書き込み中 ---\n";
74fwrite($stream, "Hello world.\n");
75fwrite($stream, "PHP streams are powerful.\n");
76echo "-------------------------------------\n";
77
78// ストリームポインタを先頭に戻します。これにより、最初からデータを読み出すことができます。
79fseek($stream, 0);
80
81// フィルタによって処理されたデータをストリームから読み込み、出力します。
82echo "--- フィルタリングされた出力 ---\n";
83while (!feof($stream)) {
84    echo fgets($stream);
85}
86echo "-----------------------------\n";
87
88// ストリームを閉じ、リソースを解放します。
89fclose($stream);
90
91?>

このサンプルコードは、PHPでカスタムストリームフィルタを実装し、その中でstream_bucket_prepend関数を使用する方法を示しています。MyPrependFilterクラスは、ストリームに入力されたデータブロックの先頭に特定の文字列を追加する独自のフィルタとして機能します。

フィルタリングの核心となるstream_bucket_prepend関数は、出力用のバケットリスト（$brigade）の先頭に、新しく作成または加工されたバケット（$bucket）を追加する役割を持ちます。これにより、元のデータよりも前に、加工済みのデータをストリームに送り出すことが可能になります。引数$brigadeにはデータを追加するバケットリストを、$bucketにはリストの先頭に追加したいバケットオブジェクトを指定します。この関数は処理が成功するとtrueを、失敗するとfalseを返します。

さらに、stream_set_write_buffer関数を用いてストリームの書き込みバッファリングを無効に設定し、fwriteが呼び出されるたびにカスタムフィルタが即座に適用される動作を確認しています。最終的に、メモリ上のストリームに書き込まれたデータは、このカスタムフィルタによって加工された状態で読み出されます。