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

Copy
1<?php
2
3/**
4 * URLへのHTTPリクエストを指定回数リトライする関数。
5 * ネットワークエラーやサーバーエラーが発生した場合に再試行を試みます。
6 *
7 * @param string $url リクエスト先のURL。
8 * @param array $options cURLオプションの配列。例: [CURLOPT_TIMEOUT => 10]。
9 * @param int $maxRetries 最大リトライ回数 (0はリトライなし)。
10 * @param int $initialDelaySec リトライ間の初期遅延時間（秒）。エラーが連続する場合は指数バックオフで増加します。
11 * @return string|false 成功した場合はレスポンスボディ、失敗した場合はfalse。
12 */
13function fetchDataWithRetry(
14    string $url,
15    array $options = [],
16    int $maxRetries = 3,
17    int $initialDelaySec = 1
18): string|false {
19    $attempt = 0;
20    $delay = $initialDelaySec;
21
22    // CURLPAUSE_RECV_CONT は、cURL転送の受信データフローを一時停止または再開するために
23    // curl_pause() 関数と共に使用される定数です。
24    // 一般的なHTTPリクエストのリトライ処理（接続失敗時の再試行など）には直接使用されません。
25    // この定数は、PHPのCURL拡張機能の一部として存在します。
26    // 例: curl_pause($ch, CURLPAUSE_RECV_CONT); // 受信の一時停止後に継続を指示する場合
27    // この定数の値を確認したい場合は var_dump(CURLPAUSE_RECV_CONT); を使用します。
28
29    while ($attempt <= $maxRetries) {
30        $ch = curl_init();
31        if ($ch === false) {
32            error_log("CURL 初期化に失敗しました。");
33            return false;
34        }
35
36        // 基本オプションの設定
37        curl_setopt($ch, CURLOPT_URL, $url);
38        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // レスポンスを文字列として取得
39        curl_setopt($ch, CURLOPT_FAILONERROR, false);   // HTTPステータスコード >= 400 でもエラーとしない (手動で判定するため)
40        curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);    // 接続タイムアウト
41        curl_setopt($ch, CURLOPT_TIMEOUT, 10);          // 転送タイムアウト
42
43        // ユーザー指定のオプションをマージ
44        foreach ($options as $opt => $val) {
45            curl_setopt($ch, $opt, $val);
46        }
47
48        $response = curl_exec($ch);
49        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
50        $curlErrno = curl_errno($ch);
51        $curlError = curl_error($ch);
52
53        curl_close($ch);
54
55        // 成功条件: レスポンスが取得でき、HTTPステータスコードが200番台
56        if ($response !== false && $httpCode >= 200 && $httpCode < 300) {
57            echo "試行 " . ($attempt + 1) . ": " . $url . " からデータを正常に取得しました。" . PHP_EOL;
58            return $response;
59        }
60
61        // 失敗ログを出力
62        error_log("試行 " . ($attempt + 1) . " が失敗しました。URL: " . $url .
63                  ", HTTPコード: " . $httpCode . ", cURLエラー (" . $curlErrno . "): " . $curlError);
64
65        $attempt++;
66
67        // 最大リトライ回数に達していない場合のみ待機
68        if ($attempt <= $maxRetries) {
69            echo "リトライします。次の試行まで " . $delay . " 秒待機します..." . PHP_EOL;
70            sleep($delay);
71            $delay *= 2; // 指数バックオフで遅延時間を増加
72        }
73    }
74
75    error_log($url . " からデータを取得できませんでした。最大 " . ($maxRetries + 1) . " 回試行しました。");
76    return false;
77}
78
79// --- サンプル使用例 ---
80
81// 成功するURL
82$successfulUrl = "https://httpbin.org/status/200"; 
83
84// 失敗するURL (HTTP 500 Internal Server Error)
85$errorUrl = "https://httpbin.org/status/500"; 
86
87// 存在しないドメイン (DNS解決エラーなど、cURLエラーが発生)
88$nonExistentDomainUrl = "http://this.domain.does.not.exist.example.com"; 
89
90echo "--- 成功するURLへのリクエスト ---" . PHP_EOL;
91$data = fetchDataWithRetry($successfulUrl);
92if ($data !== false) {
93    echo "成功！データ長: " . strlen($data) . " バイト。" . PHP_EOL;
94} else {
95    echo "失敗しました。" . PHP_EOL;
96}
97echo PHP_EOL;
98
99echo "--- HTTP 500 エラーが発生するURLへのリクエスト (リトライあり) ---" . PHP_EOL;
100// HTTP 500エラーは通常、リトライで改善しないことが多いですが、リトライロジックの動作確認のため
101$data = fetchDataWithRetry($errorUrl, [], 2, 1);
102if ($data !== false) {
103    echo "成功！データ長: " . strlen($data) . " バイト。" . PHP_EOL;
104} else {
105    echo "複数回のリトライ後もデータ取得に失敗しました。" . PHP_EOL;
106}
107echo PHP_EOL;
108
109echo "--- 存在しないドメインへのリクエスト (cURLエラー、リトライあり) ---" . PHP_EOL;
110// ネットワークエラー (例: DNS解決失敗) もリトライ対象としています
111$data = fetchDataWithRetry($nonExistentDomainUrl, [], 2, 1);
112if ($data !== false) {
113    echo "成功！データ長: " . strlen($data) . " バイト。" . PHP_EOL;
114} else {
115    echo "複数回のリトライ後もデータ取得に失敗しました (cURLエラー)。" . PHP_EOL;
116}
117echo PHP_EOL;

