【PHP8.x】curl_multi_exec関数の使い方

<?php

/**
 * 複数のURLに並行してHTTPリクエストを送信し、その内容を取得します。
 * システムエンジニアを目指す初心者でも理解しやすいように、基本的なCURLマルチハンドルの利用方法を示します。
 *
 * @param array<string, string> $urls キーを識別子、値をURLとする連想配列。
 * @return array<string, string> キーを識別子、値をURLから取得したコンテンツ（またはエラーメッセージ）とする連想配列。
 * @throws RuntimeException CURLマルチハンドルの初期化に失敗した場合にスローされます。
 */
function fetchUrlsConcurrently(array $urls): array
{
    // 1. CURLマルチハンドルを初期化します。
    // これにより、複数のCURLリクエストを同時に管理できるようになります。
    $multi_handle = curl_multi_init();
    if ($multi_handle === false) {
        throw new RuntimeException("CURLマルチハンドルの初期化に失敗しました。");
    }

    $handles = []; // 個々のCURLハンドルを格納する配列
    $results = []; // 最終的な取得結果を格納する配列

    // 2. 各URLに対して個別のCURLハンドルを作成し、マルチハンドルに追加します。
    foreach ($urls as $key => $url) {
        $ch = curl_init();
        if ($ch === false) {
            // 個々のCURLハンドル作成に失敗した場合、エラーログを記録し、このURLはスキップします。
            error_log("CURLハンドル作成に失敗: " . $url);
            continue;
        }

        // CURLオプションを設定します。
        curl_setopt($ch, CURLOPT_URL, $url);             // リクエスト先のURLを設定
        curl_setopt($ch, CURLOPT_HEADER, 0);             // レスポンスヘッダーを結果に含めない
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);  // レスポンスボディを文字列として返す

        // 個々のCURLハンドルをマルチハンドルに追加します。
        curl_multi_add_handle($multi_handle, $ch);
        $handles[$key] = $ch; // 後で結果を取得するために、識別子とともにハンドルを保存します。
    }

    // 3. すべてのリクエストが完了するまで、CURLマルチハンドルを実行します。
    $still_running = null; // まだ実行中のCURLハンドルの数を格納します。
    do {
        // curl_multi_exec() を呼び出し、リクエストの実行状況を進めます。
        // $still_running は参照渡しで、実行中のハンドル数が更新されます。
        $status = curl_multi_exec($multi_handle, $still_running);

        if ($still_running > 0) {
            // まだ実行中のリクエストがある場合、CPUの使用率を抑えるためにイベントを待機します。
            // 0.1秒 (100ミリ秒) 待機するか、ソケットの活動があるまで待機します。
            curl_multi_select($multi_handle, 0.1);
        }
    } while ($still_running > 0 && $status === CURLM_OK); // 実行中のハンドルがあり、エラーがない間ループを続けます。

    // 4. 全てのリクエストが完了したら、結果を取得し、ハンドルをクローズします。
    foreach ($handles as $key => $ch) {
        $error = curl_error($ch); // エラーメッセージを取得
        $errno = curl_errno($ch); // エラー番号を取得

        if ($errno === 0) {
            // エラーがない場合、リクエストのコンテンツを取得します。
            $results[$key] = curl_multi_getcontent($ch);
        } else {
            // エラーが発生した場合、エラーメッセージを結果に格納します。
            $results[$key] = "エラー ($errno): " . $error;
        }

        // マルチハンドルから個々のCURLハンドルを削除します。
        curl_multi_remove_handle($multi_handle, $ch);
        // 個々のCURLハンドルをクローズし、リソースを解放します。
        curl_close($ch);
    }

    // マルチCURLハンドルをクローズし、関連するリソースを解放します。
    curl_multi_close($multi_handle);

    return $results;
}

// --- 使用例 ---
$urls_to_fetch = [
    'google' => 'https://www.google.com/',
    'github' => 'https://github.com/',
    'example_com' => 'https://example.com/',
    'invalid_url' => 'http://this-url-does-not-exist-12345.com/', // エラーテスト用
];

echo "複数のURLからコンテンツを並行して取得中...\n";

try {
    $fetched_contents = fetchUrlsConcurrently($urls_to_fetch);

    // 取得したコンテンツまたはエラーメッセージを表示します。
    foreach ($fetched_contents as $name => $content) {
        echo "\n--- " . $name . " ---\n";
        if (str_starts_with($content, "エラー")) {
            echo $content . "\n"; // エラーメッセージを表示
        } else {
            // 取得したコンテンツの最初の200文字を表示します。
            echo substr($content, 0, 200) . "...\n";
        }
    }
} catch (RuntimeException $e) {
    echo "エラー: " . $e->getMessage() . "\n";
}

?>

PHPのcurl_multi_exec関数は、複数のHTTPリクエストを並行して実行し、その進行を管理する際に使用されます。これにより、複数のウェブサイトからコンテンツを効率的に同時に取得するなどの処理が可能になります。

この関数の最初の引数$multi_handleは、curl_multi_initで初期化されたCurlMultiHandle型のリソースで、実行する複数のCURLリクエストをまとめた集合体です。二番目の引数&$still_runningは参照渡しで、関数が呼び出されるたびに、まだ実行中（処理が完了していない）のCURLハンドルの数がこの変数に整数値として更新されます。戻り値は整数型で、通常はCURLM_OKなどのマルチCURLハンドルの現在の実行ステータスを示します。

サンプルコードでは、fetchUrlsConcurrently関数内でcurl_multi_initで初期化したマルチハンドルに、curl_multi_add_handleを使って個々のCURLリクエストを追加しています。その後、do-whileループの中でcurl_multi_exec($multi_handle, $still_running)を繰り返し呼び出し、追加された複数のリクエストをバックグラウンドで並行処理します。$still_runningが0になるまでループを続けることで、すべてのリクエストの完了を待ちます。ループ内では、curl_multi_selectを挟むことで、CPU使用率を抑えつつ効率的にイベントを待機します。すべてのリクエストが完了したら、curl_multi_getcontentでそれぞれの結果を取得し、curl_multi_remove_handleやcurl_closeで関連するリソースを解放しています。このように、curl_multi_execはCURLによる並行処理を実現するための中心的な役割を担います。