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

Copy
1<?php
2
3/**
4 * 複数のCURLリクエストを並行して実行し、その結果を取得する関数。
5 *
6 * PHP 8 で利用可能な定数 `CURLFTPMETHOD_MULTICWD` は、`curl` 拡張機能の一部です。
7 * これはFTP接続においてファイル転送方法を指定する `CURLOPT_FTP_FILEMETHOD` オプションに
8 * 使用される整数型の値です。例えば、FTPサーバーとの通信で複数の `CWD` コマンドを送信するように
9 * cURLを設定する際に使われます。
10 *
11 * このサンプルコードでは、キーワードである `curl_multi_getcontent` の
12 * 主要な使い方を示すため、複数のHTTPリクエストの並行処理に焦点を当てています。
13 * FTPリクエストの具体的な例は環境依存が強く、初心者向けとして複雑になるため含めていませんが、
14 * `CURLFTPMETHOD_MULTICWD` のような定数は、個々の cURL ハンドル (`CURL` リソース) の
15 * オプション設定 (`curl_setopt`) で使用されることを理解することが重要です。
16 *
17 * @param array<string> $urls 取得するURLの配列
18 * @return array<string|false> 各URLのコンテンツ、または失敗した場合はfalse
19 */
20function fetchMultipleUrls(array $urls): array
21{
22    // マルチCURLハンドルを初期化
23    $mh = curl_multi_init();
24    if ($mh === false) {
25        throw new RuntimeException("CURLマルチハンドルを初期化できませんでした。");
26    }
27
28    $curlHandles = []; // 個々のCURLハンドルを保持する配列
29
30    // 各URLに対してCURLハンドルを初期化し、マルチハンドルに追加
31    foreach ($urls as $key => $url) {
32        $ch = curl_init();
33        if ($ch === false) {
34            error_log("URL: '{$url}' のCURLハンドルを初期化できませんでした。");
35            continue;
36        }
37
38        curl_setopt($ch, CURLOPT_URL, $url);
39        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 結果を文字列として返す
40        curl_setopt($ch, CURLOPT_HEADER, false);       // レスポンスヘッダを含めない
41        // 開発環境によってはSSL証明書の検証を無効にする必要がある場合がありますが、
42        // 本番環境ではセキュリティ上の理由から非推奨です。
43        // curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
44        // curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
45
46        // 個々のCURLハンドルをマルチハンドルに追加
47        $addResult = curl_multi_add_handle($mh, $ch);
48        if ($addResult !== CURLM_OK) {
49            error_log("URL: '{$url}' のCURLハンドルをマルチハンドルに追加できませんでした。エラーコード: " . $addResult);
50            curl_close($ch); // 失敗したら閉じる
51            continue;
52        }
53        $curlHandles[$key] = $ch;
54    }
55
56    $running = null; // アクティブなハンドル数を追跡する変数
57
58    // 全てのリクエストが完了するまでループ
59    do {
60        // cURLマルチセッションを実行
61        // $running に現在アクティブなハンドル数がセットされます
62        $execResult = curl_multi_exec($mh, $running);
63        if ($execResult !== CURLM_OK && $execResult !== CURLM_CALL_MULTI_PERFORM) {
64            error_log("cURLマルチ実行中にエラーが発生しました: " . curl_multi_strerror($execResult));
65            break;
66        }
67        // curl_multi_select は、IOイベントを待機し、CPU負荷を軽減します。
68        // タイムアウトを短く設定することで、より頻繁に処理を進められます。
69        if ($running > 0) {
70            curl_multi_select($mh, 0.1); // 0.1秒 (100ミリ秒) 待機
71        }
72    } while ($running > 0);
73
74    $results = [];
75    // 各CURLハンドルから結果を取得し、ハンドルを閉じる
76    foreach ($curlHandles as $key => $ch) {
77        // curl_multi_getcontent は、個々のCURLハンドルから取得した応答内容
78        // （通常はHTMLやJSONなどの文字列）を返します。
79        $content = curl_multi_getcontent($ch);
80
81        // cURLハンドルの情報を取得することも可能 (例: HTTPステータスコード)
82        // $httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
83        // if ($httpStatus === 200) { ... } else { ... }
84
85        $results[$key] = $content;
86
87        // マルチハンドルから個々のハンドルを削除
88        curl_multi_remove_handle($mh, $ch);
89        // 個々のCURLハンドルを閉じる
90        curl_close($ch);
91    }
92
93    // マルチCURLハンドルを閉じる
94    curl_multi_close($mh);
95
96    return $results;
97}
98
99// --- サンプル使用例 ---
100// 複数のURLを指定して、fetchMultipleUrls 関数を呼び出します。
101// 外部ネットワークにアクセスするため、実行環境に注意してください。
102$urlsToFetch = [
103    'https://www.google.com',
104    'https://www.bing.com',
105    'https://www.yahoo.com',
106    'https://www.php.net',
107    // 存在しないURLや遅延するURLを追加すると、エラーハンドリングや並行処理の挙動を確認できます。
108    // 'http://invalid.example.com', // 存在しないドメイン
109    // 'https://httpbin.org/delay/3' // 3秒遅延するURL
110];
111
112echo "複数のURLからコンテンツを並行して取得中...\n";
113$contents = fetchMultipleUrls($urlsToFetch);
114
115foreach ($contents as $key => $content) {
116    echo "--- URL: " . ($urlsToFetch[$key] ?? '不明なURL') . " ---\n";
117    if ($content !== false && $content !== '') {
118        echo "コンテンツの最初の100文字:\n";
119        // HTMLタグを除去し、UTF-8対応で最初の100文字を切り出して表示
120        $displayContent = mb_substr(strip_tags($content), 0, 100, 'UTF-8');
121        echo $displayContent . (mb_strlen(strip_tags($content), 'UTF-8') > 100 ? '...' : '') . "\n\n";
122    } else {
123        echo "コンテンツの取得に失敗したか、内容が空でした。\n\n";
124    }
125}

