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

Copy
1<?php
2
3/**
4 * ストリームバケット内のデータ長 (datalen) を表示するカスタムフィルター。
5 * StreamBucket::datalen プロパティが整数のデータ型 (int) であることを示します。
6 */
7class MyStreamBucketInfoFilter extends php_user_filter
8{
9    /**
10     * フィルター処理を実行します。
11     * 各ストリームバケットから datalen プロパティにアクセスし、その値とデータ型を表示します。
12     *
13     * @param resource $in 入力バケットバンドル (stream_bucket_bundle)
14     * @param resource $out 出力バケットバンドル (stream_bucket_bundle)
15     * @param int      &$consumed これまでに処理されたバイト数
16     * @param bool     $closing ストリームが閉じられようとしているか
17     * @return int フィルター処理の結果ステータス
18     */
19    public function filter(
20        $in,
21        $out,
22        &$consumed,
23        bool $closing
24    ): int {
25        while ($bucket = stream_bucket_make_writeable($in)) {
26            // StreamBucket::datalen プロパティにアクセスし、データのバイト長を取得
27            // このプロパティは PHP の整数型 (int) です。
28            echo "--- StreamBucket 情報 ---\n";
29            echo "データ長 (datalen): " . $bucket->datalen . " バイト\n";
30            echo "datalen の PHP データ型: " . gettype($bucket->datalen) . "\n";
31            echo "datalen は整数型 (int) ですか？: " . (is_int($bucket->datalen) ? 'はい' : 'いいえ') . "\n";
32            echo "-------------------------\n\n";
33
34            // 処理されたバイト数を更新
35            $consumed += $bucket->datalen;
36
37            // 処理したバケットを出力バンドルに追加 (この例ではデータを変更しません)
38            stream_bucket_append($out, $bucket);
39        }
40
41        // 処理を続行し、データを変更しないことを示す
42        return PSFS_PASS_ON;
43    }
44}
45
46// フィルターをPHPに登録します。
47// 'my_stream_bucket_info_filter' という名前で MyStreamBucketInfoFilter クラスを登録。
48stream_filter_register('my_stream_bucket_info_filter', MyStreamBucketInfoFilter::class)
49    or die("フィルターの登録に失敗しました。");
50
51// 一時メモリファイルを作成し、読み書きモードで開きます。
52$filename = 'php://temp';
53$handle = fopen($filename, 'r+');
54
55if ($handle === false) {
56    die("ファイルを開けませんでした。");
57}
58
59echo "ファイルをオープンしました。\n\n";
60
61// ストリームにカスタムフィルターを適用します。
62// 書き込み時にフィルターが動作するように設定 (STREAM_FILTER_WRITE)。
63stream_filter_append($handle, 'my_stream_bucket_info_filter', STREAM_FILTER_WRITE);
64
65echo "--- データを書き込み中 ---\n";
66
67// ストリームにデータを書き込みます。
68// 各 fwrite() が呼び出されると、データはバケットにまとめられ、フィルターを通過する可能性があります。
69$data1 = "Hello, StreamBucket example for beginners!";
70echo "書き込みデータ1: '" . $data1 . "'\n";
71fwrite($handle, $data1);
72
73$data2 = "PHP datatypes are important.";
74echo "書き込みデータ2: '" . $data2 . "'\n";
75fwrite($handle, $data2);
76
77$data3 = "Short data.";
78echo "書き込みデータ3: '" . $data3 . "'\n";
79fwrite($handle, $data3);
80
81echo "--- 書き込み完了 ---\n\n";
82
83// ストリームを閉じます。
84// このとき、バッファに残っているデータが最終的にフィルターを通過します。
85fclose($handle);
86
87echo "ファイルをクローズしました。\n";
88
89?>

このPHPコードは、ストリーム処理におけるStreamBucket::datalenプロパティの挙動を、システムエンジニアを目指す初心者にも分かりやすく説明します。StreamBucketは、ファイルやネットワークなどのストリームデータを扱う際に、データを一時的に保持する「バケット」と呼ばれる単位です。datalenプロパティは、このStreamBucketが現在持っているデータのバイト長を示し、その値はPHPの**整数型（int）**であることが特徴です。引数はなく、常に整数を返します。

サンプルコードでは、MyStreamBucketInfoFilterという独自のストリームフィルターを作成しています。このフィルターは、データがストリームに書き込まれる途中で、そのデータを格納するバケットからdatalenプロパティの値を取得し、そのバイト数とデータ型（int）を画面に表示します。これにより、データがどのようにバケットに分割され、各バケットのデータ長がdatalenプロパティとして整数で提供されるかを視覚的に確認できます。ストリームフィルターの登録と適用後、複数のデータを書き込むことで、各書き込み操作でフィルターがどのように動作し、datalenの情報を表示するかが示されます。この例は、ストリームデータ処理におけるdatalenプロパティの基本的な役割とデータ型を理解するのに役立ちます。

