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

Copy
1<?php
2
3/**
4 * CURLMOPT_MAX_PIPELINE_LENGTH オプションを使用して、複数のURLからデータを非同期に取得するサンプルコードです。
5 *
6 * この関数は、複数のHTTPリクエストを並行して実行し、
7 * CURLMOPT_MAX_PIPELINE_LENGTH オプションでHTTP/1.1パイプラインの最大長を設定する方法を示します。
8 * (注: 多くのWebサーバーはHTTP/1.1パイプラインを完全にサポートしていないか、無効にしています。
9 * このオプションは、設定可能なオプションの使用例として理解してください。)
10 *
11 * キーワード `curlm_call_multi_perform` はPHPの標準関数としては存在しませんが、
12 * ここでは、その意図するであろう「CURLマルチハンドルを用いた並行処理」を
13 * 現代的な `curl_multi_exec` を使って実現しています。
14 *
15 * @param array $urls 取得するURLの配列
16 * @return array 各URLとそれに対応するコンテンツの連想配列
17 */
18function fetch_urls_with_pipeline_limit(array $urls): array
19{
20    // cURLマルチハンドルを初期化します。
21    $mh = curl_multi_init();
22    if ($mh === false) {
23        // エラーが発生した場合の処理
24        echo "cURLマルチハンドルの初期化に失敗しました。\n";
25        return [];
26    }
27
28    $ch_handles = []; // 個々のcURLハンドルを保持する配列
29    $results = [];     // 最終的な結果を格納する配列
30
31    // 各URLに対して個別のcURLハンドルを作成し、マルチハンドルに追加します。
32    foreach ($urls as $index => $url) {
33        $ch = curl_init();
34        if ($ch === false) {
35            echo "cURLハンドルの初期化に失敗しました: $url\n";
36            continue;
37        }
38
39        // cURLオプションを設定します。
40        curl_setopt($ch, CURLOPT_URL, $url);                 // 取得するURL
41        curl_setopt($ch, CURLOPT_HEADER, 0);                 // レスポンスヘッダーを結果に含めない
42        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);      // 結果を文字列として返す
43
44        // 個々のcURLハンドルをマルチハンドルに追加します。
45        curl_multi_add_handle($mh, $ch);
46        $ch_handles[$index] = $ch; // 後で結果を取得するためにハンドルを保存します。
47    }
48
49    // CURLMOPT_MAX_PIPELINE_LENGTH オプションを設定します。
50    // このオプションは、単一の接続で処理されるHTTP/1.1パイプラインのリクエスト数を制限します。
51    // 値は正の整数で、デフォルトは0（無制限）です。
52    // ここでは例として「3」に設定しますが、実際の効果はアクセス先のサーバー実装に依存します。
53    curl_multi_setopt($mh, CURLMOPT_MAX_PIPELINE_LENGTH, 3);
54
55    // すべてのリクエストが完了するまでループを続けます。
56    $running = null; // アクティブなハンドルの数を保持します。
57    do {
58        // cURLマルチハンドルのアクティビティを実行します。
59        // `curl_multi_perform` の現代的な代替である `curl_multi_exec` を使用します。
60        $status = curl_multi_exec($mh, $running);
61
62        // `curl_multi_exec` がすぐに再度呼び出されるべきであることを示す場合
63        if ($status === CURLM_CALL_MULTI_PERFORM) {
64            continue;
65        }
66
67        // まだ実行中のリクエストがあり、エラーが発生していない場合
68        if ($running > 0 && $status === CURLM_OK) {
69            // I/Oアクティビティを待機します。
70            // タイムアウトを1秒に設定。-1は無限ですが、短いタイムアウトの方が安全です。
71            curl_multi_select($mh, 1.0);
72        }
73
74    } while ($running > 0 && $status === CURLM_OK); // 実行中のリクエストがあるか、エラーがない限り継続
75
76    // すべてのリクエストが完了したら、結果を取得し、ハンドルをクリーンアップします。
77    foreach ($ch_handles as $index => $ch) {
78        $url = $urls[$index];
79        $error = curl_error($ch); // cURLエラーメッセージを取得
80
81        if ($error === "") {
82            // エラーがない場合、取得したコンテンツを取得
83            $content = curl_multi_getcontent($ch);
84            $results[$url] = "成功: " . substr($content, 0, 100) . "..."; // 結果の最初の100文字を表示
85        } else {
86            // エラーがある場合、エラーメッセージを記録
87            $results[$url] = "エラー: " . $error;
88        }
89
90        // マルチハンドルから個々のcURLハンドルを削除します。
91        curl_multi_remove_handle($mh, $ch);
92        // 個々のcURLハンドルを閉じます。
93        curl_close($ch);
94    }
95
96    // cURLマルチハンドルを閉じ、リソースを解放します。
97    curl_multi_close($mh);
98
99    return $results;
100}
101
102// サンプル使用例
103// 動作確認のため、アクセス可能なURLをいくつか指定してください。
104// ご自身のローカルウェブサーバーのURLや、信頼できる公開URLを使用することを推奨します。
105$sample_urls = [
106    "http://example.com/",
107    "http://www.example.org/",
108    "http://www.example.net/",
109    // "http://localhost/page1.html", // ローカル環境でテストする場合の例
110    // "http://localhost/page2.html",
111];
112
113echo "複数のURLからデータを非同期に取得します (パイプライン長制限: 3に設定):\n";
114$fetched_data = fetch_urls_with_pipeline_limit($sample_urls);
115
116// 取得結果を表示します。
117foreach ($fetched_data as $url => $data) {
118    echo "URL: $url\n";
119    echo "  内容: $data\n\n";
120}
121
122?>

