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

Copy
1<?php
2
3/**
4 * ストリーム操作の通知を受け取るコールバック関数。
5 * stream_context_create() の 'notification' オプションで設定されます。
6 *
7 * @param int $notification_code 通知イベントのコード。STREAM_NOTIFY_* 定数の一つ。
8 * @param int $severity イベントの重要度。
9 * @param string $message イベントに関するメッセージ。
10 * @param int $message_code イベント固有のコード。
11 * @param int $bytes_transferred 現在までに転送されたバイト数。
12 * @param int $bytes_max 転送される予定の総バイト数。
13 */
14function streamNotificationCallback(
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_PROGRESS は、ストリーム操作（例えばファイル転送）の進行状況を示す定数です。
23    // このコールバック内で、現在の転送バイト数と最大バイト数を用いて進捗状況を監視できます。
24    if ($notification_code === STREAM_NOTIFY_PROGRESS) {
25        // bytes_maxが0の場合は、総サイズが不明であることを意味します。
26        // 小さなファイルや即座に完了する操作では、進行状況が一度に報告されることがあります。
27        if ($bytes_max > 0) {
28            $progress = round(($bytes_transferred / $bytes_max) * 100);
29            echo "Progress: {$progress}% ({$bytes_transferred}/{$bytes_max} bytes)\n";
30        } else {
31            // 総バイト数が不明な場合は、転送されたバイト数のみ表示
32            echo "Transferred: {$bytes_transferred} bytes\n";
33        }
34    }
35    // その他の通知イベントはここでは省略（例: STREAM_NOTIFY_FILE_SIZE_ISなど）
36}
37
38/**
39 * ストリーム書き込みバッファの設定とストリーム進行通知の概念を示すサンプル関数。
40 *
41 * この関数は、PHPのストリーム操作において、stream_set_write_buffer 関数で書き込みバッファリングを制御し、
42 * STREAM_NOTIFY_PROGRESS 定数を含む通知コールバックで操作の進行状況を監視する方法を説明します。
43 */
44function demonstrateStreamBufferingAndNotification(): void
45{
46    $filename = 'buffered_output.txt';
47    // stream_set_write_buffer の動作を確認しやすいように、大きめのデータを用意します（約2MB）。
48    $dataToWrite = str_repeat('A', 1024 * 1024 * 2);
49
50    echo "--- stream_set_write_buffer の使用例 ---\n";
51
52    // ファイルを書き込みモードで開きます。
53    $stream = fopen($filename, 'w');
54
55    if ($stream === false) {
56        echo "エラー: ファイル '{$filename}' を開けませんでした。\n";
57        return;
58    }
59
60    echo "ファイル '{$filename}' を開きました。\n";
61
62    // stream_set_write_buffer を使用して書き込みバッファリングポリシーを設定します。
63    // 第2引数に 0 を指定すると、バッファリングが無効になり、各 fwrite() コールが即座に
64    // 低レベルのシステムコールを発行しようとします。これにより、書き込み頻度が増し、
65    // パフォーマンスが低下する可能性があります。
66    // 通常は、システムの最適なバッファサイズ（デフォルト）を使用するか、
67    // 特定の要件に応じて適切なサイズ（例: 8192バイト）を設定します。
68    $bufferSize = 0; // デモンストレーションのためにバッファリングを無効にする設定
69
70    if (stream_set_write_buffer($stream, $bufferSize) === -1) {
71        echo "警告: 書き込みバッファの設定に失敗しました。\n";
72    } else {
73        echo "書き込みバッファを {$bufferSize} バイトに設定しました (0はバッファリングなしを意味します)。\n";
74    }
75
76    echo "ファイルにデータを書き込み中 (約 " . round(strlen($dataToWrite) / 1024 / 1024, 2) . " MB)...\n";
77    fwrite($stream, $dataToWrite);
78    echo "書き込みが完了しました。\n";
79
80    // ストリームを閉じます。これにより、バッファに残ったデータがフラッシュされます（バッファリングを無効にしている場合はすぐにフラッシュされます）。
81    fclose($stream);
82    echo "ファイル '{$filename}' を閉じました。\n";
83
84    // 生成されたファイルを削除してクリーンアップ
85    if (file_exists($filename)) {
86        unlink($filename);
87        echo "ファイル '{$filename}' を削除しました。\n";
88    }
89
90    echo "\n--- STREAM_NOTIFY_PROGRESS の概念説明と使用例 ---\n";
91
92    // STREAM_NOTIFY_PROGRESS は、ストリーム操作（特に大きなファイルのコピーやダウンロードなど）の
93    // 進行状況を通知するために使用される定数です。
94    // これを実際に使用するには、stream_context_create() 関数で通知コールバックを設定する必要があります。
95
96    // 例：リモートファイルのダウンロード時に進行状況を表示する
97    // この例は stream_set_write_buffer とは直接関係ありませんが、
98    // ストリーム操作の通知という文脈で STREAM_NOTIFY_PROGRESS の用途を示します。
99    $remoteFile = 'https://www.php.net/images/php-logo.svg'; // PHPロゴの小さな画像ファイル
100    $localCopy = 'php-logo.svg';
101
102    echo "リモートファイル '{$remoteFile}' のダウンロードを開始します。\n";
103
104    // 通知コールバックを設定したストリームコンテキストを作成
105    $context = stream_context_create([
106        'http' => [
107            'notification' => 'streamNotificationCallback',
108        ]
109    ]);
110
111    // file_put_contents 関数でリモートファイルをダウンロードし、作成したストリームコンテキストを適用します。
112    // streamNotificationCallback がダウンロードの進行中に定期的に呼び出され、
113    // STREAM_NOTIFY_PROGRESS イベントが処理される可能性があります。
114    // (ただし、ファイルが非常に小さい場合、進行状況通知が一度に完了することがあります。)
115    // @ を付けて、ダウンロード失敗時のPHPの警告メッセージを抑制しています。
116    $bytesDownloaded = @file_put_contents($localCopy, fopen($remoteFile, 'r', false, $context));
117
118    if ($bytesDownloaded !== false) {
119        echo "ダウンロード完了: '{$localCopy}' ({$bytesDownloaded} バイト)。\n";
120        // ダウンロードしたファイルを削除してクリーンアップ
121        if (file_exists($localCopy)) {
122            unlink($localCopy);
123            echo "ファイル '{$localCopy}' を削除しました。\n";
124        }
125    } else {
126        // ダウンロードが失敗した場合のエラーメッセージ
127        echo "エラー: リモートファイル '{$remoteFile}' のダウンロードに失敗しました。\n";
128        echo "URLが正しいか、またはネットワーク接続を確認してください。\n";
129    }
130
131    echo "\nデモンストレーションを終了します。\n";
132}
133
134// サンプル関数の実行
135demonstrateStreamBufferingAndNotification();

