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

Copy
1<?php
2
3/**
4 * 指定されたURLへのHTTP GETリクエストを、エラー発生時に再試行する関数。
5 *
6 * @param string $url リクエストを送信するURL。
7 * @param int $maxRetries 最大再試行回数 (初回試行を含む)。
8 * @param int $delaySecondsBetweenRetries 再試行間の待機時間 (秒)。
9 * @return string|false 成功時はレスポンスボディ、全ての試行が失敗した場合はfalse。
10 */
11function fetchUrlWithRetry(string $url, int $maxRetries = 3, int $delaySecondsBetweenRetries = 1): string|false
12{
13    for ($attempt = 1; $attempt <= $maxRetries; $attempt++) {
14        $ch = curl_init($url);
15
16        if ($ch === false) {
17            // cURL初期化に失敗した場合、再試行しても無駄なのでここで終了
18            error_log("CURL Error: Failed to initialize cURL for URL: {$url}");
19            return false;
20        }
21
22        // cURLオプションを設定
23        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);   // レスポンスを文字列で返すように設定
24        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);   // リダイレクトを自動的に追跡
25        curl_setopt($ch, CURLOPT_TIMEOUT, 10);            // 接続と応答のタイムアウトを10秒に設定
26        curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);      // 接続タイムアウトを5秒に設定
27
28        // CURLPAUSE_RECV は、curl_pause() 関数で受信操作を一時停止するために使用される定数です。
29        // PHP 8では整数値1を持ちます。
30        // この関数（ブロッキングなcurl_exec）では直接使用されませんが、cURL拡張機能の一部です。
31        // 例: $pauseReceiveValue = CURLPAUSE_RECV;
32
33        $response = curl_exec($ch);
34        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
35        $curlErrorNo = curl_errno($ch);
36        $curlErrorMsg = curl_error($ch);
37
38        curl_close($ch); // cURLセッションを閉じる
39
40        // HTTPステータスコードが200番台であれば成功とみなす
41        if ($response !== false && $httpCode >= 200 && $httpCode < 300) {
42            return $response; // 成功したので結果を返す
43        }
44
45        // 失敗ログの出力
46        error_log(sprintf(
47            "Attempt %d/%d failed for URL '%s'. HTTP Status: %d, cURL Error (%d): %s",
48            $attempt, $maxRetries, $url, $httpCode, $curlErrorNo, $curlErrorMsg
49        ));
50
51        // 最終試行でなければ、指定時間待機してから再試行
52        if ($attempt < $maxRetries) {
53            sleep($delaySecondsBetweenRetries);
54        }
55    }
56
57    return false; // 全ての試行が失敗
58}
59
60// --- サンプルコードの実行例 ---
61
62// 成功する可能性のあるURL
63$targetUrlSuccess = "https://httpbin.org/get";
64// 存在しないドメイン (cURLエラーになる)
65$targetUrlCurlFail = "http://nonexistent-domain-1234567890.com";
66// サーバー内部エラー (HTTP 500) を返すURL
67$targetUrlHttpFail = "https://httpbin.org/status/500";
68// 応答が遅延するが最終的に成功するURL (タイムアウトや再試行の挙動確認用)
69$targetUrlDelayedSuccess = "https://httpbin.org/delay/4"; // 4秒遅延
70
71echo "--- 成功するURLのテスト (即時応答) ---\n";
72$result = fetchUrlWithRetry($targetUrlSuccess, 1, 0); // 再試行なし
73if ($result !== false) {
74    echo "成功: レスポンス受信 (長さ: " . strlen($result) . " バイト)\n\n";
75} else {
76    echo "失敗: URLを取得できませんでした。\n\n";
77}
78
79echo "--- cURLエラーが発生するURLのテスト (複数回再試行) ---\n";
80// (エラーログはPHPのログ設定に依存します。通常CLIでは標準エラー出力に表示されます。)
81$result = fetchUrlWithRetry($targetUrlCurlFail, 3, 2); // 最大3回再試行、2秒待機
82if ($result !== false) {
83    echo "成功: レスポンス受信 (長さ: " . strlen($result) . " バイト)\n\n";
84} else {
85    echo "失敗: 複数回の再試行後もURLを取得できませんでした。\n\n";
86}
87
88echo "--- HTTP 500エラーが発生するURLのテスト (複数回再試行) ---\n";
89$result = fetchUrlWithRetry($targetUrlHttpFail, 2, 3); // 最大2回再試行、3秒待機
90if ($result !== false) {
91    echo "成功: レスポンス受信 (長さ: " . strlen($result) . " バイト)\n\n";
92} else {
93    echo "失敗: 複数回の再試行後もURLを取得できませんでした。\n\n";
94}
95
96echo "--- 遅延応答するURLのテスト (タイムアウトと再試行) ---\n";
97// fetchUrlWithRetry関数の CURLOPT_TIMEOUT は10秒。
98// $targetUrlDelayedSuccess は4秒遅延するため、1回目の試行は成功。
99// もし遅延を15秒に設定すると、1回目の試行がタイムアウトし、再試行される挙動が確認できます。
100$result = fetchUrlWithRetry($targetUrlDelayedSuccess, 2, 5); // 最大2回再試行、5秒待機
101if ($result !== false) {
102    echo "成功: レスポンス受信 (長さ: " . strlen($result) . " バイト)\n\n";
103} else {
104    echo "失敗: 複数回の再試行後もURLを取得できませんでした。\n\n";
105}

