【PHP8.x】STREAM_NOTIFY_COMPLETED定数の使い方

Copy
1<?php
2
3/**
4 * 特定のURLからコンテンツをフェッチし、ストリーム通知とブロッキング設定をデモンストレーションします。
5 *
6 * この関数は、ストリーム操作の完了を STREAM_NOTIFY_COMPLETED 定数を通じて通知し、
7 * stream_set_blocking 関数でストリームのブロッキングモードを設定する方法を示します。
8 *
9 * @param string $url フェッチするURL。
10 * @return string|null フェッチしたコンテンツ、または失敗した場合はnull。
11 */
12function fetchContentWithStreamFeatures(string $url): ?string
13{
14    // ストリーム操作のイベントを処理するコールバック関数を定義します。
15    // この関数は、ストリーム操作中に様々な通知イベントが発生したときにPHPによって呼び出されます。
16    // STREAM_NOTIFY_COMPLETED は、ストリーム操作が正常に完了したことを示します。
17    $notificationCallback = function (
18        int $notificationCode,
19        int $severity,
20        string $message,
21        int $messageCode,
22        int $bytesTransferred,
23        int $bytesMax
24    ) {
25        // STREAM_NOTIFY_COMPLETED コードをチェックし、操作完了時にメッセージを出力します。
26        if ($notificationCode === STREAM_NOTIFY_COMPLETED) {
27            echo "通知: ストリーム操作が完了しました。メッセージ: " . $message . PHP_EOL;
28        }
29        // 他の通知イベント（例: STREAM_NOTIFY_PROGRESS - 転送進行状況）もここで処理できます。
30        // if ($notificationCode === STREAM_NOTIFY_PROGRESS) {
31        //     echo "転送中: " . $bytesTransferred . " / " . $bytesMax . " バイト" . PHP_EOL;
32        // }
33    };
34
35    // ストリームコンテキストを作成し、通知コールバックを設定します。
36    // 'http' オプションはHTTPリクエストの挙動を制御します。
37    // 'notification' オプションに上記のコールバック関数を指定することで、ストリームイベントを捕捉できます。
38    $context = stream_context_create([
39        'http' => [
40            'follow_location' => 1, // HTTPリダイレクトを自動的に追跡します
41        ],
42        'notification' => $notificationCallback,
43    ]);
44
45    // 指定されたURLからストリームを開きます。
46    // 'r' は読み込みモードを示します。第4引数に $context を渡すことで、上記の通知コールバックが有効になります。
47    $stream = @fopen($url, 'r', false, $context);
48
49    // ストリームが開けなかった場合のエラー処理
50    if (!$stream) {
51        error_log("エラー: URL '" . $url . "' を開けませんでした。");
52        return null;
53    }
54
55    // ストリームのブロッキングモードを設定します。
56    // stream_set_blocking(リソース, ブロッキングを有効にするか)
57    // true: ブロッキングモード (デフォルト)。I/O操作はデータが利用可能になるまで処理を一時停止（ブロック）します。
58    // false: 非ブロッキングモード。I/O操作はデータがなくてもすぐに制御を返し、データがない場合はfalseを返します。
59    // ここではブロッキングモード (true) に設定していますが、必要に応じて非ブロッキングモード (false) にも設定可能です。
60    // (非ブロッキングモードの場合、stream_select() などと組み合わせて使うのが一般的です)
61    if (!stream_set_blocking($stream, true)) { // 例としてブロッキングモードを明示的に設定
62        error_log("エラー: ストリームのブロッキングモードを設定できませんでした。");
63        fclose($stream);
64        return null;
65    }
66
67    // ストリームから全てのコンテンツを読み込みます。
68    // stream_get_contents は、ストリームがブロッキングモードであれば全てのデータが読み込まれるまで待機します。
69    $content = stream_get_contents($stream);
70
71    // ストリームを閉じます。
72    // この fclose() の後に STREAM_NOTIFY_COMPLETED 通知が発生します。
73    fclose($stream);
74
75    return $content;
76}
77
78// --- スクリプトの実行例 ---
79$targetUrl = "https://www.example.com"; // 動作確認用のURL
80
81echo "URL: " . $targetUrl . " からコンテンツをフェッチしています..." . PHP_EOL;
82$fetchedContent = fetchContentWithStreamFeatures($targetUrl);
83
84if ($fetchedContent !== null) {
85    echo "コンテンツのフェッチが成功しました。最初の100文字: " . substr($fetchedContent, 0, 100) . "..." . PHP_EOL;
86} else {
87    echo "コンテンツのフェッチに失敗しました。" . PHP_EOL;
88}
89
90?>

