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

Copy
1<?php
2
3/**
4 * ストリーム通知イベントを処理するコールバック関数です。
5 * stream_socket_client のようなストリーム操作中に発生する様々なイベント（通知）を
6 * 受け取り、処理する方法を示します。
7 *
8 * STREAM_NOTIFY_AUTH_RESULT は、TLS/SSL接続における認証結果を示す通知コードです。
9 * この通知により、接続の認証が成功したか、または問題があったかを知ることができます。
10 *
11 * @param int $notificationCode 通知コード (例: STREAM_NOTIFY_AUTH_RESULT)
12 * @param int $severity 通知の重大度
13 * @param string $message 通知メッセージ
14 * @param int $messageCode メッセージのコード
15 * @param int $bytesTransferred 現在までに転送されたバイト数
16 * @param int $bytesMax 最大転送バイト数（不明な場合は0）
17 * @return void
18 */
19function streamNotificationCallback(
20    int $notificationCode,
21    int $severity,
22    string $message,
23    int $messageCode,
24    int $bytesTransferred,
25    int $bytesMax
26): void {
27    // 通知イベントの種類に基づいて処理を分岐します
28    switch ($notificationCode) {
29        case STREAM_NOTIFY_AUTH_RESULT:
30            echo "通知: 認証結果受信: {$message} ";
31            // messageCode が0の場合は認証成功、それ以外は失敗を示すことが多いです
32            if ($messageCode === 0) {
33                echo "[成功]";
34            } else {
35                echo "[失敗]";
36            }
37            break;
38        case STREAM_NOTIFY_CONNECT:
39            echo "通知: 接続を開始しました...";
40            break;
41        case STREAM_NOTIFY_COMPLETED:
42            echo "通知: ストリーム操作が完了しました。";
43            break;
44        case STREAM_NOTIFY_FAILURE:
45            echo "通知: エラーが発生しました: {$message}";
46            break;
47        // 他の STREAM_NOTIFY_* 定数も同様に処理できます
48        default:
49            echo "通知: 未知のイベント ({$notificationCode}): {$message}";
50            break;
51    }
52    echo " (重大度: {$severity}, コード: {$messageCode}, 転送: {$bytesTransferred}/{$bytesMax} バイト)\n";
53}
54
55/**
56 * 指定されたホストとポートへの安全な（TLS/SSL）クライアントソケット接続を確立します。
57 * stream_socket_client とストリームコンテキストオプションを使用して、
58 * 通知コールバックとSSL/TLS設定を適用する方法を示します。
59 *
60 * @param string $host 接続先のホスト名 (例: 'www.example.com')
61 * @param int $port 接続先のポート番号 (例: 443 for HTTPS)
62 * @return resource|false 接続に成功した場合はソケットストリームリソース、失敗した場合は false
63 */
64function createSecureClientConnection(string $host, int $port)
65{
66    $errno = null; // エラーコードを受け取るための変数
67    $errstr = null; // エラーメッセージを受け取るための変数
68
69    // ストリームコンテキストを作成し、接続に関するオプションを設定します。
70    // 特に、SSL/TLSオプションと通知コールバックが重要です。
71    $context = stream_context_create([
72        'ssl' => [
73            // リモートサーバーの証明書の検証を有効にします。
74            // 本番環境ではセキュリティのために true に設定することを強く推奨します。
75            'verify_peer' => true,
76            // サーバーのホスト名が証明書に記載されているものと一致するか検証します。
77            'verify_peer_name' => true,
78            // 適切なCA証明書バンドルへのパスを設定できますが、
79            // 多くのシステムではPHPがデフォルトのCA証明書を認識します。
80            // 'cafile' => '/path/to/your/ca-bundle.crt',
81            // 'capath' => '/path/to/your/ca-certs/',
82        ],
83        // ストリーム通知コールバック関数を設定します。
84        // これにより、接続中に発生するイベントを streamNotificationCallback 関数で捕捉できます。
85        'notification' => 'streamNotificationCallback',
86    ]);
87
88    echo "--- 接続試行中: ssl://{$host}:{$port} ---\n";
89
90    // stream_socket_client を使用して、指定されたホストとポートにソケット接続を試みます。
91    // 'ssl://' プレフィックスを付けることで、自動的にSSL/TLSハンドシェイクが行われます。
92    // 作成したストリームコンテキストを第5引数として渡し、設定を適用します。
93    // @ を付けることで、接続失敗時にPHPの標準エラーメッセージが出力されるのを抑制し、
94    // $errno と $errstr でエラーをより詳細に処理します。
95    $socket = @stream_socket_client(
96        "ssl://{$host}:{$port}",
97        $errno,
98        $errstr,
99        30, // 接続のタイムアウト時間（秒）
100        STREAM_CLIENT_CONNECT, // 接続モード（クライアント接続）
101        $context // 上で作成したストリームコンテキスト
102    );
103
104    if (!$socket) {
105        echo "--- 接続失敗: エラー ({$errno}) {$errstr} ---\n";
106        return false;
107    }
108
109    echo "--- {$host}:{$port} への接続に成功しました。---\n";
110
111    // ここでソケットに対してデータの読み書きを行うことができます。
112    // 例: HTTP GET リクエストを送信し、応答を読み取る
113    // fwrite($socket, "GET / HTTP/1.1\r\nHost: {$host}\r\nConnection: Close\r\n\r\n");
114    // while (!feof($socket)) {
115    //     echo fgets($socket, 1024);
116    // }
117
118    return $socket;
119}
120
121// --- サンプル使用例 ---
122$targetHost = 'www.example.com'; // 接続先のホスト名を指定
123$targetPort = 443; // HTTPSの標準ポートを指定
124
125// 安全なクライアント接続を確立します
126$socketConnection = createSecureClientConnection($targetHost, $targetPort);
127
128// 接続が成功した場合は、ソケットリソースを閉じます
129if ($socketConnection) {
130    echo "--- ソケットを閉じます。---\n";
131    fclose($socketConnection);
132}
133
134?>

