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

Copy
1<?php
2
3/**
4 * cURLリクエストを行い、様々なタイムアウトオプションを設定するサンプル関数です。
5 * CURLOPT_CONNECTTIMEOUT (接続タイムアウト)、
6 * CURLOPT_SERVER_RESPONSE_TIMEOUT (サーバー応答タイムアウト)、
7 * CURLOPT_TIMEOUT (全体のタイムアウト) の使用例を示します。
8 *
9 * @param string $url リクエスト先のURL
10 * @param int $connectTimeout 接続確立までのタイムアウト秒数
11 * @param int $serverResponseTimeout 接続後、サーバーからの最初の応答 (HTTPヘッダ) までのタイムアウト秒数
12 * @param int $overallTimeout リクエスト全体 (接続、応答、データ転送を含む) のタイムアウト秒数
13 * @return string|false 取得したデータ、またはエラーの場合はfalse
14 */
15function fetchDataWithTimeouts(string $url, int $connectTimeout, int $serverResponseTimeout, int $overallTimeout)
16{
17    // cURLセッションを初期化
18    $ch = curl_init();
19
20    // cURLオプションを設定
21    curl_setopt($ch, CURLOPT_URL, $url);
22    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 結果を文字列として取得
23    curl_setopt($ch, CURLOPT_HEADER, false);        // レスポンスヘッダを含めない
24
25    // 接続確立のタイムアウトを設定
26    // 例: DNS解決からTCP接続確立までの最大時間を設定します。
27    // この時間を過ぎると、サーバーに接続できない場合にタイムアウトします。
28    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $connectTimeout);
29
30    // サーバーからの最初の応答 (HTTPヘッダ) 待ちのタイムアウトを設定 (PHP 7.1.0以降)
31    // 接続が確立した後、サーバーがステータスラインとHTTPヘッダを送信するまでの最大時間を設定します。
32    // このオプションは、サーバーが高負荷で応答が遅い場合に有効です。
33    // 注意: httpbin.org/delay/X のようなURLは、ヘッダはすぐに返しますがボディの転送を遅らせます。
34    // このオプションは「最初の応答」に適用されるため、その種のURLではタイムアウトしない可能性があります。
35    curl_setopt($ch, CURLOPT_SERVER_RESPONSE_TIMEOUT, $serverResponseTimeout);
36
37    // 全体のタイムアウトを設定（接続、応答、データ転送のすべてを含む）
38    // リクエストの開始から完了 (データ転送含む) までの最大時間を設定します。
39    // この時間を過ぎると、全体の処理が完了しなくてもタイムアウトします。
40    curl_setopt($ch, CURLOPT_TIMEOUT, $overallTimeout);
41
42    // SSL証明書の検証をスキップ (開発環境での一時的な措置として使用されることがありますが、
43    // 本番環境ではセキュリティリスクがあるため非推奨です。通常は削除してください。)
44    // curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
45    // curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
46
47    echo "  >> URL: {$url}, 接続T: {$connectTimeout}s, 応答T: {$serverResponseTimeout}s, 全体T: {$overallTimeout}s" . PHP_EOL;
48
49    // cURLセッションを実行
50    $response = curl_exec($ch);
51
52    // エラーチェック
53    if (curl_errno($ch)) {
54        echo '  !! cURLエラー: ' . curl_error($ch) . ' (エラーコード: ' . curl_errno($ch) . ')' . PHP_EOL;
55        $response = false;
56    } else {
57        echo '  OK: レスポンスを受信しました。' . PHP_EOL;
58    }
59
60    // cURLセッションを閉じる
61    curl_close($ch);
62
63    return $response;
64}
65
66// === 使用例 ===
67
68// ケース1: 通常のリクエスト (高速な応答)
69echo "--- ケース1: 通常のリクエスト (高速な応答) ---" . PHP_EOL;
70$result1 = fetchDataWithTimeouts('https://httpbin.org/get', 5, 5, 10);
71if ($result1 !== false) {
72    echo "  成功: レスポンスの最初の100バイト:\n" . substr($result1, 0, 100) . "..." . PHP_EOL;
73}
74echo PHP_EOL;
75
76// ケース2: サーバー応答タイムアウトのテスト (実例ではサーバ側でのヘッダ遅延が必要)
77// ここでは httpbin.org/delay/5 を使用します。このURLはヘッダをすぐに返し、ボディの転送を5秒遅延させます。
78// CURLOPT_SERVER_RESPONSE_TIMEOUT は「最初の応答 (ヘッダ)」に適用されるため、このURLではこのオプションによるタイムアウトは発生しません。
79// もしサーバーが応答ヘッダ自体を遅延させる場合は有効です。
80echo "--- ケース2: CURLOPT_SERVER_RESPONSE_TIMEOUT の挙動 (ヘッダ遅延のサーバーを想定) ---" . PHP_EOL;
81echo "  ※注意: 'https://httpbin.org/delay/5' はヘッダをすぐに返すため、この設定でサーバー応答タイムアウトは発生しません。" . PHP_EOL;
82echo "  このタイムアウトは、サーバーが高負荷で最初のヘッダすら返せない場合に効果を発揮します。" . PHP_EOL;
83$result2 = fetchDataWithTimeouts('https://httpbin.org/delay/5', 5, 2, 10); // 応答待ちを2秒に設定
84if ($result2 === false) {
85    echo "  結果: タイムアウトまたはエラーが発生しました。" . PHP_EOL;
86} else {
87    echo "  成功: レスポンスの最初の100バイト:\n" . substr($result2, 0, 100) . "..." . PHP_EOL;
88}
89echo PHP_EOL;
90
91// ケース3: 全体のタイムアウトが短すぎる場合 (CURLOPT_TIMEOUTの効果)
92// httpbin.org/delay/5 は5秒遅延するので、全体のタイムアウトを3秒にするとタイムアウトします。
93echo "--- ケース3: 全体のタイムアウトが短すぎる場合 ---" . PHP_EOL;
94$result3 = fetchDataWithTimeouts('https://httpbin.org/delay/5', 5, 5, 3); // 全体を3秒に設定
95if ($result3 === false) {
96    echo "  結果: タイムアウトが発生しました（CURLOPT_TIMEOUTによる）。" . PHP_EOL;
97} else {
98    echo "  成功: レスポンスを受信しました。" . PHP_EOL;
99}
100echo PHP_EOL;
101
102// ケース4: 存在しないドメインへの接続試行 (CURLOPT_CONNECTTIMEOUTの効果)
103echo "--- ケース4: 存在しないドメインへの接続試行 ---" . PHP_EOL;
104$nonExistentUrl = 'http://nonexistent.example.com';
105$result4 = fetchDataWithTimeouts($nonExistentUrl, 2, 5, 10); // 接続待ちを2秒に設定
106if ($result4 === false) {
107    echo "  結果: 接続タイムアウトまたは名前解決エラーが発生しました（CURLOPT_CONNECTTIMEOUTによる）。" . PHP_EOL;
108} else {
109    echo "  成功: レスポンスを受信しました。" . PHP_EOL;
110}
111echo PHP_EOL;
112
113?>

