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

Copy
1<?php
2
3/**
4 * ストリーム通知イベントを処理するコールバック関数。
5 * システムエンジニアを目指す初心者向けに、ストリーム処理の各段階を可視化します。
6 * STREAM_NOTIFY_RESOLVE イベントは、ホスト名の解決が開始されたときに通知されます。
7 *
8 * @param int $notificationCode 通知の種類を示すコード（例: STREAM_NOTIFY_RESOLVE, STREAM_NOTIFY_CONNECT など）
9 * @param int $severity 通知の重大度
10 * @param string $message 通知メッセージ
11 * @param int $messageCode 通知メッセージに関連する数値コード
12 * @param int $bytesTransferred 転送されたバイト数
13 * @param int $bytesMax 最大転送バイト数
14 * @return void
15 */
16function handleStreamNotification(
17    int $notificationCode,
18    int $severity,
19    string $message,
20    int $messageCode,
21    int $bytesTransferred,
22    int $bytesMax
23): void {
24    echo "--- Stream Notification ---\n";
25    echo "Code: " . $notificationCode;
26    // STREAM_NOTIFY_RESOLVE は、ホスト名の解決処理が開始されたことを示す定数です。
27    // DNSルックアップなどが行われる際にこのイベントが通知されます。
28    if ($notificationCode === STREAM_NOTIFY_RESOLVE) {
29        echo " (STREAM_NOTIFY_RESOLVE - ホスト名解決開始)";
30    }
31    echo "\nSeverity: " . $severity . "\n";
32    echo "Message: " . $message . "\n";
33    echo "Message Code: " . $messageCode . "\n";
34    echo "Bytes Transferred: " . $bytesTransferred . "\n";
35    echo "Bytes Max: " . $bytesMax . "\n";
36    echo "---------------------------\n\n";
37}
38
39/**
40 * stream_socket_client を使用してリモートホストに接続し、
41 * STREAM_NOTIFY_RESOLVE を含むストリーム通知を捕捉するサンプル関数。
42 *
43 * @param string $host 接続先ホスト（例: 'tcp://example.com:80'）
44 * @param int $timeout 接続タイムアウト（秒）
45 * @return bool 接続に成功した場合は true、失敗した場合は false
46 */
47function connectWithNotification(string $host, int $timeout = 5): bool
48{
49    // ストリームコンテキストを作成し、通知コールバックを設定します。
50    // これにより、ストリーム処理の様々な段階でイベントを受け取ることができます。
51    $context = stream_context_create([
52        'socket' => [
53            'timeout' => $timeout, // 接続タイムアウトを設定
54        ],
55        // 'notification' オプションにコールバック関数名を指定することで、
56        // ストリームの処理中に発生するイベントを捕捉できます。
57        // ホスト名解決 (STREAM_NOTIFY_RESOLVE) などがこのコールバックで通知されます。
58        'notification' => 'handleStreamNotification',
59    ]);
60
61    echo "Attempting to connect to: " . $host . " with timeout: " . $timeout . "s\n\n";
62
63    $errorCode = 0;
64    $errorMessage = '';
65
66    // stream_socket_client でソケット接続を試みます。
67    // この関数が内部でホスト名解決を行う際に、上記で設定したコールバックが
68    // STREAM_NOTIFY_RESOLVE を含む様々なイベントを受け取ります。
69    $socket = stream_socket_client(
70        $host,
71        $errorCode,
72        $errorMessage,
73        $timeout,
74        STREAM_CLIENT_CONNECT, // 接続モードを指定 (TCP/UDP クライアント接続)
75        $context // 作成したストリームコンテキストを渡す
76    );
77
78    if ($socket) {
79        echo "Successfully connected to " . $host . "\n";
80        // 接続が成功したら、リソースを適切に閉じます。
81        fclose($socket);
82        echo "Connection closed.\n";
83        return true;
84    } else {
85        echo "Failed to connect to " . $host . ".\n";
86        echo "Error: (" . $errorCode . ") " . $errorMessage . "\n";
87        return false;
88    }
89}
90
91// --- サンプル実行 ---
92// example.com はテスト用に予約されたドメインで、DNS解決が行われます。
93// これにより、stream_socket_client の内部でホスト名解決処理が発生し、
94// handleStreamNotification 関数で STREAM_NOTIFY_RESOLVE イベントが通知されるのを観察できます。
95connectWithNotification('tcp://example.com:80', 3);

このPHPサンプルコードは、ネットワーク接続の内部的な進行状況を通知イベントで確認する方法を示しています。特にSTREAM_NOTIFY_RESOLVEは、接続先のホスト名（例: example.com）をIPアドレスに変換する「ホスト名解決」処理が開始された際に通知される定数です。

