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

Copy
1<?php
2
3/**
4 * 指定されたURLからコンテンツを取得し、cURL操作のタイムアウトエラーを処理します。
5 *
6 * @param string $url 取得するURL。
7 * @param int $timeout 接続と転送を含めた操作全体のタイムアウト秒数。
8 * @return string|false 成功した場合は取得したコンテンツ、失敗した場合はfalse。
9 */
10function fetchUrlWithTimeoutHandling(string $url, int $timeout = 5)
11{
12    // cURLハンドルの初期化
13    $ch = curl_init();
14
15    // cURLオプションの設定
16    curl_setopt($ch, CURLOPT_URL, $url);                // 取得するURLを設定
17    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);     // curl_exec()の戻り値を文字列として取得する
18    curl_setopt($ch, CURLOPT_TIMEOUT, $timeout);        // 接続とデータ転送を含めた操作全体のタイムアウトを設定（秒）
19
20    // cURLリクエストの実行
21    $response = curl_exec($ch);
22
23    // エラーチェック
24    if (curl_errno($ch)) {
25        $error_code = curl_errno($ch);
26        $error_message = curl_error($ch);
27
28        // キーワードである CURLE_OPERATION_TIMEDOUT エラーを特に処理する
29        if ($error_code === CURLE_OPERATION_TIMEDOUT) {
30            echo "エラー: cURL操作がタイムアウトしました。指定された時間 ({$timeout}秒) 内に応答がありませんでした。\n";
31            echo "URL: {$url}\n";
32            echo "詳細: {$error_message}\n";
33        } else {
34            // その他のcURLエラーの処理
35            echo "cURLエラーが発生しました。\n";
36            echo "エラーコード: {$error_code}\n";
37            echo "エラーメッセージ: {$error_message}\n";
38        }
39        curl_close($ch);
40        return false;
41    }
42
43    // cURLハンドルのクローズ
44    curl_close($ch);
45
46    echo "URL '{$url}' から正常にコンテンツを取得しました。\n";
47    return $response;
48}
49
50// --- サンプルコードの実行例 ---
51
52// 1. 意図的にタイムアウトを発生させやすいように、短いタイムアウトを設定
53//    非常に短いタイムアウト（例: 1秒）を設定し、応答に時間がかかる場合にタイムアウトを観察できます。
54//    ただし、ネットワーク状況やサーバーの応答速度によっては、タイムアウトしない可能性もあります。
55$testUrlShortTimeout = "http://example.com"; // 通常は高速に応答するサイト
56$shortTimeout = 1; // 1秒のタイムアウト
57
58echo "--- 短いタイムアウト ({$shortTimeout}秒) で {$testUrlShortTimeout} を試行 ---\n";
59$contentShort = fetchUrlWithTimeoutHandling($testUrlShortTimeout, $shortTimeout);
60if ($contentShort !== false) {
61    echo "取得コンテンツの一部:\n";
62    echo substr($contentShort, 0, 100) . "...\n";
63}
64echo "\n";
65
66// 2. 通常のタイムアウトで別のURLを試行
67$testUrlNormalTimeout = "https://www.google.com";
68$normalTimeout = 5; // 5秒のタイムアウト
69
70echo "--- 通常のタイムアウト ({$normalTimeout}秒) で {$testUrlNormalTimeout} を試行 ---\n";
71$contentNormal = fetchUrlWithTimeoutHandling($testUrlNormalTimeout, $normalTimeout);
72if ($contentNormal !== false) {
73    echo "取得コンテンツの一部:\n";
74    echo substr($contentNormal, 0, 100) . "...\n";
75}
76
77?>

このPHPサンプルコードは、cURL機能を利用してURLからWebコンテンツを取得し、その際に発生しうるタイムアウトエラーを適切に処理する方法を解説しています。

fetchUrlWithTimeoutHandling関数は、取得するURLを$urlとして、操作全体の最大待機時間（秒）を$timeoutとして受け取ります。関数内部では、curl_init()で通信セッションを開始し、curl_setopt()を使ってURLや戻り値形式、そして特に重要なCURLOPT_TIMEOUTでタイムアウト時間を設定します。この設定により、外部サーバーからの応答遅延などで処理が停止し続けることを防ぎます。