このPHPコードは、複数のウェブサイト（URL）からコンテンツを同時に（並行して）取得する方法を示しており、個々のURLを順番に取得するよりも全体の処理時間を短縮できる場合があります。

リファレンスにあるCURLFTPMETHOD_MULTICWDは、FTP通信でファイルを転送する際の特定の動作を指定する定数ですが、このサンプルコードはHTTPリクエストの並行処理に焦点を当てています。CURLFTPMETHOD_MULTICWDのような定数は、個々のcURLハンドルの動作をcurl_setopt関数で設定する際に使用されることを示しています。

fetchMultipleUrls関数は、取得したいURLを文字列で格納した配列（引数$urls）を受け取ります。戻り値は、入力されたURLと同じ順序で、それぞれのURLから取得されたコンテンツ（文字列）または取得に失敗した場合はfalseを格納した配列です。

この関数では、まずcurl_multi_initで複数のcURLリクエストを管理するための「マルチcURLハンドル」を初期化します。次に、取得したい各URLに対してcurl_initで個別のcURLハンドルを作成し、コンテンツを文字列として返す設定（CURLOPT_RETURNTRANSFER）などのオプションを設定した後、curl_multi_add_handleでマルチハンドルに追加します。

その後、curl_multi_exec関数をループで繰り返し呼び出すことで、追加された全てのリクエストを並行して実行し、完了を待ちます。全てのリクエストが完了した後、キーワードであるcurl_multi_getcontent関数を使って、各個別のcURLハンドルから取得された実際のウェブページのコンテンツ（HTMLやJSONなどの文字列）を取り出します。最後に、使用した全てのcURLハンドルとマルチcURLハンドルを適切に閉じます。