このサンプルコードは、PHPのcURL拡張機能を利用してHTTP GETリクエストを送信し、エラー発生時に自動的に再試行するfetchUrlWithRetry関数を提供しています。

fetchUrlWithRetry関数は、リクエスト先のURL、最大再試行回数、再試行間の待機時間を引数として受け取ります。内部ではcURLセッションを開始し、レスポンスを文字列として取得する設定や、接続・応答のタイムアウトなどを設定します。リクエストが成功（HTTPステータスコードが200番台）した場合は、サーバーからのレスポンスボディを文字列として返します。もしリクエストが失敗した場合、エラーを記録し、残りの再試行回数があれば指定時間待機して再度試行します。全ての試行が失敗すると、関数はfalseを返します。

CURLPAUSE_RECVはPHP 8のcURL拡張機能に定義されている定数で、curl_pause()関数を用いてデータ受信操作を一時停止する際に利用される整数値（1）です。このサンプルコードでは直接使用していませんが、cURLのより高度な非同期処理や一時停止制御のための機能の一部として存在します。

Copy
1<?php
2
3/**
4 * cURLを使用して指定されたURLからデータをフェッチし、
5 * 特定の条件でデータ受信を一時停止する例を示します。
6 *
7 * CURLPAUSE_RECV 定数は、cURLのコールバック関数内で返されると、
8 * 受信データの処理を一時停止するようにcURLライブラリに指示します。
9 * この機能は、主に非同期処理を行う curl_multi_exec() と組み合わせて使用することで、
10 * 柔軟なデータストリーミング制御が可能になります。
11 * curl_exec() の場合は、一時停止を要求しても転送が完了するまでブロックし続けます。
12 *
13 * @param string $url データをフェッチする対象のURL
14 * @return string 受信したデータ
15 * @throws RuntimeException cURLセッションの初期化失敗または実行中にエラーが発生した場合
16 */
17function fetchUrlWithPauseExample(string $url): string
18{
19    // cURLセッションを初期化します。
20    // これにより、HTTPリクエストを行うためのハンドルが作成されます。
21    $ch = curl_init();
22
23    // cURLハンドルの初期化に失敗した場合はエラーをスローします。
24    if ($ch === false) {
25        throw new RuntimeException('cURLセッションの初期化に失敗しました。');
26    }
27
28    // サーバーから受信したデータを蓄積する変数です。
29    $receivedData = '';
30    // 一時停止を一度だけトリガーするためのフラグです。
31    // これがないと、コールバックが呼ばれるたびに一時停止を要求し続ける可能性があります。
32    $pauseTriggered = false;
33
34    // cURLオプションを設定します。
35    // CURLOPT_URL: リクエストを送信するURL。
36    curl_setopt($ch, CURLOPT_URL, $url);
37    // CURLOPT_HEADER: レスポンスヘッダーをボディと一緒に出力しないようにします。
38    curl_setopt($ch, CURLOPT_HEADER, false);
39    // CURLOPT_RETURNTRANSFER: curl_exec() がレスポンスを直接出力せず、
40    // WRITEFUNCTIONコールバックがデータの処理を完全に制御するようにします。
41    curl_setopt($ch, CURLOPT_RETURNTRANSFER, false);
42
43    // CURLOPT_WRITEFUNCTION を設定し、データ受信時に呼び出されるコールバック関数を定義します。
44    // このコールバックは、サーバーからデータの一部が届くたびに実行されます。
45    // 無名関数内で `use (&$receivedData, &$pauseTriggered)` を使うことで、
46    // 関数スコープ外の変数を参照し、変更できるようになります。
47    curl_setopt($ch, CURLOPT_WRITEFUNCTION, function ($ch_handle, $data) use (&$receivedData, &$pauseTriggered) {
48        $dataLength = strlen($data);
49        $receivedData .= $data; // 受信データを蓄積します。
50
51        // ここでは、受信データが50バイトを超え、かつまだ一時停止を要求していない場合に、
52        // 受信の一時停止を要求する例を示します。
53        // 実際のアプリケーションでは、より複雑なロジックに基づいて一時停止を決定します。
54        if (strlen($receivedData) > 50 && !$pauseTriggered) {
55            echo "DEBUG: 受信データが50バイトを超えました (" . strlen($receivedData) . "バイト)。受信一時停止を要求します。\n";
56            $pauseTriggered = true; // 一度一時停止を要求したら、再び要求しないようにフラグを設定します。
57            
58            // CURLPAUSE_RECV を返すと、cURLライブラリはこの時点での受信処理を一時停止します。
59            // この定数は、PHPのcURL拡張機能によって提供される特別な値です。
60            // しかし、curl_exec() は転送が完了するまでブロックするため、この一時停止は
61            // curl_multi_exec() といった非同期処理のコンテキストでより効果を発揮します。
62            return CURLPAUSE_RECV;
63        }
64
65        // 通常、データの処理を続行する場合は、受信したデータのバイト数を返します。
66        // cURLはこの戻り値を使用して、コールバックがどれだけのデータを「処理したか」を把握します。
67        return $dataLength;
68    });
69
70    // cURLセッションを実行します。
71    // 前述の通り、コールバック関数が CURLPAUSE_RECV を返しても、
72    // curl_exec() は通常、転送が完了するまでブロックし、待機します。
73    curl_exec($ch);
74
75    // cURLの実行中にエラーが発生したかチェックします。
76    if (curl_errno($ch)) {
77        throw new RuntimeException('cURLエラー: ' . curl_error($ch));
78    }
79
80    // cURLセッションを閉じ、関連するリソースを解放します。
81    curl_close($ch);
82
83    // コールバック関数によって蓄積された全データを返します。
84    return $receivedData;
85}
86
87// サンプル使用例
88// 実際にアクセス可能で、ある程度の長さのコンテンツを返すURLを指定してください。
89// 例: 'https://jsonplaceholder.typicode.com/posts/1' (JSONデータ) や 'https://example.com' (HTML)
90$targetUrl = 'https://example.com'; 
91
92try {
93    echo "URLからデータをフェッチ中: " . $targetUrl . "\n";
94    $data = fetchUrlWithPauseExample($targetUrl);
95    echo "--- 受信データ (一部表示) ---\n";
96    // 受信したデータが非常に長い可能性があるので、先頭200バイトのみを表示します。
97    echo substr($data, 0, 200) . "...\n"; 
98    echo "合計受信バイト数: " . strlen($data) . "\n";
99} catch (RuntimeException $e) {
100    echo "エラー: " . $e->getMessage() . "\n";
101}
102

このPHPサンプルコードは、cURLライブラリを用いて指定されたURLからデータをフェッチし、特定の条件でデータ受信を一時停止する挙動を示すものです。fetchUrlWithPauseExample関数は、対象URLを引数$urlとして受け取り、サーバーから受信した全データを文字列として返します。cURLセッションの初期化や実行中に問題が発生した場合はRuntimeExceptionをスローします。

特に注目すべきは、CURLPAUSE_RECV定数の使用です。この定数は、CURLOPT_WRITEFUNCTIONオプションで設定されたコールバック関数内で返されると、cURLライブラリに対し、それ以上のデータ受信処理を一時的に停止するよう指示します。サンプルコードでは、受信データが50バイトを超えた場合に一時停止を要求するロジックが組み込まれています。

ただし、curl_exec()関数はデータ転送が完了するまで処理をブロックし続けるため、CURLPAUSE_RECVによる一時停止は、主にcurl_multi_exec()のような非同期処理と組み合わせることで真に効果を発揮します。このコードは、cURLのデータストリーミング制御の一例として、コールバック関数がいかに柔軟な処理を可能にするかを示しています。最後に、処理が完了するとcURLセッションは閉じられ、関連するリソースが解放されます。