curl_exec()でHTTPリクエストを実行後、curl_errno()関数でエラーをチェックします。エラーコードがCURLE_OPERATION_TIMEDOUTと一致した場合、これはcURL操作が指定された時間内に完了しなかったことを意味し、専用のエラーメッセージを出力します。その他のcURLエラーも同様に処理されます。

関数は、コンテンツ取得に成功した場合はその内容を文字列として返し、失敗した場合はfalseを返します。最後にcurl_close()でcURLセッションを閉じ、使用したリソースを解放します。外部サービスと連携する堅牢なシステムを構築する上で、このようなタイムアウトを含むエラーハンドリングは非常に重要です。

Copy
1<?php
2
3/**
4 * cURLリクエストを指定回数リトライして実行します。
5 *
6 * この関数は、ネットワークエラー、タイムアウト、または特定のHTTPステータスコードが発生した場合に、
7 * 自動的にリクエストを再試行するメカニズムを提供します。
8 * 各リトライの間には指数関数的に増加する遅延が挿入され、サーバーへの負荷を軽減します。
9 *
10 * @param string $url リクエストを送信するターゲットURL。
11 * @param array $options cURLオプションの配列（例: `[CURLOPT_POST => true, CURLOPT_POSTFIELDS => 'data']`）。
12 * @param int $maxRetries 最大リトライ回数（0の場合はリトライなし、合計1回のみ試行）。
13 * @param int $initialDelayMs 初期のリトライ遅延時間（ミリ秒）。各リトライでこの値が2の冪乗で増加します。
14 * @return string|false 成功した場合はレスポンスボディ、全てのリトライが失敗した場合は `false`。
15 */
16function makeCurlRequestWithRetry(
17    string $url,
18    array $options = [],
19    int $maxRetries = 3,
20    int $initialDelayMs = 500
21): string|false {
22    $attempt = 0; // 現在の試行回数を追跡
23    $response = false; // レスポンスを初期化
24
25    // 最大試行回数（最初の試行 + 最大リトライ回数）までループ
26    while ($attempt <= $maxRetries) {
27        $ch = curl_init(); // cURLセッションを初期化
28
29        // 共通のcURLオプションを設定
30        curl_setopt($ch, CURLOPT_URL, $url);
31        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);    // レスポンスを文字列として返す
32        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);  // リダイレクトを追跡
33        curl_setopt($ch, CURLOPT_TIMEOUT, 15);            // リクエスト全体のタイムアウト（秒）
34        curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);      // 接続タイムアウト（秒）
35
36        // ユーザーが指定した追加のcURLオプションを適用
37        foreach ($options as $opt => $value) {
38            curl_setopt($ch, $opt, $value);
39        }
40
41        $response = curl_exec($ch); // cURLリクエストを実行
42        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); // HTTPステータスコードを取得
43        $curlErrno = curl_errno($ch); // cURLエラーコードを取得
44        $curlError = curl_error($ch); // cURLエラーメッセージを取得
45
46        curl_close($ch); // cURLセッションを閉じる
47
48        // 成功条件: cURLエラーがなく、HTTPステータスコードが200番台の場合
49        if ($curlErrno === CURLE_OK && $httpCode >= 200 && $httpCode < 300) {
50            return $response; // 成功したのでレスポンスを返す
51        }
52
53        // 失敗した場合のログ出力
54        error_log(sprintf(
55            "Attempt %d/%d failed for URL: %s. HTTP Code: %d, cURL Error: (%d) %s",
56            $attempt + 1,
57            $maxRetries + 1,
58            $url,
59            $httpCode,
60            $curlErrno,
61            $curlError
62        ));
63
64        // 最大リトライ回数に達したらループを終了
65        if ($attempt >= $maxRetries) {
66            error_log("Max retries exceeded for URL: " . $url . ". Giving up.");
67            break;
68        }
69
70        // 指数関数的なバックオフによる遅延を計算し、適用
71        // 遅延時間 = initialDelayMs * (2 ^ attempt) ミリ秒
72        $delayMs = $initialDelayMs * pow(2, $attempt);
73        usleep($delayMs * 1000); // usleepはマイクロ秒単位なので1000倍する
74
75        $attempt++; // 試行回数をインクリメント
76    }
77
78    return false; // 全ての試行が失敗した場合は false を返す
79}
80
81// --- サンプル使用例 ---
82
83// 1. 存在しないURLへのリクエスト (エラーとリトライの例)
84echo "--- 存在しないURLへのリクエスト (リトライを試行) ---\n";
85$nonExistentUrl = "https://example.com/nonexistent_resource_".uniqid();
86$result1 = makeCurlRequestWithRetry($nonExistentUrl, [], 2, 200); // 2回リトライ、初期遅延200ms
87
88if ($result1 !== false) {
89    echo "成功: レスポンスを受信しました。\n";
90    echo "内容 (最初の200文字):\n" . substr($result1, 0, 200) . "...\n\n";
91} else {
92    echo "失敗: 全てのリトライが失敗しました。\n\n";
93}
94
95
96// 2. 有効なURLへのリクエスト (成功の例)
97echo "--- 有効なURLへのリクエスト (リトライなし、1回で成功) ---\n";
98$validUrl = "https://api.github.com/zen"; // GitHub Zen API
99$githubOptions = [
100    CURLOPT_USERAGENT => 'PHP-Curl-Retry-Example/1.0', // GitHub APIはUser-Agentを要求
101    CURLOPT_HTTPHEADER => ['Accept: application/vnd.github.v3+json'],
102];
103$result2 = makeCurlRequestWithRetry($validUrl, $githubOptions, 0); // リトライなし (0回リトライ = 1回試行)
104
105if ($result2 !== false) {
106    echo "成功: GitHub Zen のメッセージを受信しました。\n";
107    echo "内容:\n" . $result2 . "\n\n";
108} else {
109    echo "失敗: GitHub Zen の取得に失敗しました。\n\n";
110}
111
112// 3. タイムアウトしやすいURLへのリクエスト (低タイムアウトとリトライの例)
113echo "--- タイムアウトしやすいURLへのリクエスト (低タイムアウト設定でリトライ) ---\n";
114// このURLは意図的に応答を遅延させることができ、タイムアウトのテストに適しています
115// 例: https://httpbin.org/delay/5 (5秒遅延)
116$slowUrl = "https://httpbin.org/delay/2"; // 2秒遅延するURL
117$slowOptions = [
118    CURLOPT_TIMEOUT => 1, // 各リクエストのタイムアウトを1秒に設定 (2秒遅延するので初回は必ずタイムアウト)
119    CURLOPT_CONNECTTIMEOUT => 1,
120];
121$result3 = makeCurlRequestWithRetry($slowUrl, $slowOptions, 2, 500); // 2回リトライ、初期遅延500ms
122
123if ($result3 !== false) {
124    echo "成功: 遅延のあるURLからレスポンスを受信しました。\n";
125    echo "内容 (最初の200文字):\n" . substr($result3, 0, 200) . "...\n\n";
126} else {
127    echo "失敗: 遅延のあるURLからの取得に失敗しました。\n\n";
128}