Copy
1<?php
2
3/**
4 * 複数のURLに対して並行してCURLリクエストを実行し、その結果を返します。
5 *
6 * この関数は、CURLマルチハンドラを使用して、指定された複数のURLへ同時にHTTPリクエストを送信します。
7 * 'CURLFTPMETHOD_MULTICWD' 定数はFTP転送時に使用されるもので、HTTPリクエストでは直接関係ありません。
8 * これは、FTPのディレクトリ変更方法を「複数のCWDコマンドを発行する」と指定する際に、
9 * CURLOPT_FTP_FILEMETHOD オプションに設定される値の一つです。
10 * 例: curl_setopt($ch, CURLOPT_FTP_FILEMETHOD, CURLFTPMETHOD_MULTICWD);
11 *
12 * @param array $urls リクエストを送信するURLの配列。
13 * @return array 各URLに対するレスポンスボディの配列。エラーがあった場合はエラーメッセージ。
14 */
15function performMultiCurlRequest(array $urls): array
16{
17    // CURLマルチハンドラを初期化します。複数のCURLリクエストを同時に処理するために必要です。
18    $multi_handle = curl_multi_init();
19    $curl_handles = []; // 個々のCURLハンドラを格納する配列
20    $results = [];       // 各リクエストの結果を格納する配列
21
22    // 各URLに対してCURLハンドラを作成し、マルチハンドラに追加します。
23    foreach ($urls as $index => $url) {
24        $ch = curl_init(); // 新しいCURLハンドラを初期化
25
26        // CURLオプションを設定します。
27        curl_setopt($ch, CURLOPT_URL, $url);             // リクエストするURL
28        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);  // レスポンスを文字列として返すように設定
29        curl_setopt($ch, CURLOPT_HEADER, false);         // レスポンスヘッダーを含めない
30
31        // ここで CURLFTPMETHOD_MULTICWD 定数について説明します。
32        // この定数は、FTP転送時に CURLOPT_FTP_FILEMETHOD オプションに設定して利用されるものです。
33        // FTPクライアントがディレクトリを変更する際に、複数のCWDコマンドを発行する方法を指定します。
34        // 現在の例はHTTPリクエストのため直接使用しませんが、CURLの機能の一部として存在します。
35        // 例: curl_setopt($ch, CURLOPT_FTP_FILEMETHOD, CURLFTPMETHOD_MULTICWD);
36
37        // curl_multi_add_handle を使用して、単一のCURLハンドラをマルチハンドラに追加します。
38        // これにより、このハンドラがマルチリクエスト処理の一部となります。
39        curl_multi_add_handle($multi_handle, $ch);
40        $curl_handles[$index] = $ch; // 後で結果を取得するためにハンドラを保存
41    }
42
43    // すべてのリクエストが完了するまで実行を繰り返します。
44    $running = null; // 実行中のハンドラの数を追跡する変数
45    do {
46        // CURLマルチハンドラのアクティビティを監視し、実行します。
47        // $running は残りの実行中のハンドラの数で更新されます。
48        curl_multi_exec($multi_handle, $running);
49
50        // アクティビティがなければ、新しいイベントが発生するまで待機します。
51        // これによりCPU使用率を抑えることができます。
52        if ($running) {
53            curl_multi_select($multi_handle);
54        }
55    } while ($running > 0); // 実行中のハンドラがなくなるまでループ
56
57    // 各CURLハンドラから結果を取得し、後処理を行います。
58    foreach ($curl_handles as $index => $ch) {
59        $error = curl_error($ch); // エラーメッセージを取得
60        if ($error) {
61            $results[$urls[$index]] = 'Error: ' . $error; // エラーがあればそのメッセージを格納
62        } else {
63            // エラーがなければ、レスポンスボディを取得します。
64            $results[$urls[$index]] = curl_multi_getcontent($ch);
65        }
66        // マルチハンドラから単一のCURLハンドラを削除します。
67        curl_multi_remove_handle($multi_handle, $ch);
68        // 単一のCURLハンドラをクローズし、リソースを解放します。
69        curl_close($ch);
70    }
71
72    // マルチハンドラをクローズし、関連するリソースをすべて解放します。
73    curl_multi_close($multi_handle);
74
75    return $results;
76}
77
78// --- サンプル使用例 ---
79// 実際に存在するURLを指定してください。存在しないURLはエラーになる可能性があります。
80$targetUrls = [
81    'https://example.com',
82    'https://www.php.net/manual/ja/function.curl-multi-add-handle.php',
83    'https://httpbin.org/get?param=multicurl_test' // テスト用の公開API
84];
85
86echo "--- 複数のCURLリクエストを並行して実行中 ---\n";
87$responses = performMultiCurlRequest($targetUrls);
88
89// 各URLからのレスポンスを表示します。
90foreach ($responses as $url => $content) {
91    echo "\n---------------------------------------------------\n";
92    echo "URL: " . $url . "\n";
93    echo "ステータス: " . (str_contains($content, 'Error:') ? '失敗' : '成功') . "\n";
94    // 長いレスポンスの場合、一部のみ表示して見やすくします。
95    echo "内容 (一部): " . substr($content, 0, 300) . "...\n";
96    echo "---------------------------------------------------\n";
97}
98
99?>

このPHPサンプルコードは、CURL拡張機能を使って複数のWebサイトへ同時にHTTPリクエストを送信し、その結果を効率的に取得する方法を説明しています。

curl_multi_add_handle関数は、個別に作成したCURLリクエスト（単一のCURLハンドラ）を、複数のリクエストを並行処理するCURLマルチハンドラに追加する役割です。引数はマルチハンドラと単一のCURLハンドラで、成功時に整数0を、エラー時にはCURLM_CALL_MULTI_PERFORM定数をint型で返します。これにより、複数のHTTP通信などを効率良く同時実行できます。

CURLFTPMETHOD_MULTICWD定数は、FTP転送時にディレクトリ変更を「複数のCWD（Current Working Directory）コマンドで行う」と指定する際に使用される整数値です。本サンプルコードではHTTPリクエストを扱っているため直接は利用されていませんが、CURLのFTP関連機能の一部として存在します。

コードでは、まずマルチハンドラを初期化し、各URL用のCURLハンドラを設定後、curl_multi_add_handleでマルチハンドラに追加します。その後、curl_multi_execで並行通信を実行し、全て完了後に各URLからのレスポンスを取得し、リソースを解放します。この手法は、多数のWebサービスからのデータ収集などでアプリケーションの応答速度を高めるのに非常に有効です。