CURLOPT_SERVER_RESPONSE_TIMEOUTは、PHPのcURL拡張機能で使用される定数で、Webサーバーとの通信において、接続が確立された後にサーバーから最初の応答（HTTPヘッダ）を受け取るまでの最大待ち時間を秒単位で設定します。

この定数をcurl_setopt()関数と組み合わせて使用することで、サーバーが高負荷であるなどの理由で、リクエストを受け付けたもののすぐにヘッダを返せない状況において、処理が長時間停止するのを防ぐことができます。サンプルコードでは、この定数を用いてfetchDataWithTimeouts関数内で、指定した$serverResponseTimeout秒が経過してもサーバーから最初の応答がない場合にタイムアウトを発生させています。

類似のタイムアウト設定として、CURLOPT_CONNECTTIMEOUTはサーバーへの接続確立までの時間を制限し、CURLOPT_TIMEOUTは接続からデータ転送完了までのリクエスト全体にかかる時間を制限します。CURLOPT_SERVER_RESPONSE_TIMEOUTは、これらの中間に位置する「接続後、最初のヘッダが届くまで」という特定のフェーズを制御する点が特徴です。

例えば、サンプルコードのケース2のように、サーバーはすぐにヘッダを返すものの、データ転送に時間がかかるURLでは、このオプションではなくCURLOPT_TIMEOUTが効果を発揮します。適切なタイムアウト設定を行うことで、ネットワークの遅延やサーバー側の問題からシステムを守り、安定した運用に役立ちます。

