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

Copy
1<?php
2
3/**
4 * cURLで低速転送制限 (CURLOPT_LOW_SPEED_LIMIT) の設定例を示します。
5 *
6 * この関数は、PHP cURL拡張機能を使用し、
7 * 転送速度が指定されたしきい値を下回る状態が一定時間続いた場合に
8 * リクエストをタイムアウトさせる設定を実演します。
9 */
10function demonstrateCurlLowSpeedLimit(): void
11{
12    // cURLリクエストのターゲットURLを設定します。
13    // 低速転送によるタイムアウトを実際に確認するには、
14    // 意図的に遅延させるサーバーエンドポイントや、非常にサイズの大きいファイルを
15    // 低帯域幅でダウンロードするなどのシナリオを想定してください。
16    $url = "https://example.com/some/resource"; // 例: 適宜変更してください
17
18    $ch = curl_init();
19
20    if ($ch === false) {
21        echo "エラー: cURLハンドルの初期化に失敗しました。\n";
22        return;
23    }
24
25    // 基本的なcURLオプションの設定
26    curl_setopt($ch, CURLOPT_URL, $url);             // ターゲットURL
27    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);   // 転送結果を文字列で返す
28    curl_setopt($ch, CURLOPT_FAILONERROR, true);      // HTTPステータスコードが400以上の場合にエラーとする
29
30    // CURLOPT_LOW_SPEED_LIMIT の設定
31    // 転送速度が指定されたバイト/秒を下回った場合に、
32    // CURLOPT_LOW_SPEED_TIME と組み合わせてタイムアウトを発生させます。
33    // 例: 10 バイト/秒 (10 B/s)。
34    curl_setopt($ch, CURLOPT_LOW_SPEED_LIMIT, 10);
35
36    // CURLOPT_LOW_SPEED_TIME の設定
37    // CURLOPT_LOW_SPEED_LIMIT で指定された速度を下回る状態が継続する秒数を指定します。
38    // 例: 5 秒。転送速度が 5 秒間連続して 10 バイト/秒を下回った場合、cURLはタイムアウトします。
39    curl_setopt($ch, CURLOPT_LOW_SPEED_TIME, 5);
40
41    // CURLOPT_TIMEOUT の設定 (キーワードに合わせ、リクエスト全体の最大実行時間を制限)
42    // cURLリクエスト全体の最大実行時間を秒単位で設定します。
43    // CURLOPT_LOW_SPEED_LIMIT は低速による停滞を検知するのに対し、
44    // CURLOPT_TIMEOUT は接続確立からデータ受信までの全工程に適用されます。
45    // 例: 15 秒。
46    curl_setopt($ch, CURLOPT_TIMEOUT, 15);
47
48    echo "cURLリクエストを開始します... (URL: $url)\n";
49
50    $response = curl_exec($ch);
51
52    if (curl_errno($ch)) {
53        // cURLエラーが発生した場合
54        $error_message = curl_error($ch);
55        $error_code = curl_errno($ch);
56        echo "エラー: cURLリクエスト中に問題が発生しました。\n";
57        echo "コード: " . $error_code . ", メッセージ: " . $error_message . "\n";
58
59        if ($error_code === CURLE_OPERATION_TIMEDOUT) {
60             echo "ヒント: リクエストがタイムアウトしました。これは低速転送制限または全体タイムアウトによる可能性があります。\n";
61        }
62    } else {
63        // cURLリクエストが成功した場合
64        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
65        echo "成功: cURLリクエストが完了しました。\n";
66        echo "HTTPステータスコード: " . $httpCode . "\n";
67        echo "レスポンスデータの長さ: " . strlen($response) . " バイト\n";
68    }
69
70    // cURLハンドルのクローズ
71    curl_close($ch);
72}
73
74// 関数の実行
75demonstrateCurlLowSpeedLimit();

このサンプルコードは、PHPのcURL拡張機能を使用して、ネットワークリクエストのタイムアウトを細かく制御する方法をシステムエンジニアを目指す初心者向けに示しています。

特に重要なのはCURLOPT_LOW_SPEED_LIMIT定数とCURLOPT_LOW_SPEED_TIMEオプションの組み合わせです。CURLOPT_LOW_SPEED_LIMITは、データ転送速度が指定されたバイト/秒（サンプルでは10バイト/秒）を下回った場合に「低速」と判断する基準を設定します。この定数自体に引数や戻り値はありませんが、curl_setopt関数で設定する際にその基準となる数値を渡します。そして、CURLOPT_LOW_SPEED_TIMEで、この低速状態が何秒間（サンプルでは5秒間）続いたらリクエストをタイムアウトさせるかを指定します。これにより、ネットワークが不安定な状況で無駄に待機し続けることを防ぐことができます。

また、キーワードにもあるCURLOPT_TIMEOUTも設定されており、これはcURLリクエスト全体の最大実行時間（サンプルでは15秒）を制限します。CURLOPT_LOW_SPEED_LIMITがデータ転送の停滞に特化しているのに対し、CURLOPT_TIMEOUTは接続確立からデータ受信までの全工程に適用される点が異なります。

コードでは、設定されたオプションで実際にcURLリクエストを実行し、成功または失敗（タイムアウトを含む）した場合のメッセージやエラー情報を分かりやすく表示しています。