handleStreamNotification関数は、この通知を含むストリーム処理中に発生する様々なイベントを受け取るコールバック関数です。通知の種類を示すコード、重大度、メッセージなどの情報を引数として受け取り、その内容を出力します。

connectWithNotification関数は、実際にネットワーク接続を行う部分です。この関数では、まずstream_context_createを使ってストリームコンテキストを作成し、notificationオプションにhandleStreamNotification関数を設定します。これにより、ネットワーク接続の処理中に発生するイベントがhandleStreamNotification関数に送られるようになります。

その後、stream_socket_client関数で指定されたホスト（例: tcp://example.com:80）への接続を試みます。この関数は、接続先のホスト、エラーコード、エラーメッセージ、タイムアウト、接続モード、そして先ほど設定した通知コールバックを含むコンテキストを引数に取ります。接続が成功すればストリームリソースを返し、失敗すればfalseを返します。この一連の処理の中で、ホスト名解決が行われる際にSTREAM_NOTIFY_RESOLVEイベントがhandleStreamNotification関数に通知され、接続の準備段階からイベントの流れを詳細に把握できます。

Copy
1<?php
2
3/**
4 * ストリーム操作中に発生する様々な通知イベントを処理するコールバック関数です。
5 *
6 * この関数は、PHPがストリーム（ファイル、ネットワーク接続など）を操作する際に、
7 * 特定のイベントが発生すると自動的に呼び出されます。
8 * 特に STREAM_NOTIFY_RESOLVE は、ホスト名の解決（ドメイン名からIPアドレスへの変換）が
9 * 完了したときに通知されるイベントです。
10 *
11 * @param int    $notificationCode     発生した通知イベントのコード（例: STREAM_NOTIFY_RESOLVE）。
12 * @param int    $severity             イベントの重要度。
13 * @param string $message              イベントに関連するメッセージ。
14 * @param int    $messageCode          メッセージの数値コード。
15 * @param int    $bytesTransferred     現在までに転送されたバイト数。
16 * @param int    $bytesMax             転送される合計バイト数（不明な場合は0）。
17 */
18function handleStreamNotification(
19    int $notificationCode,
20    int $severity,
21    string $message,
22    int $messageCode,
23    int $bytesTransferred,
24    int $bytesMax
25): void {
26    echo "[通知] ";
27    switch ($notificationCode) {
28        case STREAM_NOTIFY_RESOLVE:
29            echo "ホスト名解決完了: '{$message}'\n";
30            break;
31        case STREAM_NOTIFY_CONNECT:
32            echo "接続開始: '{$message}'\n";
33            break;
34        case STREAM_NOTIFY_FILE_SIZE_IS:
35            echo "ファイルサイズ判明: {$bytesMax} バイト\n";
36            break;
37        case STREAM_NOTIFY_FAILURE:
38            echo "エラー発生: {$message}\n";
39            break;
40        case STREAM_NOTIFY_COMPLETED:
41            echo "ストリーム処理完了。\n";
42            break;
43        // STREAM_NOTIFY_PROGRESS は頻繁に発生するため、ここでは表示を省略します。
44        // 必要に応じてコメント解除して確認してください。
45        // case STREAM_NOTIFY_PROGRESS:
46        //     echo "転送中: {$bytesTransferred} / {$bytesMax} バイト\n";
47        //     break;
48        default:
49            // その他の通知イベントも確認したい場合は、ここにコードを追加してください。
50            // echo "その他通知: コード {$notificationCode}, メッセージ '{$message}'\n";
51            break;
52    }
53}
54
55// 1. ストリームコンテキストの作成
56//    これは、ネットワーク接続などのストリーム操作における挙動を細かく設定するためのものです。
57//    ここでは、特に 'notification' オプションを使って、上記で定義したコールバック関数を登録します。
58$context = stream_context_create([
59    'http' => [
60        'timeout' => 5, // 接続およびデータ読み込みのタイムアウトを5秒に設定
61    ],
62    'options' => [
63        // 'notification' オプションにコールバック関数の名前を指定することで、
64        // ストリームイベント発生時にこの関数が呼び出されるようになります。
65        'notification' => 'handleStreamNotification',
66    ],
67]);
68
69// 接続先のURL。ここでは一般的なWebサイトを使用します。
70$url = 'http://example.com';
71
72echo "--------------------------------------------------\n";
73echo "Webサイト '{$url}' への接続とストリーム操作を開始します。\n";
74echo "ストリームイベントの通知（特にホスト名解決）に注目してください。\n";
75echo "--------------------------------------------------\n";
76
77// 2. 指定されたURLに対してストリームを開く
78//    fopen関数は、ネットワーク接続を確立し、データ読み書きのためのストリームリソースを返します。
79//    この操作中に、設定した通知コールバック関数が呼び出され、ホスト名解決などのイベントが通知されます。
80//    @ はエラーメッセージが直接出力されるのを防ぎ、後で error_get_last() で詳細を確認します。
81$stream = @fopen($url, 'r', false, $context);
82
83if ($stream) {
84    echo "\nストリームが正常に開かれました。\n";
85    echo "--------------------------------------------------\n";
86    echo "ストリームのブロッキングモードを設定します。\n";
87    echo "--------------------------------------------------\n";
88
89    // 3. ストリームをブロッキングモードに設定（デフォルトの動作）
90    //    ブロッキングモードでは、ストリームからのデータ読み込み (fread() など) や書き込みが完了するまで、
91    //    スクリプトの実行が一時停止（ブロック）します。
92    echo "\n=> ストリームをブロッキングモード (true) に設定します。\n";
93    if (stream_set_blocking($stream, true)) {
94        echo "   設定成功。このモードではデータが到着するまで fread() は待機します。\n";
95        echo "   データ読み込み中 (最大1024バイト): \n";
96        $data = fread($stream, 1024); // データが利用可能になるまでブロックされます
97        if ($data === false) {
98            echo "   読み込みエラーが発生しました。\n";
99        } elseif ($data === '') {
100            echo "   データがありませんでした (ストリームの終端かもしれません)。\n";
101        } else {
102            echo "   一部データを読み込みました (最初の50バイト): '" . substr($data, 0, 50) . "...'\n";
103        }
104    } else {
105        echo "   ブロッキングモードの設定に失敗しました。\n";
106    }
107
108    // 4. ストリームをノンブロッキングモードに設定
109    //    ノンブロッキングモードでは、ストリームからのデータ読み込みや書き込み操作は、
110    //    データがすぐに利用できない場合でも、すぐに制御をスクリプトに返します。
111    //    データがなくてもスクリプトは続行されるため、ポーリングやイベントループで利用されます。
112    echo "\n=> ストリームをノンブロッキングモード (false) に設定します。\n";
113    if (stream_set_blocking($stream, false)) {
114        echo "   設定成功。このモードではデータが到着していなくても fread() はすぐに制御を返します。\n";
115        echo "   データ読み込み中 (最大1024バイト): \n";
116        $data = fread($stream, 1024); // データがなくてもすぐに制御が戻ります
117        if ($data === false) {
118            echo "   読み込みエラーが発生しました。\n";
119        } elseif ($data === '') {
120            echo "   データがまだ準備できていないか、既にストリームの終端に達している可能性があります。\n";
121            echo "   (ノンブロッキングモードでは、データがなくても空文字列が返されることがあります。)\n";
122        } else {
123            echo "   一部データを読み込みました (最初の50バイト): '" . substr($data, 0, 50) . "...'\n";
124        }
125    } else {
126        echo "   ノンブロッキングモードの設定に失敗しました。\n";
127    }
128
129    // 5. ストリームを閉じる
130    fclose($stream);
131    echo "\nストリームを閉じました。\n";
132
133} else {
134    echo "\nストリームを開けませんでした。\n";
135    $error = error_get_last();
136    if ($error) {
137        echo "エラー詳細: " . $error['message'] . "\n";
138    }
139}
140
141echo "--------------------------------------------------\n";
142echo "処理が完了しました。\n";
143echo "--------------------------------------------------\n";