Copy
1<?php
2
3/**
4 * CURLを使って指定されたURLにHTTP GETリクエストを送信し、
5 * 接続および操作のタイムアウトを設定する関数です。
6 *
7 * システムエンジニアを目指す初心者向けに、外部サービスへの接続時に発生しうる
8 * 応答遅延や接続不可に対応するための基本的なタイムアウト設定を学ぶことを目的としています。
9 *
10 * @param string $url リクエストを送信するターゲットURL。
11 * @param int $connectTimeout 接続が確立されるまでの最大待機時間（秒）。
12 *                            この時間を超えると、接続試行は中止されます。
13 * @param int $requestTimeout CURL操作全体の最大待機時間（秒）。
14 *                            接続からデータの送受信まで、操作全体がこの時間を超えると中止されます。
15 * @return string|false リクエストが成功した場合は応答ボディの文字列、
16 *                      エラーが発生した（タイムアウトを含む）場合はfalseを返します。
17 */
18function fetchUrlWithTimeouts(string $url, int $connectTimeout = 5, int $requestTimeout = 10)
19{
20    // 1. CURLセッションを初期化します。
21    //    CURL操作を行うためのハンドルを作成します。
22    $ch = curl_init();
23
24    // 初期化に失敗した場合はエラーメッセージを出力し、処理を終了します。
25    if ($ch === false) {
26        echo "CURLセッションの初期化に失敗しました。\n";
27        return false;
28    }
29
30    // 2. CURLオプションを設定します。
31    //    curl_setopt_array() を使うと、複数のオプションを一度に設定できます。
32    curl_setopt_array($ch, [
33        CURLOPT_URL            => $url,                           // ターゲットURLを設定します。
34        CURLOPT_RETURNTRANSFER => true,                           // 応答を文字列として返すように設定します。
35                                                                  // これがないと、応答は直接出力されます。
36        CURLOPT_HEADER         => false,                          // 応答ヘッダーを結果に含めないように設定します。
37        CURLOPT_FAILONERROR    => true,                           // HTTPステータスコードが400以上の場合にCURLエラーと見なします。
38        CURLOPT_CONNECTTIMEOUT => $connectTimeout,                // 接続確立までのタイムアウト時間（秒）を設定します。
39                                                                  // キーワード「curlopt_connecttimeout」に関連。
40        CURLOPT_TIMEOUT        => $requestTimeout,                // CURL操作全体のタイムアウト時間（秒）を設定します。
41                                                                  // 接続、応答の受信、ダウンロード全体が含まれます。
42
43        // PHP 8.2 以降で利用可能なオプション:
44        // CURLOPT_SERVER_RESPONSE_TIMEOUT_MS は、サーバーからの最初の応答を待つ最大時間をミリ秒で設定します。
45        // リファレンスの「CURLOPT_SERVER_RESPONSE_TIMEOUT」は、この概念を指しますが、
46        // PHP 8.0 のCURL拡張には、このミリ秒単位の定数は存在せず、
47        // PHP 8.2 で CURLOPT_SERVER_RESPONSE_TIMEOUT_MS として導入されました。
48        // 現在のPHP 8系（例: 8.0, 8.1）では、CURLOPT_TIMEOUT が操作全体のタイムアウトを制御します。
49        // PHP 8.2 以降をご利用の場合は、以下のように設定することで、
50        // より詳細なタイムアウト制御が可能になります。
51        // if (defined('CURLOPT_SERVER_RESPONSE_TIMEOUT_MS')) {
52        //     curl_setopt($ch, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, 2000); // サーバー応答まで2秒待機
53        // }
54    ]);
55
56    // 3. CURLリクエストを実行します。
57    $response = curl_exec($ch);
58
59    // 4. エラーハンドリングと結果の処理を行います。
60    if (curl_errno($ch)) {
61        // CURLエラーが発生した場合、エラーメッセージとコードを取得して出力します。
62        $errorMsg = curl_error($ch);
63        $errorCode = curl_errno($ch);
64        echo "CURLエラーが発生しました (コード: {$errorCode}): {$errorMsg}\n";
65        $response = false; // エラー時はfalseを返す
66    } else {
67        // リクエストが成功した場合、HTTPステータスコードを取得して出力します。
68        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
69        echo "HTTPステータスコード: {$httpCode}\n";
70        echo "URLへのアクセスに成功しました。\n";
71    }
72
73    // 5. CURLセッションを閉じ、リソースを解放します。
74    curl_close($ch);
75
76    return $response;
77}
78
79// -----------------------------------------------------------------------------
80// サンプルコードの実行例
81// -----------------------------------------------------------------------------
82
83// 試したいURLを設定します。
84// 例1: 正常に動作するURL
85$targetUrl = 'https://www.example.com/';
86
87// 例2: 存在しないポートやアドレスで、接続タイムアウトを試すURL
88// $targetUrl = 'http://localhost:9999/';
89
90// 例3: 意図的に応答を遅延させるサービスを利用し、全体タイムアウトを試すURL
91//      この例では、https://deelay.me/ が5秒遅延させた後にgoogle.comの内容を返します。
92//      requestTimeout を3秒などと短くするとタイムアウトが発生します。
93// $targetUrl = 'https://deelay.me/5000?url=https://www.google.com';
94
95
96echo "ターゲットURL: {$targetUrl}\n";
97echo "接続タイムアウト: 3秒, 全体タイムアウト: 5秒 でリクエストを送信します。\n";
98
99// fetchUrlWithTimeouts 関数を呼び出し、タイムアウトを設定してリクエストを実行します。
100$responseData = fetchUrlWithTimeouts($targetUrl, 3, 5);
101
102// 結果を表示します。
103echo "\n------------------------------------------------\n";
104if ($responseData !== false) {
105    echo "リクエスト結果: 成功\n";
106    echo "応答ボディの抜粋 (最初の200文字):\n";
107    // 応答が長すぎる場合を考慮し、最初の200文字のみ表示します。
108    echo mb_substr($responseData, 0, 200) . "...\n";
109} else {
110    echo "リクエスト結果: 失敗またはタイムアウト\n";
111    echo "エラーメッセージを確認してください。\n";
112}
113echo "------------------------------------------------\n";
114
115?>