このPHPサンプルコードは、特定のURLからウェブコンテンツを取得する過程で、PHPのストリーム機能における通知メカニズムとブロッキング設定を実演しています。

まず、STREAM_NOTIFY_COMPLETED定数は、PHPのストリーム操作が正常に完了したことを示す整数値の通知コードです。このコードは、ストリーム操作中に発生する様々なイベントを捕捉するためのコールバック関数内で利用され、操作の最終的な成功を通知するために用いられます。この定数自体に引数はありませんが、コールバック関数に渡される際にその値が使用されます。戻り値は整数型の定数値です。

次に、stream_set_blocking関数は、指定されたストリームリソースのブロッキングモードを設定するものです。この関数は、最初の引数に設定対象のストリームリソースを、二番目の引数にブロッキングを有効にするか否かを示す真偽値（trueまたはfalse）を取ります。引数がtrueの場合、ストリームはブロッキングモードとなり、読み書き操作はデータが利用可能になるか、書き込みが完了するまでプログラムの実行を一時停止（ブロック）します。一方、falseを指定すると非ブロッキングモードとなり、データがすぐに利用できない場合でも即座に制御を返し、プログラムは他の処理に進むことができます。この関数の戻り値は、設定に成功した場合はtrue、失敗した場合はfalseです。

サンプルコードでは、まずストリームイベントを処理するコールバック関数を定義し、この関数内でSTREAM_NOTIFY_COMPLETEDを検出して完了メッセージを出力しています。このコールバック関数は、stream_context_createで作成されるストリームコンテキストに設定され、fopen関数でURLを開く際に適用されます。fopenでストリームを開いた後、stream_set_blocking関数を使ってストリームをブロッキングモードに明示的に設定しています。これにより、続くstream_get_contents関数によるコンテンツの読み込みは、全てのデータが取得されるまで待機し、確実に完了することが保証されます。最後にfcloseでストリームを閉じると、設定された通知コールバックを通じてSTREAM_NOTIFY_COMPLETEDが通知され、操作の成功が示されます。この一連の処理を通じて、ストリームの基本的なデータ転送とイベント通知の仕組みを学ぶことができます。

