【PHP8.x】StreamBucket::dataプロパティの使い方

Copy
1<?php
2
3/**
4 * カスタムストリームフィルターを定義するクラス。
5 * StreamBucket::$data プロパティを利用して、ストリームを流れるデータを加工する方法を示します。
6 * このフィルターは、バケット内のすべてのデータを大文字に変換します。
7 */
8class MyUppercaseFilter extends php_user_filter
9{
10    /**
11     * ストリームフィルターの主要な処理メソッド。
12     * 入力バケットキューからデータを取り出し、加工し、出力バケットキューに配置します。
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(
21        $in,
22        $out,
23        &$consumed,
24        bool $closing
25    ): int {
26        // 入力キューから利用可能なすべてのバケットを処理
27        while ($bucket = stream_bucket_make_writeable($in)) {
28            // StreamBucket::$data プロパティにアクセスし、バケット内の実際のデータ（文字列）を取得します。
29            // これはPHP Data Objects（PDO）が扱うデータとは異なりますが、
30            // 「データ」という共通の概念をキーワードから連想させます。
31            $originalData = $bucket->data;
32
33            // 取得したデータを大文字に変換する例
34            $processedData = strtoupper($originalData);
35
36            // 処理されたデータの元のバイト数をカウント
37            $consumed += strlen($originalData);
38
39            // 加工されたデータを含む新しいバケットを作成し、出力キューに追加します。
40            $newBucket = stream_bucket_new($this->stream, $processedData);
41            stream_bucket_append($out, $newBucket);
42        }
43
44        // 処理を続行可能であることを示します
45        return PSFS_PASS_ON;
46    }
47}
48
49// カスタムストリームフィルターを登録
50// 'my_uppercase_filter' という名前でフィルターをシステムに登録します。
51stream_filter_register('my_uppercase_filter', MyUppercaseFilter::class)
52    or die('Failed to register filter'); // 登録に失敗した場合はスクリプトを終了
53
54// フィルターを適用してファイルにデータを書き込む例
55$filePath = 'filtered_output.txt';
56// ここでは、キーワード「php data objects」を含む文字列を例として使用し、
57// StreamBucket::$data が扱う「データ」としての文脈を示します。
58$originalContent = "Hello from php data objects world! This data will be uppercased.";
59
60echo "元のデータ: " . $originalContent . PHP_EOL;
61
62// 'my_uppercase_filter' を適用してファイルに書き込みます。
63// file_put_contents のパスに 'php://filter/write=my_uppercase_filter/resource=' を使用することで、
64// データをファイルに書き込む前にフィルターが適用されます。
65$filterPath = 'php://filter/write=my_uppercase_filter/resource=' . $filePath;
66file_put_contents($filterPath, $originalContent);
67
68echo "フィルター適用後、ファイルに書き込まれました: " . $filePath . PHP_EOL;
69
70// フィルターを通して書き込まれたファイルの内容を読み込み、表示します。
71$filteredContent = file_get_contents($filePath);
72echo "ファイル '" . $filePath . "' の内容: " . $filteredContent . PHP_EOL;
73
74// 後処理として作成したファイルを削除します
75if (file_exists($filePath)) {
76    unlink($filePath);
77    echo "一時ファイル '" . $filePath . "' を削除しました。" . PHP_EOL;
78}
79
80?>

PHP 8のStreamBucket::$dataプロパティは、ストリームフィルター処理において、データの具体的な内容にアクセスするために使用されます。ストリームフィルターとは、ファイルへの書き込みや読み込みの際に、その途中でデータを加工したり変換したりする仕組みのことです。

このdataプロパティは、StreamBucketというクラスに属しており、フィルター処理の際にデータのかたまり（バケット）から、実際に加工したい「データ本体」を文字列として取得します。引数を取ることはなく、常にバケットが保持するデータを文字列型で返します。

サンプルコードでは、MyUppercaseFilterというカスタムフィルターが定義されており、このフィルターの中で$bucket->dataとしてプロパティにアクセスし、バケット内の元のデータを取得しています。そして、取得したデータをstrtoupper関数を使ってすべて大文字に変換し、新しいバケットとして出力する処理が示されています。

キーワードの「php data objects」は、StreamBucket::$dataが扱う「データ」が具体的にどのような情報を含み得るかを示す一例として使用されています。このように、dataプロパティはストリームを流れる様々な種類の情報を操作するための中心的な役割を担っています。

Copy
1<?php
2
3/**
4 * このサンプルコードは、PHPのストリームフィルター内で
5 * StreamBucket::data プロパティを利用し、その内容が日付文字列であると仮定して
6 * フォーマットを変換する例を示します。
7 * StreamBucket は直接インスタンス化するものではなく、ストリームフィルター処理中に
8 * PHPによって提供されるオブジェクトです。
9 */
10
11/**
12 * DateFormatFilter クラス
13 * ストリームから受け取った日付文字列のフォーマットを変換するカスタムフィルター。
14 */
15class DateFormatFilter extends php_user_filter
16{
17    /**
18     * フィルター処理を実行します。
19     * このメソッドは、ストリームにデータが書き込まれるか、読み込まれるときにPHPによって呼び出されます。
20     *
21     * @param resource $in 入力バケットリスト (通常は stream_bucket_make_writeable で処理)
22     * @param resource $out 出力バケットリスト
23     * @param int      &$consumed 消費されたバイト数
24     * @param bool     $closing ストリームが閉じられようとしているかを示すフラグ
25     * @return int フィルターの動作を示す定数 (例: PSFS_PASS_ON, PSFS_FEED_ME, PSFS_ERR_FATAL)
26     */
27    public function filter($in, $out, &$consumed, $closing)
28    {
29        // 入力バケットリストから書き込み可能なバケットを一つずつ取得し処理します
30        while ($bucket = stream_bucket_make_writeable($in)) {
31            // StreamBucket::data プロパティにアクセスし、バケットに含まれる生のデータを文字列として取得します。
32            $originalData = $bucket->data;
33
34            // キーワード「php date」に関連付け:
35            // 受け取ったデータ（$originalData）が日付文字列であると仮定し、DateTimeクラスで解析を試みます。
36            // ここでは 'YYYY-MM-DD HH:MM:SS' 形式を想定しています。
37            $dateTime = DateTime::createFromFormat('Y-m-d H:i:s', trim($originalData));
38
39            if ($dateTime) {
40                // 日付として正常に解析できた場合、新しいフォーマットに変換します。
41                $processedData = $dateTime->format('l, F j, Y, H:i:s');
42            } else {
43                // 日付として解析できなかった場合は、元のデータをそのまま使用します。
44                $processedData = $originalData;
45            }
46
47            // 処理したデータを StreamBucket::data プロパティに設定し直します。
48            // これにより、バケットのコンテンツが更新されます。
49            $bucket->data = $processedData;
50            // データ長も更新する必要があります。
51            $bucket->datalen = strlen($processedData);
52
53            // 消費されたバイト数を更新します (変更後のデータ長で)。
54            $consumed += $bucket->datalen;
55            // 処理済みのバケットを出力バケットリストに追加します。
56            stream_bucket_append($out, $bucket);
57        }
58
59        // フィルター処理が成功し、ストリームの処理を続行することを示します。
60        return PSFS_PASS_ON;
61    }
62}
63
64// フィルター名を登録します。
65// これにより、このフィルターを stream_filter_append() などで利用できるようになります。
66if (!stream_filter_register("date_format_filter", DateFormatFilter::class)) {
67    die("エラー: フィルター 'date_format_filter' の登録に失敗しました。\n");
68}
69
70echo "--- ストリームフィルターのデモンストレーション ---\n\n";
71
72// テスト用のメモリストリームを作成します。
73// php://memory は、ファイルシステムではなくメモリ内で動作する一時的なストリームです。
74$fp = fopen("php://memory", "r+");
75if (!$fp) {
76    die("エラー: メモリストリームのオープンに失敗しました。\n");
77}
78
79// 作成したメモリストリームに、登録したフィルターを適用します。
80// STREAM_FILTER_WRITE は、ストリームへの書き込み時にフィルターが適用されることを意味します。
81if (!stream_filter_append($fp, "date_format_filter", STREAM_FILTER_WRITE)) {
82    fclose($fp);
83    die("エラー: フィルター 'date_format_filter' の適用に失敗しました。\n");
84}
85
86echo "元のデータをストリームに書き込み中...\n";
87
88// テストデータをストリームに書き込みます。
89// このデータが DateFormatFilter によって処理されます。
90fwrite($fp, "2023-10-27 10:30:00\n");
91fwrite($fp, "2024-01-15 08:00:00\n");
92fwrite($fp, "これは日付ではありません。\n"); // 日付ではない文字列もテスト
93
94// ストリームポインタを先頭に戻し、フィルターによって変換されたデータを読み出せるようにします。
95fseek($fp, 0);
96
97echo "\n--- フィルター適用後の出力 ---\n";
98// ストリームからデータを読み出し、結果を表示します。
99while (!feof($fp)) {
100    echo fgets($fp);
101}
102
103// ストリームを閉じ、リソースを解放します。
104fclose($fp);
105
106echo "\n--- デモンストレーション完了 ---\n";
107
108?>

PHP 8のStreamBucket::dataプロパティは、カスタムストリームフィルター内で、ストリームを流れるデータの各「バケット」（断片）が保持する実際のデータにアクセスするために利用されます。このプロパティには引数がなく、常にバケットに含まれるデータの内容をstring型で返します。また、このプロパティに新しい文字列を代入することで、バケットのデータを変更することも可能です。

サンプルコードでは、DateFormatFilterというカスタムストリームフィルターを定義し、そのfilterメソッド内でStreamBucket::dataを使用しています。stream_bucket_make_writeable関数で取得したStreamBucketオブジェクトから$bucket->dataを利用し、元のデータ文字列を取得しています。キーワードである「php date」に関連して、取得したデータが日付文字列であると仮定し、DateTime::createFromFormatを使って日付として解析を試みています。日付として正常に解析できた場合は、新しいフォーマットの日付文字列に変換し、それを再び$bucket->dataプロパティに設定してバケットの内容を更新しています。日付として解析できなかった場合は元のデータをそのまま利用し、同様に$bucket->dataと$bucket->datalenを更新します。このようにStreamBucket::dataを用いることで、ストリームフィルターは通過するデータの内容を読み取り、必要に応じて加工して出力できるのです。