このサンプルコードは、PHPのcURL拡張機能を用いて、複数のURLからデータを非同期に取得する方法を示しています。CURLMOPT_MAX_PIPELINE_LENGTH定数を使って、HTTP/1.1パイプラインのリクエスト数を制限する方法を解説します。このオプションは、単一の接続で処理されるHTTPリクエスト数を設定しますが、多くのウェブサーバーでHTTP/1.1パイプラインが完全にサポートされていない場合があるため、オプションの使用例として理解してください。

コードはまず、curl_multi_init()で複数のcURLリクエストを管理するマルチハンドルを初期化します。次に、渡された$urls配列の各URLに対し、curl_init()で個別のcURLハンドルを作成し、URLなどのオプションを設定後、マルチハンドルに追加します。ここでcurl_multi_setopt()を使ってCURLMOPT_MAX_PIPELINE_LENGTHを「3」に設定し、パイプラインの最大長を制限しています。

その後、curl_multi_exec()とcurl_multi_select()で構成されるループで、全てのリクエストが完了するまで非同期通信を実行します。CURLM_CALL_MULTI_PERFORMは、curl_multi_exec()が即座に再呼び出しを推奨する状態を示す定数です。最後に、各リクエストの結果をcurl_multi_getcontent()で取得し、エラーがないか確認して、それぞれのハンドルとマルチハンドルを閉じます。関数は、引数$urls（取得するURLの配列）を受け取り、URLと結果の連想配列を返します。キーワードのcurlm_call_multi_performは直接の関数名ではありませんが、このコードはCURLマルチハンドルによる並行処理を現代的なcurl_multi_execで実現しています。