このPHPサンプルコードは、cURL拡張機能を用いて指定されたURLへHTTPリクエストを行い、ネットワークエラーやサーバーエラーが発生した場合に、指定回数リトライする処理を実装したfetchDataWithRetry関数を提供しています。

fetchDataWithRetry関数は、リクエスト先のURL（$url）、最大リトライ回数（$maxRetries）、リトライ間の初期遅延時間（$initialDelaySec）を引数として受け取ります。この関数は、HTTPステータスコードが200番台であれば成功と判断し、レスポンスボディを返します。通信が失敗した場合は、エラーログを出力し、指数バックオフ（遅延時間が徐々に長くなる）で待機しながら再試行を試みます。これにより、一時的な接続不良などに対応し、処理の堅牢性を高めます。

CURLPAUSE_RECV_CONT定数は、cURL転送における受信データフローの一時停止や再開を制御するためにcurl_pause()関数と併用される定数です。このサンプルコードでは直接使用されていませんが、PHPのCURL拡張機能の一部として存在し、より低レベルなデータ転送制御が必要な場面で利用されます。

fetchDataWithRetry関数は、データ取得に成功した場合はレスポンスボディの文字列を返し、指定されたすべてのリトライを試行してもデータ取得に失敗した場合はfalseを返します。

Copy
1<?php
2
3/**
4 * CURLの受信処理を一時停止・再開するサンプル
5 *
6 * この関数は、CURLPAUSE_RECV_CONT 定数を使用して、
7 * curl_multi_* インターフェースを介したデータ受信を一時停止し、その後再開する方法を示します。
8 *
9 * システムエンジニアを目指す初心者の方へ:
10 * 通常、curl_exec() はHTTPリクエストが完了するまで処理をブロック（待機）します。
11 * 「レスポンスを待たない」というキーワードは、このブロッキング動作を避け、
12 * 処理の途中で他のタスクを実行したいというニーズを指すことがあります。
13 *
14 * curl_multi_* 関数群と curl_pause() を組み合わせることで、
15 * CURLがデータを完全に受信し終わるのを待つことなく、途中で処理を一時停止させ、
16 * アプリケーションが制御を取り戻して他のロジックを実行する「猶予」を持つことができます。
17 * その後、CURLPAUSE_RECV_CONT を使って受信処理を再開します。
18 * これは、大きなファイルのダウンロード中に進捗を表示したり、
19 * 部分的なデータを処理したりする際に役立ちます。
20 */
21function demonstrateCurlPauseRecvCont(): void
22{
23    // デモンストレーション用のURL。
24    // ある程度のデータ量があり、一時停止の効果が確認しやすいものを選択しています。
25    // 例: JSONPlaceholderのコメントリストの一部 (約50KB程度のJSONデータ)
26    $url = 'https://jsonplaceholder.typicode.com/comments?postId=1'; 
27
28    echo "CURL受信処理の一時停止と再開のデモンストレーションを開始します。\n";
29
30    $mh = curl_multi_init(); // マルチCURLハンドラを初期化
31    $ch = curl_init();      // 単一CURLハンドラを初期化
32
33    // 受信したデータを格納するためのバッファ
34    $receivedData = '';
35    // 受信処理を一時停止させるためのフラグ。最初のデータチャンクで一時停止するように設定。
36    $shouldPauseOnFirstChunk = true;
37    // 一時停止が一度トリガーされ、再開処理が実行されたかどうかを追跡するフラグ
38    $pauseTriggeredAndHandled = false;
39
40    // CURLOPT_WRITEFUNCTION: データを受信するたびに呼び出されるコールバック関数を設定します。
41    // この関数は、CURLが受信したデータをどのように処理するかを制御します。
42    curl_setopt($ch, CURLOPT_WRITEFUNCTION, function ($ch_handle, $data) use (&$receivedData, &$shouldPauseOnFirstChunk) {
43        $dataLength = strlen($data);
44        echo "  受信データチャンク（" . $dataLength . "バイト）\n";
45        $receivedData .= $data; // 受信データをバッファに追加
46
47        // $shouldPauseOnFirstChunk が true の場合、受信処理を一時停止します。
48        // これは、最初のデータチャンクを受信した時点で一度一時停止させるためのロジックです。
49        if ($shouldPauseOnFirstChunk && $dataLength > 0) {
50            echo "  ---- 受信処理を一時停止します (CURL_WRITEFUNC_PAUSE) ----\n";
51            $shouldPauseOnFirstChunk = false; // 一度一時停止したら、フラグをリセット
52            return CURL_WRITEFUNC_PAUSE;       // CURLに対して一時停止を要求
53        }
54        return $dataLength; // 受信を続行し、受け取ったバイト数を返します。
55    });
56
57    curl_setopt($ch, CURLOPT_URL, $url);           // リクエストURLを設定
58    curl_setopt($ch, CURLOPT_HEADER, 0);           // レスポンスヘッダーを含めない
59    // CURLOPT_RETURNTRANSFER は使用しません。CURLOPT_WRITEFUNCTION でデータを処理するため、
60    // デフォルトの動作（標準出力に書き出す、または WRITEFUNCTION を呼び出す）を維持します。
61
62    curl_multi_add_handle($mh, $ch); // マルチハンドラにCURLハンドラを追加
63
64    $running = null; // 実行中のハンドラ数を追跡する変数
65
66    // CURLマルチリクエストの実行ループ
67    do {
68        // curl_multi_exec() を呼び出して、アクティブなCURLハンドラを処理します。
69        // $running には現在アクティブなハンドラの数が格納されます。
70        $status = curl_multi_exec($mh, $running);
71
72        if ($status === CURLM_CALL_MULTI_PERFORM) {
73            // curl_multi_exec() を再度呼び出す必要がある場合、ループを続行します。
74            continue;
75        }
76
77        // curl_multi_info_read() は、完了したCURLハンドルに関する情報（エラーなど）を取得します。
78        while ($info = curl_multi_info_read($mh)) {
79            if ($info['msg'] === CURLMSG_DONE) {
80                echo "  CURLハンドルが完了しました。\n";
81            }
82        }
83
84        // $running が0より大きい（まだ処理中のハンドルがある）場合、
85        // curl_multi_select() で待機し、I/Oイベントを待ちます。
86        // タイムアウトを設けることで、他の処理も行えるようになります。
87        if ($running && curl_multi_select($mh, 1.0) === -1) {
88            // selectエラーまたはタイムアウトの場合、CPU使用率を抑えるため少し待つ。
89            usleep(100);
90        }
91
92        // CURLハンドルが一時停止状態にあり、かつまだ再開処理をしていない場合
93        // curl_getinfo($ch, CURLINFO_PAUSE) は、CURLハンドルの現在のポーズ状態を返します。
94        // 0以外の値は一時停止中を示します。
95        if (curl_getinfo($ch, CURLINFO_PAUSE) > 0 && !$pauseTriggeredAndHandled) {
96            echo "  ---- アプリケーションは一時停止中に独自の処理を実行します ----\n";
97            // ここで、アプリケーションはCURLの受信を待たずに他の処理を実行できます。
98            // 例: ログの記録、プログレスバーの更新、別の非同期タスクの開始など。
99            sleep(2); // 2秒間「他の処理」をシミュレート
100            echo "  ---- 独自の処理が完了しました ----\n";
101
102            echo "  ---- 受信処理を再開します (CURLPAUSE_RECV_CONT) ----\n";
103            // curl_pause() に CURLPAUSE_RECV_CONT を渡すことで、
104            // 以前一時停止した受信処理を再開します。
105            curl_pause($ch, CURLPAUSE_RECV_CONT);
106            $pauseTriggeredAndHandled = true; // 再開フラグをセット
107        }
108
109    } while ($running > 0 || $status === CURLM_CALL_MULTI_PERFORM); // 処理中のハンドルがある限りループを続行
110
111    echo "CURLマルチリクエストの実行が完了しました。\n";
112    echo "最終的に受信したデータの長さ: " . strlen($receivedData) . "バイト\n";
113
114    curl_multi_remove_handle($mh, $ch); // マルチハンドラからCURLハンドラを削除
115    curl_close($ch);                     // 単一CURLハンドラをクローズ
116    curl_multi_close($mh);               // マルチCURLハンドラをクローズ
117
118    echo "デモンストレーションが終了しました。\n";
119}
120
121// 関数を呼び出してデモンストレーションを実行
122demonstrateCurlPauseRecvCont();

PHP 8のCURL拡張機能に属する定数CURLPAUSE_RECV_CONTは、HTTPリクエストのデータ受信処理を再開するために使用されます。この定数自体に引数や戻り値はありませんが、curl_pause()関数に渡すことで、特定のCURLハンドルの受信処理を再開する指示として機能します。

システムエンジニアを目指す初心者の方へ。「レスポンスを待たない」というキーワードは、通常curl_exec()がHTTPレスポンスの完了まで処理をブロックするのに対し、curl_multi_*関数群とcurl_pause()を組み合わせることで、データの受信中に他の処理を実行したい場合に利用されます。

サンプルコードでは、CURLOPT_WRITEFUNCTIONコールバック関数内で最初のデータチャンクを受信した際にCURL_WRITEFUNC_PAUSEを返し、受信処理を一時停止しています。これにより、アプリケーションはCURLがデータを完全に受信し終わる前に、メインループで一時的に別の処理（例として2秒間の待機）を実行できます。その後、curl_pause($ch, CURLPAUSE_RECV_CONT)を呼び出すことで、中断していた受信処理を再開します。これは、大きなファイルのダウンロード中にリアルタイムで進捗を表示したり、受信した部分データを逐次処理したりする際に非常に役立つ仕組みです。