このPHPサンプルコードは、PHPのcURL拡張機能を用いて、ネットワークリクエストが失敗した場合に自動的に再試行するmakeCurlRequestWithRetry関数を定義しています。この関数は、一時的なネットワーク障害やタイムアウト、特定のHTTPステータスコードによるエラーから回復し、外部サービスとの安定した通信を確立するために役立ちます。

関数は四つの引数を取ります。$urlはリクエストを送信するURL、$optionsはcURL設定の配列、$maxRetriesは最大リトライ回数（0の場合はリトライなしで1回のみ試行）、$initialDelayMsは初回の遅延時間（ミリ秒）です。各リトライの間には、この$initialDelayMsが指数関数的に増加する「指数関数的バックオフ」と呼ばれる遅延が挿入され、サーバーへの過度な負荷を軽減します。

内部では、指定された試行回数までループを行い、cURLセッションの初期化、リクエストの実行、およびエラーチェック（cURLエラーコードやHTTPステータスコードの確認）を繰り返します。リクエストが成功（cURLエラーがなく、HTTPステータスコードが200番台）した場合は、その時点でレスポンスボディを文字列として返します。全てのリトライが失敗に終わった場合は、falseを戻り値として返します。この機能により、ネットワーク状況に左右されにくい堅牢なアプリケーションの構築が可能となります。