このサンプルコードは、PHPのストリーム操作におけるバッファリング制御と進行状況通知の仕組みを解説しています。

STREAM_NOTIFY_PROGRESSは、ファイル転送などのストリーム操作の進行状況を示す整数定数です。この定数は、stream_context_create()で設定する通知コールバック関数内で、現在の転送バイト数や最大バイト数といった詳細な進捗情報を受け取る際に利用されます。サンプル中のstreamNotificationCallback関数は、この定数が示すイベントを受け取ると、転送されたバイト数と総バイト数をもとに進捗率を計算し表示する役割を担っています。

一方、stream_set_write_buffer関数は、ファイルなどのストリームへの書き込み動作におけるバッファリングのサイズを設定します。第一引数にストリームリソース、第二引数にバッファサイズ（0を指定するとバッファリングが無効化されます）を指定します。この関数は、設定に成功すると0を、失敗すると-1を整数で返します。バッファリングを無効にすると、小さな書き込みが頻繁に発生する場合にパフォーマンスが低下する可能性があります。

このコードでは、まずstream_set_write_bufferを用いて書き込みバッファを制御しながらファイルにデータを書き込む例を示し、次にSTREAM_NOTIFY_PROGRESS定数を通知コールバックとして設定することで、リモートファイルのダウンロード進行状況を監視する方法を説明しています。これにより、効率的なストリーム処理と操作の可視化を学ぶことができます。