このサンプルコードは、PHPにおけるストリーム操作中のイベント通知処理と、ストリームのブロッキングモード設定方法を具体的に示しています。

STREAM_NOTIFY_RESOLVEは、ファイルやネットワークなどのストリーム操作中に発生する様々な通知イベントの一つで、特にホスト名（ドメイン名）からIPアドレスへの解決処理が完了した際に通知されます。このようなストリームイベントを捕捉するため、stream_context_create関数を使ってストリームコンテキストを作成し、notificationオプションにイベント発生時に呼び出されるコールバック関数（handleStreamNotification）を登録しています。

コードの後半では、stream_set_blocking関数を使用してストリームのデータ読み書きの挙動を制御しています。この関数は、第一引数に操作対象のストリームリソース、第二引数にブロッキングモードを示す真偽値（trueでブロッキング、falseでノンブロッキング）を渡します。戻り値は、設定が成功した場合はtrue、失敗した場合はfalseです。

stream_set_blocking($stream, true)と設定すると、fread()などの読み込み操作はデータが到着するまでスクリプトの実行を一時的に停止（ブロック）します。対照的に、stream_set_blocking($stream, false)と設定すると、データが利用できない場合でもfread()はすぐに制御を返し、スクリプトは待機せずに次の処理へ進みます。この違いにより、ネットワーク通信などでデータの到着を待つか、他の処理と並行して進めるかを制御できるようになります。