このPHPサンプルコードは、ネットワークを介した安全な通信（TLS/SSL接続）を確立し、その過程で発生するイベントを処理する方法を示しています。

特にSTREAM_NOTIFY_AUTH_RESULTは、接続先のサーバーが正規のものであるかを確認するTLS/SSL認証の結果を示す定数です。これにより、接続の安全性が確保されたか、または問題があったかをプログラムで把握できます。

streamNotificationCallback関数は、STREAM_NOTIFY_AUTH_RESULTを含む、ストリーム操作中に発生する様々な通知イベントを捕捉し、処理するためのコールバック関数です。この関数には、通知の種類、重大度、メッセージなどの詳細情報が引数として渡されますが、特定の値を返す必要はありません。

createSecureClientConnection関数は、stream_socket_client関数を用いて、指定されたホストとポートへのSSL/TLSクライアント接続を試みます。この接続設定にはstream_context_createで作成されたストリームコンテキストが使用され、そのコンテキスト内でサーバー証明書の検証を有効にしたり、streamNotificationCallback関数を通知ハンドラとして登録したりしています。stream_socket_clientは接続に成功するとソケットのリソースを返し、失敗するとfalseを返します。この仕組みにより、開発者は安全な接続の認証結果をリアルタイムに監視し、状況に応じた処理を行うことが可能となります。