Copy
1<?php
2
3/**
4 * CURLOPT_LOW_SPEED_LIMIT 定数の使用例を示す関数。
5 *
6 * この関数は、CURLOPT_LOW_SPEED_LIMIT および CURLOPT_LOW_SPEED_TIME を設定し、
7 * 指定されたURLへのデータ転送が低速な場合に cURL 操作を中断する方法を示します。
8 * また、HTTPリダイレクトを自動的に追跡するための CURLOPT_FOLLOWLOCATION の設定例も含まれます。
9 *
10 * @param string $url アクセスするURL。
11 */
12function demonstrateCurlLowSpeedLimit(string $url): void
13{
14    // cURL拡張がロードされているか確認
15    if (!extension_loaded('curl')) {
16        echo "エラー: cURL拡張がロードされていません。PHP設定を確認してください。\n";
17        return;
18    }
19
20    // cURLセッションを初期化
21    $ch = curl_init();
22    if ($ch === false) {
23        echo "エラー: cURLセッションの初期化に失敗しました。\n";
24        return;
25    }
26
27    // アクセスするURLを設定
28    curl_setopt($ch, CURLOPT_URL, $url);
29    // レスポンスを文字列として取得するように設定
30    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
31    // HTTPリダイレクトが発生した場合に自動的に追跡するように設定
32    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
33
34    // --- 低速リミット設定 ---
35    // CURLOPT_LOW_SPEED_TIME: タイムアウトを検出するまでの秒数。
36    // 例: 5秒間。
37    $lowSpeedTime = 5;
38    curl_setopt($ch, CURLOPT_LOW_SPEED_TIME, $lowSpeedTime);
39
40    // CURLOPT_LOW_SPEED_LIMIT: 許可される最小転送速度（バイト/秒）。
41    // 例: 1バイト/秒。
42    // `$lowSpeedTime`秒間、転送速度がこの値を下回ると cURL 操作を中止します。
43    // これは、非常に遅い接続やハングアップした接続を検出するのに役立ちます。
44    $lowSpeedLimit = 1;
45    curl_setopt($ch, CURLOPT_LOW_SPEED_LIMIT, $lowSpeedLimit);
46
47    echo "URL: {$url}\n";
48    echo "cURLリクエストを開始します。\n";
49    echo "設定: {$lowSpeedTime}秒間、転送速度が{$lowSpeedLimit}バイト/秒を下回ると操作を中止します。\n";
50
51    // cURLセッションを実行
52    $response = curl_exec($ch);
53
54    // cURLエラーが発生したかチェック
55    if (curl_errno($ch)) {
56        echo "cURLエラーが発生しました: " . curl_error($ch) . " (エラーコード: " . curl_errno($ch) . ")\n";
57        // 低速リミットによるタイムアウトの場合、エラーコードは CURLE_OPERATION_TIMEDOUT (28) になります。
58        if (curl_errno($ch) === CURLE_OPERATION_TIMEDOUT) {
59            echo "このエラーは、CURLOPT_LOW_SPEED_LIMIT の設定により、データ転送が低速であると判断され、操作がタイムアウトした可能性があります。\n";
60        }
61    } else {
62        echo "cURLリクエストは成功しました。\n";
63        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
64        echo "HTTPステータスコード: {$httpCode}\n";
65        echo "取得したデータ（冒頭100文字）:\n";
66        echo mb_substr((string)$response, 0, 100) . "...\n";
67    }
68
69    // cURLセッションを閉じる
70    curl_close($ch);
71}
72
73// テスト用のURL。低速リミットを意図的に発動させるためには、
74// $lowSpeedTime を短く、または $lowSpeedLimit を大きく設定する必要があるかもしれません。
75// あるいは、意図的にレスポンスが遅延するようなテストサービスを利用するとより効果的です。
76$targetUrl = "http://www.google.com";
77
78// 関数を実行
79demonstrateCurlLowSpeedLimit($targetUrl);

PHPのCURLOPT_LOW_SPEED_LIMITは、cURLによるデータ転送において、許容される最低転送速度をバイト/秒で指定するための定数です。この定数をcurl_setopt()関数で設定することで、同時に指定するCURLOPT_LOW_SPEED_TIMEで設定された秒数（例えば5秒間）の間に、データ転送速度がこの制限値（例えば1バイト/秒）を下回った場合に、cURL操作を自動的に中断させることができます。これは、ネットワーク接続が非常に遅い場合や、リモートサーバーが応答を停止してデータ転送が滞っている「ハングアップ状態」を効率的に検出し、タイムアウトさせるために利用されます。

サンプルコードでは、この機能を活用し、cURLが指定されたURLへアクセスする際に、5秒間データ転送が1バイト/秒以下であれば処理を中止するよう設定しています。これにより、無限に待機するような状況を避けることができます。また、コードにはCURLOPT_FOLLOWLOCATIONをtrueに設定する例も含まれており、これはHTTPリダイレクト（アクセスしたURLが別のURLへ転送されること）が発生した場合に、cURLが自動的に新しいURLを追跡してアクセスするように指示する設定です。これらの設定はcurl_init()で初期化したcURLセッションハンドルに対して適用され、curl_exec()の実行結果に影響を与えます。CURLOPT_LOW_SPEED_LIMIT自体に引数や戻り値はありませんが、curl_setopt()の第二引数として利用され、cURLの挙動を制御します。操作が低速リミットにより中断された場合、curl_errno()でエラーコードCURLE_OPERATION_TIMEDOUT（28）を確認できます。