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

Copy
1<?php
2
3/**
4 * ストリーム通知コールバック関数。
5 * ストリーム操作中に発生するさまざまな通知（STREAM_NOTIFY_*）を受け取ります。
6 * STREAM_NOTIFY_AUTH_REQUIRED の使われ方を示します。
7 *
8 * @param int $notificationCode 通知コード (STREAM_NOTIFY_*)
9 * @param int $severity 通知の重大度 (STREAM_NOTIFY_SEVERITY_*)
10 * @param string $message 通知メッセージ
11 * @param int $messageCode メッセージコード (例えばHTTPステータスコード)
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    // 発生した通知コードとメッセージを出力
25    echo "[通知] コード: {$notificationCode}, 重大度: {$severity}, メッセージ: '{$message}'";
26    if (!empty($messageCode)) {
27        echo " (内部コード: {$messageCode})";
28    }
29    echo "\n";
30
31    // STREAM_NOTIFY_AUTH_REQUIRED は、ストリーム操作で認証が必要な場合に発生する通知コードです。
32    // 例えば、プロキシ経由で外部リソースにアクセスする際に認証が要求された場合などにこの通知が送られます。
33    if ($notificationCode === STREAM_NOTIFY_AUTH_REQUIRED) {
34        echo "--- 重要な通知: 認証が必要です！ ---\n";
35        echo "この通知は、ストリーム操作において認証情報を求められていることを示します。\n";
36    }
37}
38
39/**
40 * 簡単なTCPソケットサーバーを起動し、クライアントからの接続を受け入れます。
41 * ストリームコンテキストに通知コールバックを設定し、STREAM_NOTIFY_AUTH_REQUIRED が
42 * どのような文脈で使われるかを示します。
43 *
44 * @param string $address サーバーがリッスンするアドレスとポート (例: "tcp://127.0.0.1:8000")
45 * @return void
46 */
47function startAuthAwareSocketServer(string $address): void
48{
49    // STREAM_NOTIFY_AUTH_REQUIRED 定数の値を出力します（int型です）。
50    echo "STREAM_NOTIFY_AUTH_REQUIRED の値: " . STREAM_NOTIFY_AUTH_REQUIRED . " (int型)\n\n";
51
52    // ストリームコンテキストを作成し、通知コールバックを設定します。
53    // このコールバックは、このコンテキストを使用して行われるストリーム操作中に発生する
54    // さまざまな通知（STREAM_NOTIFY_*）を受け取ることができます。
55    $context = stream_context_create([
56        'socket' => [
57            'notification' => 'handleStreamNotification',
58        ],
59        // このサンプルでは認証プロキシを実装していませんが、
60        // HTTPプロキシ認証などで通知が発生する可能性も考慮されます。
61    ]);
62
63    // stream_socket_server() 関数を使用してサーバーソケットを作成します。
64    // エラーが発生した場合にPHPの警告が出ないように `@` を付与し、独自にエラーハンドリングを行います。
65    $serverSocket = @stream_socket_server($address, $errno, $errstr, STREAM_SERVER_BIND | STREAM_SERVER_LISTEN, $context);
66
67    if (!$serverSocket) {
68        echo "サーバーの起動に失敗しました: {$errstr} ({$errno})\n";
69        return;
70    }
71
72    echo "サーバーが {$address} でリッスンしています。\n";
73    echo "クライアント接続を待っています (Ctrl+C で終了)。\n";
74
75    // サーバーソケットをノンブロッキングモードに設定し、
76    // `stream_socket_accept` が接続がない場合でもすぐに戻るようにします。
77    stream_set_blocking($serverSocket, false);
78
79    while (true) {
80        // stream_socket_accept() 関数でクライアントからの接続を受け入れます。
81        // タイムアウトを短く設定することで、ループがブロックされるのを防ぎます。
82        $clientSocket = @stream_socket_accept($serverSocket, 0.5, $peername);
83
84        if ($clientSocket) {
85            echo "\nクライアントが接続しました: {$peername}\n";
86
87            // ここで受け入れたクライアントソケット（これもストリームです）を通じて
88            // 認証が必要な上位プロトコル（例: HTTPリクエストに対する認証）を実装した場合、
89            // その認証処理中に STREAM_NOTIFY_AUTH_REQUIRED の通知が発生する可能性があります。
90            // このサンプルでは実際の認証エラーを発生させませんが、通知を受け取る準備はできています。
91
92            // 簡単な応答をクライアントに送信します。
93            fwrite($clientSocket, "Hello from PHP server!\n");
94            fwrite($clientSocket, "Your IP: {$peername}\n");
95            
96            // クライアントソケットを閉じます。
97            fclose($clientSocket);
98            echo "クライアント {$peername} の接続を閉じました。\n";
99        }
100
101        // CPU使用率を抑えるため、短時間待機します。
102        usleep(100000); // 100ミリ秒
103    }
104
105    // 理論上はここに到達しませんが、クリーンアップのために記述します。
106    fclose($serverSocket);
107}
108
109// サーバーを起動します。ご自身の環境に合わせてアドレスとポートを変更してください。
110// 例: "tcp://127.0.0.1:8000" は、ローカルホストのポート8000で待ち受けます。
111startAuthAwareSocketServer("tcp://127.0.0.1:8000");
112