Copy
1<?php
2
3/**
4 * ストリーム通知コールバック関数。
5 * stream_context_create でコンテキストに設定され、ストリーム操作の進捗や完了を通知します。
6 *
7 * @param int $notification_code 発生したイベントを示す定数 (例: STREAM_NOTIFY_COMPLETED)
8 * @param int $severity イベントの重要度
9 * @param string $message イベントに関するメッセージ
10 * @param int $message_code メッセージコード
11 * @param int $bytes_transferred 現在までに転送されたバイト数
12 * @param int $bytes_max 総バイト数 (不明な場合は0)
13 */
14function downloadStreamNotificationCallback(
15    int $notification_code,
16    int $severity,
17    string $message,
18    int $message_code,
19    int $bytes_transferred,
20    int $bytes_max
21): void {
22    // STREAM_NOTIFY_COMPLETED は、ストリーム操作（例えばファイルのダウンロード）が正常に完了したことを示します。
23    // この定数は整数値を持ち、通知コールバック関数に渡される $notification_code と比較することで利用されます。
24    if ($notification_code === STREAM_NOTIFY_COMPLETED) {
25        echo "[通知] ダウンロード完了: $message\n";
26    } elseif ($notification_code === STREAM_NOTIFY_FILE_SIZE_IS) {
27        echo "[通知] ファイルサイズ: " . ($bytes_max > 0 ? $bytes_max . "バイト" : "不明") . "\n";
28    } elseif ($notification_code === STREAM_NOTIFY_PROGRESS) {
29        // 進捗状況は頻繁に発生するため、ここでは詳細な出力は省略
30        // echo "[通知] 進捗: $bytes_transferred / $bytes_max バイト転送済み\n";
31    } elseif ($severity === STREAM_NOTIFY_SEVERITY_ERR) {
32        echo "[エラー通知] エラーコード: $notification_code ($message_code) - $message\n";
33    }
34}
35
36/**
37 * 外部URLからファイルを非同期にダウンロードし、stream_select で進捗を監視するサンプルコード。
38 * STREAM_NOTIFY_COMPLETED は、ダウンロード操作の完了を通知する際に利用されます。
39 */
40function downloadFileAsyncWithStreamSelect(string $url): void
41{
42    echo "URL: $url からの非同期ダウンロードを開始します。\n";
43
44    // ストリームコンテキストを作成し、通知コールバックを設定します。
45    // このコンテキストは、fopen などのストリーム操作に適用され、
46    // 操作の進捗や完了を downloadStreamNotificationCallback に通知します。
47    $context = stream_context_create([
48        'notification' => ['callback' => 'downloadStreamNotificationCallback']
49    ]);
50
51    // 外部URLをストリームとして開きます。
52    // コンテキストを適用し、ノンブロッキングモードに設定します。
53    $stream = @fopen($url, 'rb', false, $context);
54
55    if (!$stream) {
56        echo "エラー: ストリームを開けませんでした。\n";
57        return;
58    }
59
60    // ストリームをノンブロッキングモードに設定します。
61    // これにより、fread などの操作がすぐに戻り、データを待ってブロックされなくなります。
62    stream_set_blocking($stream, false);
63
64    $downloaded_data = '';
65    $sockets = [$stream]; // stream_select で監視するストリームのリスト
66
67    echo "ダウンロード中...\n";
68
69    // stream_select を使って、ストリームが読み込み可能になるのを監視します。
70    while (true) {
71        $read_streams = $sockets;
72        $write_streams = [];
73        $except_streams = [];
74
75        // stream_select は、指定されたストリームのどれかが読み込み可能、書き込み可能、
76        // または例外状態になるまで待機します。タイムアウトは500ミリ秒（0.5秒）。
77        // 戻り値は準備ができたストリームの数。
78        $num_changed_streams = stream_select($read_streams, $write_streams, $except_streams, 0, 500000);
79
80        if ($num_changed_streams === false) {
81            echo "エラー: stream_select が失敗しました。\n";
82            break;
83        }
84
85        if ($num_changed_streams === 0) {
86            // タイムアウトしたが、何もストリームの状態が変化しなかった場合
87            // 他の処理を行うか、再度待機する
88            continue;
89        }
90
91        // 読み込み可能になったストリームを処理します。
92        foreach ($read_streams as $ready_stream) {
93            if ($ready_stream === $stream) {
94                // ストリームからデータを読み込みます。
95                // ノンブロッキングモードのため、利用可能なデータがあればすぐに返ります。
96                $buffer = fread($stream, 8192); // 8KBずつ読み込む
97
98                if ($buffer === false) {
99                    echo "エラー: ストリームの読み込み中に問題が発生しました。\n";
100                    break 2; // ループを抜ける
101                }
102
103                if ($buffer === '') {
104                    // ストリームの終端に達した（EOF）か、データが一時的にない場合
105                    if (feof($stream)) {
106                        echo "ダウンロードが完了しました！\n";
107                        break 2; // ループを抜ける
108                    }
109                    // まだデータが残っているが、現在利用可能でない場合は待機を続ける
110                } else {
111                    $downloaded_data .= $buffer;
112                    // echo "読み込み中: " . strlen($buffer) . "バイト受信。\n";
113                }
114            }
115        }
116    }
117
118    // ストリームを閉じます。
119    fclose($stream);
120
121    echo "ダウンロードされたデータの合計サイズ: " . strlen($downloaded_data) . "バイト\n";
122    // echo "ダウンロードされたデータの一部:\n" . substr($downloaded_data, 0, 200) . "...\n";
123}
124
125// サンプルとして、PHP公式サイトのトップページをダウンロードします。
126// ネットワークアクセスが必要なため、インターネット接続が必要です。
127downloadFileAsyncWithStreamSelect('https://www.php.net/');
128
129// STREAM_NOTIFY_COMPLETED 定数の値を確認 (int型)
130// echo "STREAM_NOTIFY_COMPLETED の値: " . STREAM_NOTIFY_COMPLETED . "\n";

PHPの定数STREAM_NOTIFY_COMPLETEDは、ファイル転送やネットワーク通信などのストリーム操作が正常に完了したことを示す整数値です。この定数自体は引数を取りませんが、その値は、stream_context_create関数で設定される通知コールバック関数に$notification_codeとして渡され、ストリームイベントの種類を識別するために利用されます。

サンプルコードでは、downloadStreamNotificationCallbackというコールバック関数が定義されており、外部URLからのファイルダウンロード中に発生する様々なイベントを処理します。特に、この関数内で$notification_codeがSTREAM_NOTIFY_COMPLETEDと一致した場合に、「ダウンロード完了」のメッセージが表示され、非同期で行われた操作の成功を明確に通知します。

downloadFileAsyncWithStreamSelect関数は、stream_selectを利用してファイルを非同期でダウンロードする例です。stream_selectは、ストリームが読み込み可能になるのをノンブロッキングで待機し、データが利用可能になり次第読み込みます。この非同期処理の中で、STREAM_NOTIFY_COMPLETEDはストリーム操作の最終的な成功をコールバックを通じて確認し、ダウンロード完了の検出に役立つ重要な役割を果たします。