Copy
1<?php
2
3// StreamBucket::datalen プロパティは、ストリームフィルター処理中に
4// バケット内のデータの長さをバイト単位で取得するために使用されます。
5// StreamBucketオブジェクトはPHP内部で生成されるため、直接インスタンス化できません。
6// このサンプルは、ストリームフィルターを通じてdatalenプロパティへのアクセスを示します。
7
8/**
9 * カスタムストリームフィルターのクラス定義。
10 * php_user_filterを継承することで、ストリームフィルターとして機能します。
11 * このフィルターは、入力された各バケットのデータ長と内容を表示し、変更せずにそのまま出力します。
12 */
13class MyDatalenFilter extends php_user_filter
14{
15    /**
16     * ストリームフィルターの主要な処理ロジックを実装するメソッドです。
17     * ストリームにデータが書き込まれると、このメソッドが呼び出されます。
18     *
19     * @param resource $in 入力バケットリスト (StreamBucketオブジェクトのリスト)
20     * @param resource $out 出力バケットリスト (StreamBucketオブジェクトを追加する場所)
21     * @param int $consumed これまでにフィルターによって処理されたバイト数の合計
22     * @param bool $closing ストリームが閉じられようとしているかを示すフラグ
23     * @return int フィルターのステータス (PSFS_PASS_ON, PSFS_FEED_ME, PSFS_ERR)
24     */
25    public function filter($in, $out, &$consumed, bool $closing): int
26    {
27        // 入力バケットリストから利用可能な各バケットを順に処理します
28        while ($bucket = stream_bucket_make_writeable($in)) {
29            // StreamBucketオブジェクトのdatalenプロパティにアクセスし、
30            // バケット内のデータの長さをバイト単位で取得します。
31            $length = $bucket->datalen;
32            echo "取得したデータ長: {$length}バイト\n";
33
34            // バケット内のデータ内容を表示します (改行文字は除去して見やすくしています)
35            echo "バケットの内容: " . rtrim($bucket->data) . "\n";
36
37            // このバケットで処理されたバイト数を合計バイト数に加算します
38            $consumed += $length;
39
40            // 処理したバケットを出力バケットリストに追加します。
41            // この例ではデータ内容を変更していないため、そのまま次の段階へ渡します。
42            stream_bucket_append($out, $bucket);
43        }
44
45        // フィルターが全ての入力バケットを正常に処理し、出力を生成したことを示します
46        return PSFS_PASS_ON;
47    }
48}
49
50// カスタムフィルターをPHPに登録します。
51// これにより、文字列 "my_datalen_filter" でこのフィルターを参照できるようになります。
52stream_filter_register("my_datalen_filter", "MyDatalenFilter")
53    or die("フィルターの登録に失敗しました。");
54
55echo "--- StreamBucket::datalen プロパティの使用例 --- \n\n";
56
57// メモリ上のストリームを開きます。
58// 'w+' モードは、読み書き可能でファイルポインタを先頭に設定します。
59$fp = fopen("php://memory", "w+");
60
61if ($fp === false) {
62    die("ストリームのオープンに失敗しました。");
63}
64
65// 開いたストリームに、作成したカスタムフィルターを適用します。
66// STREAM_FILTER_WRITE は、ストリームへの書き込み操作時にフィルターを適用することを意味します。
67stream_filter_append($fp, "my_datalen_filter", STREAM_FILTER_WRITE);
68
69echo "ストリームにデータを書き込み中...\n";
70// 以下の各fwrite呼び出しによって、データがストリームバッファに書き込まれ、
71// その後フィルターを通過する際に、MyDatalenFilter::filter() メソッドが呼び出されます。
72fwrite($fp, "Hello, PHP Stream!\n");      // 19バイト (改行含む)
73fwrite($fp, "This is a test data.\n");    // 21バイト (改行含む)
74fwrite($fp, "Another line for example.\n");// 26バイト (改行含む)
75
76// ストリームを閉じます。
77// この操作により、ストリームバッファに残っている全てのデータがフラッシュされ、
78// 適用されているフィルターを最終的に通過します。
79fclose($fp);
80
81echo "\nストリーム処理完了。\n";
82
83?>

PHP 8におけるStreamBucket::datalenプロパティは、ストリームフィルター処理中に利用される特殊なプロパティです。これは、ストリームを流れるデータの一時的な塊である「バケット」が持つデータの長さを、バイト単位の整数値（int）として取得するために使用されます。このプロパティは引数を必要としません。

StreamBucketオブジェクトはPHPの内部で自動的に生成されるため、プログラマーが直接インスタンス化することはありません。通常、php_user_filterを継承したカスタムストリームフィルターのfilterメソッド内で、stream_bucket_make_writeable関数で取得したStreamBucketオブジェクトから$bucket->datalenのようにアクセスします。

サンプルコードでは、MyDatalenFilterというカスタムフィルターを定義し、そのfilterメソッド内で$bucket->datalenプロパティを利用して、流れてくるデータの長さを取得・表示しています。このフィルターをphp://memoryストリームに適用し、データを書き込むことで、datalenが各書き込み操作によって生成されるバケットのデータ長を正確に教えてくれる様子が示されています。これにより、ストリームフィルターはデータの内容だけでなく、その長さに基づいてさまざまな処理を実行できるようになります。