Copy
1<?php
2
3/**
4 * PHP ストリームの異なる側面を示すサンプルコード。
5 * stream_select を用いたノンブロッキングI/Oと、
6 * STREAM_NOTIFY_PROGRESS を用いたストリーム進捗通知を実演します。
7 *
8 * システムエンジニアを目指す初心者向けに、ストリーム操作の基本概念を理解しやすくします。
9 */
10function demonstrateStreamOperations(): void
11{
12    echo "--- stream_select を用いたノンブロッキングI/Oのデモンストレーション ---\n";
13
14    // ソケットサーバーの作成 (簡略化された例)
15    // 実際にはループで複数の接続を処理します
16    $serverSocket = stream_socket_server("tcp://127.0.0.1:8000", $errno, $errstr);
17    if (!$serverSocket) {
18        echo "エラー: サーバーソケットの作成に失敗しました - $errstr ($errno)\n";
19        return;
20    }
21    // ソケットをノンブロッキングモードに設定
22    // これにより、stream_select がタイムアウト期間中に他の処理を実行できるようになります
23    stream_set_blocking($serverSocket, 0);
24
25    echo "サーバーが tcp://127.0.0.1:8000 で起動しました。\n";
26    echo "1秒間接続を待ちます... (クライアント接続なしの場合、タイムアウトします)\n";
27
28    // 読み込み準備ができているかを監視するソケットの配列
29    $readSockets = [$serverSocket];
30    $writeSockets = null; // 書き込み準備ができているかを監視するソケット
31    $exceptSockets = null; // 例外が発生したかを監視するソケット
32    $timeout = 1; // stream_select のタイムアウトを1秒に設定
33
34    // stream_select でソケットイベントを監視
35    // 監視対象のソケットにイベントがない場合、指定されたタイムアウト期間だけ待機します
36    $numChangedSockets = stream_select($readSockets, $writeSockets, $exceptSockets, $timeout);
37
38    if ($numChangedSockets === false) {
39        echo "stream_select の実行中にエラーが発生しました。\n";
40    } elseif ($numChangedSockets > 0) {
41        // イベントが発生した場合
42        // ここではシンプルに、サーバーソケットでイベントがあったことを示します
43        // 実際には $readSockets をループして、どのソケットでイベントがあったかを判別し、処理を行います
44        echo "ソケットにイベントが発生しました。クライアント接続が試みられた可能性があります。\n";
45    } else {
46        // タイムアウト時間内にイベントが発生しなかった場合
47        echo "タイムアウト内にソケットイベントは発生しませんでした。\n";
48    }
49
50    // サーバーソケットを閉じます
51    fclose($serverSocket);
52    echo "サーバーソケットを閉じました。\n\n";
53
54
55    echo "--- STREAM_NOTIFY_PROGRESS を用いたストリーム進捗通知のデモンストレーション ---\n";
56
57    /**
58     * ストリーム通知コールバック関数。
59     * stream_context_create で設定され、ストリーム操作中に様々なイベントが発生したときに呼び出されます。
60     *
61     * @param int    $notificationCode   通知コード (例: STREAM_NOTIFY_PROGRESS)
62     * @param int    $severity           通知の重要度
63     * @param string $message            通知メッセージ
64     * @param int    $messageCode        メッセージコード
65     * @param int    $bytesTransferred   転送されたバイト数
66     * @param int    $bytesMax           合計バイト数 (利用可能な場合)
67     */
68    $notificationCallback = function (
69        int $notificationCode,
70        int $severity,
71        string $message,
72        int $messageCode,
73        int $bytesTransferred,
74        int $bytesMax
75    ): void {
76        // STREAM_NOTIFY_PROGRESS は、データ転送の進捗状況を示すイベントです
77        if ($notificationCode === STREAM_NOTIFY_PROGRESS) {
78            if ($bytesMax > 0) {
79                $progress = ($bytesTransferred / $bytesMax) * 100;
80                // 進捗状況を小数点以下2桁まで表示
81                echo sprintf("  進捗: %.2f%% (%d / %d バイト)\n", $progress, $bytesTransferred, $bytesMax);
82            } else {
83                echo sprintf("  転送中: %d バイト\n", $bytesTransferred);
84            }
85        }
86        // 他の通知コードも処理できます
87        elseif ($notificationCode === STREAM_NOTIFY_FILE_SIZE_IS) {
88            echo "  ファイルサイズ確定: " . $bytesMax . " バイト\n";
89        } elseif ($notificationCode === STREAM_NOTIFY_COMPLETED) {
90            echo "  ダウンロード完了！\n";
91        } elseif ($notificationCode === STREAM_NOTIFY_FAILURE) {
92            echo "  ダウンロード失敗: " . $message . "\n";
93        }
94    };
95
96    // ストリームコンテキストの作成
97    // ここで上記の通知コールバック関数を設定します。
98    // このコンテキストは、ファイル操作関数 (例: file_get_contents, fopen) に渡すことができます。
99    $context = stream_context_create([], [
100        'notification' => $notificationCallback,
101    ]);
102
103    // 進捗通知を伴う外部リソースの取得を試みます
104    // PHPロゴのSVGファイルなど、比較的小さなファイルを指定することで素早く結果を確認できます
105    $urlToDownload = 'https://www.php.net/images/logos/php-logo.svg';
106    echo "外部ファイル ($urlToDownload) のダウンロードを開始します...\n";
107
108    // file_get_contents を使用してファイルをダウンロード
109    // 第三引数に作成したコンテキストを渡すことで、通知コールバックが有効になります
110    try {
111        $contents = file_get_contents($urlToDownload, false, $context);
112        if ($contents === false) {
113            echo "エラー: '$urlToDownload' の取得に失敗しました。\n";
114        } else {
115            echo "外部ファイルのダウンロードが完了しました。取得したバイト数: " . strlen($contents) . "\n";
116        }
117    } catch (Throwable $e) { // PHP 7+ でのエラーと例外を捕捉
118        echo "エラーが発生しました: " . $e->getMessage() . "\n";
119    }
120}
121
122// 関数を実行してデモンストレーションを開始
123demonstrateStreamOperations();