STREAM_NOTIFY_AUTH_REQUIREDは、PHPのストリーム操作において、認証が必要な状況が発生したことを通知する整数定数です。例えば、プロキシサーバー経由で外部リソースにアクセスする際に認証情報が求められた場合などに、この通知が送られます。この定数自体は引数を取らず、戻り値として整数を返します。

このサンプルコードでは、STREAM_NOTIFY_AUTH_REQUIRED定数の実際の値が整数であることを示し、その使われ方を解説しています。startAuthAwareSocketServer関数は、stream_context_create関数を用いてストリームコンテキストを作成し、notificationオプションにhandleStreamNotificationというコールバック関数を設定しています。この設定により、stream_socket_serverやstream_socket_acceptのようなストリーム関連の操作中に発生する様々な通知を、handleStreamNotification関数で捕捉できるようになります。

handleStreamNotification関数は、第一引数で通知の種類を示す$notificationCode（整数型）、第三引数で詳細なメッセージ（文字列型）などを受け取ります。この関数内で$notificationCodeがSTREAM_NOTIFY_AUTH_REQUIREDと一致した場合に、認証が必要である旨のメッセージを出力しています。このサーバー自体は認証機能を持ちませんが、ストリーム操作中に認証要求が発生するシナリオにおいて、どのように通知を受け取り、対応するかの基本を示しています。

