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

Copy
1<?php
2
3/**
4 * CURLOPT_TIMEOUT_MS オプションを使用してcURLリクエストのタイムアウトを設定する方法を示す関数。
5 *
6 * システムエンジニアを目指す初心者が、ネットワーク通信の安定性と信頼性を確保するために
7 * タイムアウト設定がいかに重要かを理解できるように作成されています。
8 */
9function demonstrateCurlTimeoutMs(): void
10{
11    // リクエストを送信するURLを設定します。
12    // この例では一般的なウェブサイトを使用しますが、
13    // 実際にタイムアウトが発生するシナリオを試したい場合は、
14    // 応答が非常に遅いサーバーや、存在しないポート番号などを指定すると良いでしょう。
15    $url = 'https://example.com';
16
17    // cURLセッションを初期化します。
18    // これがネットワークリクエストを開始するための最初の手順です。
19    $ch = curl_init();
20
21    // cURLセッションの初期化が成功したかを確認します。
22    if ($ch === false) {
23        echo "エラー: cURLセッションの初期化に失敗しました。\n";
24        return;
25    }
26
27    // cURLオプションを設定します。
28    // curl_setopt() 関数を使って、リクエストの挙動を細かく制御できます。
29
30    // CURLOPT_URL: リクエストを送信するターゲットURLを設定します。
31    curl_setopt($ch, CURLOPT_URL, $url);
32
33    // CURLOPT_RETURNTRANSFER: curl_exec() が結果を直接出力するのではなく、
34    // 文字列として返すように設定します。これにより、プログラム内でレスポンスを処理できます。
35    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
36
37    // ★CURLOPT_TIMEOUT_MS の設定★
38    // CURLOPT_TIMEOUT_MS は、cURL操作全体が完了するまでの最大時間をミリ秒単位で設定します。
39    // これにより、ネットワークの問題やサーバーの応答遅延によってプログラムが
40    // 無限に待機してしまうのを防ぎ、アプリケーションの応答性を保つことができます。
41    // ここでは、2000ミリ秒 (2秒) をタイムアウトとして設定します。
42    $timeout_ms = 2000;
43    curl_setopt($ch, CURLOPT_TIMEOUT_MS, $timeout_ms);
44
45    echo "URL: {$url} へのリクエストを {$timeout_ms}ms (" . ($timeout_ms / 1000) . "秒) のタイムアウトで実行します。\n";
46    echo "この時間内に応答がない場合、リクエストはタイムアウトします。\n";
47
48    // 設定したcURLリクエストを実行し、結果を取得します。
49    $response = curl_exec($ch);
50
51    // cURLリクエストの実行中にエラーが発生したかどうかを確認します。
52    if (curl_errno($ch)) {
53        // エラーコードとエラーメッセージを取得します。
54        $error_code = curl_errno($ch);
55        $error_message = curl_error($ch);
56        echo "エラー: cURLリクエストの実行中に問題が発生しました。\n";
57        echo "  エラーコード: {$error_code}\n";
58        echo "  エラーメッセージ: {$error_message}\n";
59
60        // タイムアウトエラーの場合、特定のエラーコード (28: CURLE_OPERATION_TIMEDOUT) が返されます。
61        if ($error_code === CURLE_OPERATION_TIMEDOUT) {
62            echo "  補足: 設定された {$timeout_ms}ms 以内にサーバーからの応答がなかったため、リクエストはタイムアウトしました。\n";
63        }
64    } else {
65        // リクエストが成功した場合、HTTPステータスコードを取得します。
66        $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
67        echo "成功: HTTPステータスコード: {$http_code}\n";
68        // 取得したレスポンスの先頭部分を表示します。（長文の場合に備えて切り詰めます）
69        echo "レスポンスの先頭部分: " . substr((string)$response, 0, 200) . (strlen((string)$response) > 200 ? '...' : '') . "\n";
70    }
71
72    // cURLセッションを閉じ、使用したリソースを解放します。
73    // これは重要なクリーンアップ作業です。
74    curl_close($ch);
75}
76
77// 上記で定義した関数を実行し、CURLOPT_TIMEOUT_MS の動作を確認します。
78demonstrateCurlTimeoutMs();

このPHPサンプルコードは、cURL拡張機能を利用してネットワークリクエストを行う際に、CURLOPT_TIMEOUT_MSオプションを使って操作の最大実行時間をミリ秒単位で設定する方法を示しています。ネットワーク通信において、サーバーからの応答が遅い、または全くない場合にプログラムが長時間待機することを防ぎ、アプリケーションの応答性と信頼性を確保するために、タイムアウト設定は非常に重要です。

コードではまずcurl_init()でcURLセッションを初期化し、curl_setopt()関数を使用して様々なオプションを設定します。CURLOPT_URLでアクセス先のURLを指定し、CURLOPT_RETURNTRANSFERでcurl_exec()の実行結果を文字列として取得するよう設定します。そして、CURLOPT_TIMEOUT_MSに2000（2秒）という値を設定することで、cURL操作全体がこの時間内に完了しない場合に、リクエストが自動的に中断されエラーとして処理されるようにしています。

CURLOPT_TIMEOUT_MS自体は引数や戻り値を持たない定数ですが、curl_setopt()関数の第2引数としてこの定数を渡し、第3引数にタイムアウト時間をミリ秒単位の数値で指定することで、cURLの挙動を制御します。curl_setopt()は設定が成功すればtrueを、失敗すればfalseを返します。リクエストの実行はcurl_exec()で行われ、成功すれば応答内容が、失敗すればfalseが返され、curl_errno()やcurl_error()関数でエラーの詳細を確認できます。タイムアウトが発生した場合には、特定のエラーコード（28）が返されるため、その後のエラーハンドリングで適切に処理することが可能です。最後にcurl_close()でリソースを解放します。