このサンプルコードは、PHPのCURL拡張機能を用いて指定されたURLへHTTP GETリクエストを送信し、外部サービスとの通信におけるタイムアウトを制御する方法を示します。システムエンジニアにとって、外部連携時の応答遅延や接続障害に対応するための信頼性確保は非常に重要です。

fetchUrlWithTimeouts関数は、ターゲットURL、接続確立までの最大待機時間（$connectTimeout）、そしてCURL操作全体の最大待機時間（$requestTimeout）を引数として受け取ります。成功時にはサーバーからの応答ボディを文字列で返し、エラーやタイムアウトが発生した場合はfalseを返します。

コード内部では、まずcurl_init()でCURLセッションを初期化し、curl_setopt_array()で各種オプションを設定します。特に重要なのは、キーワードでもあるCURLOPT_CONNECTTIMEOUTと、CURLOPT_TIMEOUTです。CURLOPT_CONNECTTIMEOUTは、リモートサーバーへの接続が確立されるまでの時間を秒単位で指定します。CURLOPT_TIMEOUTは、接続からデータの送受信まで、CURL操作全体の最大待機時間を秒単位で設定します。

リファレンスにあるCURLOPT_SERVER_RESPONSE_TIMEOUTは、サーバーからの最初の応答を待つ時間を示す概念を指しますが、PHP 8.0のCURL拡張では、この目的のために直接利用できる定数は提供されていません。現在のPHP 8系では、CURLOPT_TIMEOUTが操作全体のタイムアウトとしてこの役割の一部をカバーします。

リクエスト実行後、curl_errno()でエラーの有無を確認し、タイムアウトを含む問題が発生した場合は適切なエラーメッセージを出力します。最後にcurl_close()でリソースを解放することで、外部サービスとの堅牢な通信処理を構築できます。