Copy
1<?php
2
3/**
4 * stream_socket_client を使用してリソースに接続し、
5 * STREAM_NOTIFY_AUTH_REQUIRED 定数を含むストリーム通知を監視する例。
6 *
7 * この関数は、システムエンジニアを目指す初心者向けに、
8 * PHPのストリーム通知メカニズムと STREAM_NOTIFY_AUTH_REQUIRED 定数の役割を示します。
9 * STREAM_NOTIFY_AUTH_REQUIRED は、ストリーム操作で認証が必要になった場合に
10 * 通知コールバックの $message_code として渡される定数です。
11 *
12 * 実際には、認証を要求するプロキシサーバーなどを経由しない限り、
13 * この定数が直接発生するのを観察するのは難しい場合があります。
14 * しかし、通知コールバックがどのように設定され、様々なイベントを処理するかを理解するのに役立ちます。
15 *
16 * @param string $host 接続先ホスト (例: "www.example.com")
17 * @param int $port 接続先ポート (例: 80)
18 * @param int $timeout 接続タイムアウト (秒)
19 * @return bool 接続が成功し、通信が完了した場合は true、それ以外は false
20 */
21function connectAndMonitorStreamAuth(string $host, int $port, int $timeout = 10): bool
22{
23    echo "Attempting to connect to $host:$port with stream notifications...\n";
24
25    // ストリームコンテキストを作成
26    // ストリームの振る舞いをカスタマイズするための設定を保持します。
27    $context = stream_context_create();
28
29    // 通知コールバック関数を無名関数として定義
30    // このコールバックは、ストリーム操作中にPHPが特定のイベントを検出したときに呼び出されます。
31    $notificationCallback = function (
32        int $notification_code,
33        int $severity,
34        string $message,
35        int $message_code,
36        int $bytes_transferred,
37        int $bytes_max
38    ): void {
39        echo "--- Stream Notification ---\n";
40        echo "  Notification Code: $notification_code, Severity: $severity\n";
41        echo "  Message: '$message'\n";
42        echo "  Message Code: $message_code\n";
43
44        // STREAM_NOTIFY_AUTH_REQUIRED は、ストリーム操作で認証が必要になった場合に発生します。
45        // 例えば、認証を要求するプロキシサーバーを介して接続する場合などです。
46        if ($message_code === STREAM_NOTIFY_AUTH_REQUIRED) {
47            echo "  [IMPORTANT] Detected: Authentication is required for this stream!\n";
48            // ここに認証情報を設定するロジックなどを追加できます。
49            // 例: stream_context_set_option($context, 'http', 'header', 'Proxy-Authorization: Basic ...');
50        }
51        echo "---------------------------\n";
52    };
53
54    // コンテキストに通知コールバックを設定
55    // この設定により、ストリーム操作中に上記 $notificationCallback が呼び出されます。
56    if (!stream_context_set_params($context, ['notification' => $notificationCallback])) {
57        echo "Error: Could not set stream notification callback.\n";
58        return false;
59    }
60
61    $errno = 0;
62    $errstr = '';
63
64    // stream_socket_client を使用してソケット接続を試みる
65    // 第一引数は接続先のアドレス (例: "tcp://www.example.com:80")
66    // 第五引数は作成したコンテキスト。これにより、通知コールバックが適用されます。
67    $client = @stream_socket_client(
68        "tcp://$host:$port",
69        $errno,
70        $errstr,
71        $timeout,
72        STREAM_CLIENT_CONNECT, // 接続のみを行うフラグ
73        $context
74    );
75
76    if (!$client) {
77        echo "Failed to connect: [$errno] $errstr\n";
78        return false;
79    }
80
81    echo "Successfully connected to $host:$port.\n";
82
83    // 接続成功後、簡単なHTTPリクエストを送信して応答を読み込む
84    $request = "GET / HTTP/1.1\r\nHost: $host\r\nConnection: close\r\n\r\n";
85    fwrite($client, $request);
86
87    echo "--- Server Response ---\n";
88    while (!feof($client)) {
89        echo fgets($client, 1024);
90    }
91    echo "-----------------------\n";
92
93    // ソケット接続を閉じる
94    fclose($client);
95    echo "Connection closed.\n";
96    return true;
97}
98
99// --- サンプル実行 ---
100
101// 1. 一般的なウェブサイトに接続する例
102// 認証は不要なため、STREAM_NOTIFY_AUTH_REQUIRED が発生することは稀ですが、
103// その他の通知イベント（接続、進捗など）がコールバックで処理されることを確認できます。
104echo "--- Example 1: Connecting to www.example.com (HTTP) ---\n";
105connectAndMonitorStreamAuth("www.example.com", 80);
106
107echo "\n--- Example 2: Connecting to a non-existent host ---\n";
108// 2. 存在しないホストへの接続を試みる例
109// この場合、接続失敗に関連する通知（STREAM_NOTIFY_FAILURE など）が発生します。
110connectAndMonitorStreamAuth("nonexistent.example.com", 80);
111
112?>

このPHPサンプルコードは、stream_socket_client関数を使用してネットワーク接続を確立し、その過程で発生する様々なストリーム通知イベントを監視する方法を示しています。特にSTREAM_NOTIFY_AUTH_REQUIRED定数は、ストリーム操作中に認証が必要になった際に通知コールバック関数に渡されるメッセージコードであり、システムエンジニアを目指す方々がストリームの動作を深く理解するのに役立ちます。

コードでは、まずstream_context_createでストリームコンテキストを作成し、そのコンテキストに対して通知コールバック関数を設定しています。このコールバック関数は、接続の進行状況やエラー、そして認証要求といったイベントが発生するたびに自動的に呼び出されます。コールバック内では、$message_code引数がSTREAM_NOTIFY_AUTH_REQUIREDと一致した場合に、認証が必要であることを検知し、特別な処理を記述できるようになっています。

stream_socket_client関数は、指定されたホストとポートにソケット接続を試みます。この関数には、接続先アドレス、エラーコード、エラー文字列、タイムアウト時間、そして先ほど設定した通知コールバックを含むストリームコンテキスト（第5引数）が渡されます。引数$hostは接続先ホスト、$portはポート番号、$timeoutは接続のタイムアウト秒数を指定し、関数は接続と通信が成功したかを示す真偽値（trueまたはfalse）を戻り値として返します。成功時にはソケットリソースが返され、簡単なHTTPリクエストの送受信が行われます。この例を通じて、PHPのストリーム通知メカニズムと特定のイベントハンドリングの基本を学べます。