Copy
1<?php
2
3/**
4 * CURLMOPT_MAX_PIPELINE_LENGTH を設定し、CURLE_OPERATION_TIMEDOUT エラーをシミュレートする関数。
5 *
6 * この関数は、libcurl のマルチハンドルを使用して複数のリクエストを並行して実行します。
7 * パイプライン処理の最大長を設定し、各リクエストに短いタイムアウトを設定することで、
8 * 意図的に CURLE_OPERATION_TIMEDOUT エラーを発生させ、その検出方法を示します。
9 *
10 * 注: HTTP/1.1 のパイプライン処理は、多くの現代のウェブサーバーで完全にサポートされていないか、
11 * 無効にされている場合があります。しかし、この設定が cURL に与える影響と、
12 * 並行処理におけるタイムアウトの発生を理解するのに役立ちます。
13 */
14function simulatePipelinedTimeout(): void
15{
16    echo "CURLMOPT_MAX_PIPELINE_LENGTH を使用したパイプライン処理でのタイムアウトシミュレーションを開始します。\n\n";
17
18    // 1. cURL マルチハンドルを初期化
19    $multiHandle = curl_multi_init();
20    if ($multiHandle === false) {
21        echo "エラー: cURL マルチハンドルの初期化に失敗しました。\n";
22        return;
23    }
24
25    // 2. マルチハンドルのオプションを設定: パイプライン処理の最大長
26    // このオプションは、単一の接続でキューに入れることができるリクエストの最大数を設定します。
27    // HTTP/1.1 パイプライン処理にはサーバー側のサポートが必要です。
28    curl_multi_setopt($multiHandle, CURLMOPT_MAX_PIPELINE_LENGTH, 3);
29    echo "CURLMOPT_MAX_PIPELINE_LENGTH を 3 に設定しました。\n";
30
31    // タイムアウトをシミュレートするための遅延URLリスト
32    // httpbin.org はテスト用のHTTPサービスです。/delay/{seconds} で指定秒数応答を遅延させます。
33    $urls = [
34        'リクエストA' => 'http://httpbin.org/delay/5', // 5秒遅延するURL
35        'リクエストB' => 'http://httpbin.org/delay/2', // 2秒遅延するURL
36        'リクエストC' => 'http://httpbin.org/delay/4', // 4秒遅延するURL
37    ];
38
39    $handles = [];      // 個々のcURLハンドルの配列
40    $requestInfo = [];  // ハンドルIDとリクエスト名を紐付けるための配列
41
42    // 3. 各URLに対して cURL ハンドルを作成し、オプションを設定
43    foreach ($urls as $name => $url) {
44        $ch = curl_init();
45        if ($ch === false) {
46            echo "エラー: {$name} ({$url}) の cURL ハンドル初期化に失敗しました。\n";
47            continue;
48        }
49
50        curl_setopt($ch, CURLOPT_URL, $url);
51        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 結果を文字列として取得
52        // 短いタイムアウトを設定 (3秒)
53        // URLがこれより長く遅延する場合 (例: 5秒遅延のURL)、
54        // CURLE_OPERATION_TIMEDOUT エラーが発生するはずです。
55        curl_setopt($ch, CURLOPT_TIMEOUT, 3); // 3秒でタイムアウト
56
57        // cURL ハンドルをマルチハンドルに追加
58        curl_multi_add_handle($multiHandle, $ch);
59        $handles[] = $ch;
60        $requestInfo[(int)$ch] = $name; // ハンドルの整数IDでリクエスト名を保存
61        echo "{$name} ({$url}) をマルチハンドルに追加しました。タイムアウト: 3秒\n";
62    }
63
64    if (empty($handles)) {
65        echo "エラー: 処理する cURL ハンドルがありません。\n";
66        curl_multi_close($multiHandle);
67        return;
68    }
69
70    echo "\n--- リクエスト実行中 ---\n";
71
72    // 4. すべてのリクエストが完了するまでループで実行
73    $active = null; // アクティブなハンドル数を格納
74    do {
75        // cURL マルチ転送を実行し、完了した転送があればそれを処理
76        $mrc = curl_multi_exec($multiHandle, $active);
77
78        // イベント待機 (CPU使用率を抑えるため)
79        // curl_multi_select は、ハンドルに活動があるまで待機します。
80        // 一部のシステム (例: macOS) で -1 を返す場合があるため、短いスリープを挟みます。
81        if ($active > 0 && $mrc === CURLM_OK && curl_multi_select($multiHandle) === -1) {
82            usleep(100); // 100マイクロ秒待機
83        }
84
85    } while ($active > 0 && $mrc === CURLM_OK); // アクティブなハンドルがあり、エラーがない間ループを継続
86
87    echo "\n--- 結果の確認 ---\n";
88
89    // 5. 各リクエストの結果を確認
90    foreach ($handles as $ch) {
91        $name = $requestInfo[(int)$ch];
92        $error = curl_error($ch);     // エラーメッセージ
93        $errno = curl_errno($ch);     // エラーコード (CURLE_OPERATION_TIMEDOUT は 28)
94        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); // HTTPステータスコード
95
96        echo "{$name} (URL: " . curl_getinfo($ch, CURLINFO_EFFECTIVE_URL) . ")\n";
97        echo "  HTTP ステータスコード: {$httpCode}\n";
98        echo "  cURL エラーコード: {$errno}\n";
99        echo "  cURL エラーメッセージ: {$error}\n";
100
101        // エラーコードが CURLE_OPERATION_TIMEDOUT (28) であるかを確認
102        if ($errno === CURLE_OPERATION_TIMEDOUT) {
103            echo "  >>> 確認: CURLE_OPERATION_TIMEDOUT (コード 28) が検出されました！ <<< \n";
104        } else {
105            echo "  >>> 注意: タイムアウトエラーは検出されませんでした (コード {$errno})。\n";
106        }
107        echo "\n";
108
109        // ハンドルをマルチハンドルから削除し、個々のハンドルをクローズ
110        curl_multi_remove_handle($multiHandle, $ch);
111        curl_close($ch);
112    }
113
114    // 6. cURL マルチハンドルをクローズ
115    curl_multi_close($multiHandle);
116
117    echo "シミュレーションが完了しました。\n";
118}
119
120// 関数を実行
121simulatePipelinedTimeout();

PHPのcURL拡張機能を用いたこのサンプルコードは、複数のHTTPリクエストを並行して処理し、タイムアウトエラーを検出する方法をシステムエンジニアの初心者向けに紹介します。CURLMOPT_MAX_PIPELINE_LENGTHは、curl_multi_setopt関数で使用するオプション定数で、単一接続におけるパイプラインリクエストの最大長を設定します。この定数自体に引数や戻り値はなく、サーバーがHTTP/1.1パイプラインに対応している場合に利用価値があります。

コードでは、curl_multi_initで並行処理用のハンドルを作成し、複数のURLに対しcurl_initで個別のリクエストを設定します。各リクエストにはCURLOPT_TIMEOUTオプションで短いタイムアウト（3秒）が設けられ、応答が遅いURL（5秒遅延）を含めることで、意図的にCURLE_OPERATION_TIMEDOUTエラーを発生させます。

curl_multi_execでリクエストを実行後、curl_errnoとcurl_errorを用いて各リクエストの結果を確認します。CURLE_OPERATION_TIMEDOUTはエラーコード28として返され、リクエストが指定時間内に完了しなかったことを明確に示します。これにより、Webアプリケーション開発における非同期処理のエラーハンドリングの基礎を学ぶことができます。