このPHPサンプルコードは、システムエンジニアを目指す初心者向けに、ストリーム操作の二つの重要な側面を説明します。一つはノンブロッキングI/Oを実現するstream_select関数の利用法、もう一つはストリームの進捗状況を通知するSTREAM_NOTIFY_PROGRESS定数の使い方です。

stream_select関数は、複数のストリーム（例えばネットワークソケット）の状態を効率的に監視するための関数です。プログラムが特定のストリームからの読み書きを待つ際に、その操作が完了するまで他の処理がブロックされる（停止する）のを防ぎます。この関数は、引数で監視対象の読み込み・書き込み・例外ソケットのリストとタイムアウト時間を指定し、指定された時間内にイベントが発生したソケットの数を整数値で返します。サンプルコードでは、サーバーソケットがクライアント接続を待つ際に、タイムアウトを設けることで、接続がない場合でもプログラムが指定時間後に次の処理に進める様子を示しています。

一方、STREAM_NOTIFY_PROGRESSは、ストリーム操作、例えばインターネット上のファイルをダウンロードする際などに、データ転送の進捗状況を通知するために使われる整数値の定数です。この定数自体に引数はありません。利用する際は、stream_context_create関数でストリームコンテキストを作成し、その中に通知用のコールバック関数を設定します。ファイルダウンロードなどのストリーム操作中に、設定されたコールバック関数が様々なイベントコードとともに呼び出され、この定数を用いて現在のイベントが「進捗通知」であることを識別します。サンプルでは、外部ファイルのダウンロード中に、転送されたバイト数と合計バイト数から進捗率を計算し、画面に表示することで、リアルタイムな進捗状況を可視化しています。