Copy
1<?php
2
3// 1. カスタムストリームフィルタークラスの定義
4// `php_user_filter`を継承し、ストリームデータを変換するフィルターを作成します。
5class MyUppercaseFilter extends php_user_filter
6{
7    /**
8     * ストリームフィルターがデータを処理するメソッドです。
9     * 入力データバケットからデータを受け取り、変換して出力バケットへ書き込みます。
10     *
11     * @param resource $in 入力バケットブリゲード (データソース)
12     * @param resource $out 出力バケットブリゲード (変換後のデータ格納先)
13     * @param int $consumed 処理されたバイト数を格納する変数への参照
14     * @param bool $closing ストリームが閉じられようとしているかどうかのフラグ
15     * @return int フィルター処理の結果 (PSFS_PASS_ON, PSFS_FEED_ME, PSFS_ERR_FATALなど)
16     */
17    public function filter($in, $out, &$consumed, bool $closing): int
18    {
19        while ($bucket = stream_bucket_make_writeable($in)) {
20            // 受信したデータを全て大文字に変換します。
21            $bucket->data = strtoupper($bucket->data);
22            $consumed += $bucket->datalen;
23            stream_bucket_append($out, $bucket);
24        }
25
26        return PSFS_PASS_ON; // 変換したデータを次の処理またはストリームへ渡します
27    }
28}
29
30// 2. カスタムストリームフィルターの登録
31// "my.uppercase"という名前でMyUppercaseFilterクラスを登録します。
32if (!stream_filter_register('my.uppercase', MyUppercaseFilter::class)) {
33    die("カスタムフィルター 'my.uppercase' の登録に失敗しました。\n");
34}
35echo "カスタムフィルター 'my.uppercase' が登録されました。\n\n";
36
37// 3. ストリーム通知コールバック関数の定義
38// ストリームに関する様々な通知イベントを受け取るグローバル関数です。
39// `STREAM_NOTIFY_AUTH_RESULT`は認証結果を示す通知コードとして使用されます。
40function myNotificationCallback(
41    int $notification_code,
42    int $severity,
43    string $message,
44    int $message_code,
45    int $bytes_transferred,
46    int $bytes_max
47): void {
48    echo "--- ストリーム通知イベント受信 --- \n";
49    echo "  通知コード: {$notification_code}\n";
50    echo "  深刻度: {$severity}\n";
51    echo "  メッセージ: {$message}\n";
52    echo "  メッセージコード: {$message_code}\n";
53
54    // `STREAM_NOTIFY_AUTH_RESULT` 定数は、認証プロセス結果の通知コードとして使われます。
55    // この定数自体に特定のデータや戻り値はありませんが、通知イベントの種類を示します。
56    if ($notification_code === STREAM_NOTIFY_AUTH_RESULT) {
57        echo "  --> 認証結果の通知を受信しました。\n";
58        // 実際のアプリケーションでは、ここで認証の成否（`severity`や`message_code`から判断）
59        // に応じて、適切なエラー処理や後続の処理を行います。
60    }
61    echo "--------------------------------- \n\n";
62}
63
64// 4. ストリームコンテキストの作成と通知コールバックの設定
65// ストリーム操作中に発生する通知を受け取るために、ストリームコンテキストに
66// `myNotificationCallback`関数を設定します。
67$context = stream_context_create([
68    'notification' => 'myNotificationCallback',
69]);
70echo "ストリーム通知コールバックが設定されたコンテキストを作成しました。\n\n";
71
72// 5. ストリームのオープン、フィルターの適用、および操作
73// `php://memory` ストリームを使用し、上記で登録したカスタムフィルターと
74// 通知コールバックが設定されたコンテキストを適用します。
75// `php://memory` は認証を伴わないため、`STREAM_NOTIFY_AUTH_RESULT`通知は通常発生しませんが、
76// 通知コールバックの仕組みとフィルターの適用方法を示す目的の例です。
77$fp = fopen('php://memory', 'w+', false, $context);
78
79if (!$fp) {
80    die("`php://memory` ストリームのオープンに失敗しました。\n");
81}
82
83// オープンしたストリームにカスタムフィルターを適用します。
84// `STREAM_FILTER_WRITE`を指定することで、ストリームへの書き込み時にフィルターが適用されます。
85if (!stream_filter_append($fp, 'my.uppercase', STREAM_FILTER_WRITE)) {
86    die("カスタムフィルター 'my.uppercase' の適用に失敗しました。\n");
87}
88echo "ストリームにカスタムフィルター 'my.uppercase' が適用されました (書き込み時)。\n\n";
89
90$originalData = "Hello world from PHP stream filter.\n";
91echo "元のデータ: {$originalData}";
92
93// データをストリームに書き込みます。この時、`my.uppercase` フィルターが適用され、データが大文字に変換されます。
94fwrite($fp, $originalData);
95echo "データ書き込み完了。\n";
96
97// ストリームポインタを先頭に戻し、書き込まれたデータを読み込みます。
98rewind($fp);
99$filteredData = stream_get_contents($fp);
100echo "フィルター適用後のデータ (大文字変換済み): {$filteredData}\n\n";
101
102// ストリームを閉じます。
103fclose($fp);
104echo "ストリームが閉じられました。\n";
105
106// 補足:
107// `STREAM_NOTIFY_AUTH_RESULT` は、FTPやSSHなど認証が必要なリモートプロトコルを扱うストリームで
108// 認証プロセス中に発生する結果を通知する際に使用されます。この例ではローカルの `php://memory` を
109// 使用しているため、この特定の認証通知は発生しませんが、通知コールバックの一般的な利用方法と
110// `STREAM_NOTIFY_AUTH_RESULT` 定数がどのように使われるかを示しています。

このサンプルコードは、PHPのストリーム機能において、カスタムフィルターの作成・登録と、STREAM_NOTIFY_AUTH_RESULT定数を含むストリーム通知イベントの処理方法をシステムエンジニアを目指す初心者向けに解説しています。STREAM_NOTIFY_AUTH_RESULTは、ストリーム操作における認証結果を示す通知コードとして使用される定数であり、それ自体に引数や戻り値はありません。

まず、php_user_filterを継承したMyUppercaseFilterクラスで、ストリームに流れるデータを全て大文字に変換するカスタムフィルターを定義しています。このフィルターはstream_filter_register関数を使って「my.uppercase」という名前でシステムに登録されます。次に、ストリーム操作中に発生する様々なイベント（通知コード、深刻度、メッセージなど）を受け取るための通知コールバック関数myNotificationCallbackを作成しています。この関数内でSTREAM_NOTIFY_AUTH_RESULTが通知コードとして渡された場合の処理例が示されており、認証結果の通知があったことを認識できます。

stream_context_createにより、この通知コールバックが設定されたストリームコンテキストを作成し、fopenでphp://memoryストリームを開く際に適用しています。開いたストリームには、stream_filter_appendを使って先ほど登録した大文字変換フィルターが適用され、ストリームへの書き込み時にデータが自動的に変換されます。コードは、変換前のデータを書き込み、フィルターを通して大文字に変換された後のデータを読み出す一連の流れを示しています。STREAM_NOTIFY_AUTH_RESULTは通常、FTPやSSHなどの認証を伴うプロトコルで利用されるため、この例のローカルストリームでは直接発生しませんが、通知の仕組みと定数の用途を理解する上で重要な概念です。