【PHP8.x】CURL_FNMATCHFUNC_MATCH定数の使い方
CURL_FNMATCHFUNC_MATCH定数の使い方について、初心者にもわかりやすく解説します。
基本的な使い方
CURL_FNMATCHFUNC_MATCH定数は、PHPのcURL拡張機能において、ファイル名パターンマッチングのコールバック関数が「マッチした」ことを示すために使用される値を表す定数です。この定数は、特にcurl_setopt()関数を用いてCURLOPT_FNMATCH_FUNCTIONオプションを設定する際に重要な役割を果たします。
CURLOPT_FNMATCH_FUNCTIONオプションは、FTPなどのプロトコルでワイルドカード転送（GLOBING）を行う際に、どのファイル名が指定されたパターンに適合するかを判断するためのユーザー定義コールバック関数を登録するために使用されます。登録されたコールバック関数は、提供されたファイル名とパターンがマッチするかどうかを独自に判定し、その結果に応じて特定の定数を戻り値として返す必要があります。
CURL_FNMATCHFUNC_MATCHは、そのコールバック関数が、与えられたファイル名が指定されたパターンと一致すると判断した場合に、cURLライブラリへ「マッチした」と伝えるために返すための定数です。例えば、*.txtというパターンに対してdocument.txtというファイル名が渡された際に、コールバック関数がこの定数を返せば、cURLはdocument.txtが転送対象として適切であると認識し、後続の処理を進めることができます。
この定数を理解することは、複雑なファイル選択ロジックをcURL経由で実装する際に役立ちます。具体的には、ファイルのフィルタリングや特定の条件に合致するファイルを効率的に取得するシナリオにおいて、カスタムのコールバック関数を効果的に利用するために不可欠な要素となります。
構文(syntax)
1<?php 2CURL_FNMATCHFUNC_MATCH; 3?>
引数(parameters)
引数なし
引数はありません
戻り値(return)
戻り値なし
戻り値はありません
サンプルコード
PHP cURLマルチ実行とFNMATCH設定
1<?php 2 3/** 4 * CURL_FNMATCHFUNC_MATCH 定数を使用するコールバック関数の例。 5 * 6 * この定数は、FTPなどのファイル転送プロトコルにおけるワイルドカードマッチング機能で 7 * CURLOPT_FNMATCH_FUNCTION に設定されたコールバック関数が、 8 * ファイル名がパターンにマッチしたと判断した場合に返します。 9 * 10 * @param CurlHandle $curl CURL ハンドル (PHP 8 以降の型) 11 * @param string $filename マッチング対象のファイル名 12 * @param string $pattern マッチングパターン 13 * @return int 成功した場合は CURL_FNMATCHFUNC_MATCH を返します。 14 */ 15function myFnmatchCallback(CurlHandle $curl, string $filename, string $pattern): int 16{ 17 // 実際のマッチングロジックはここに追加されます。 18 // この例では、CURL_FNMATCHFUNC_MATCH の使用を示すために常にマッチしたと仮定し、その値を返します。 19 // このコールバックは、CURLOPT_FNMATCH_FUNCTION オプションが有効な場合にのみ呼び出されます。 20 // HTTP リクエストでは通常呼び出されませんが、定数の利用方法を示すために含めています。 21 return CURL_FNMATCHFUNC_MATCH; 22} 23 24/** 25 * 複数の cURL リクエストを並行して実行し、 26 * CURL_FNMATCHFUNC_MATCH 定数を含むコールバック関数の設定例を示す関数。 27 * 28 * `curl_multi_exec` (キーワード: `curlm_call_multi_perform` に相当) を使用して、 29 * 複数の cURL リクエストを効率的に処理します。 30 * 31 * @param array<string> $urls 取得するURLの配列 32 */ 33function performMultiCurlWithFnMatch(array $urls): void 34{ 35 // cURL マルチハンドルを初期化します。 36 // マルチハンドルは、複数の cURL リクエストを同時に管理するために使用されます。 37 $multi_handle = curl_multi_init(); 38 if ($multi_handle === false) { 39 echo "エラー: マルチ cURL ハンドルの初期化に失敗しました。\n"; 40 return; 41 } 42 43 $handles = []; // 個々の cURL ハンドルを格納する配列 44 45 // 各URLに対して個別の cURL ハンドルを作成し、マルチハンドルに追加します。 46 foreach ($urls as $url) { 47 $ch = curl_init(); 48 if ($ch === false) { 49 echo "エラー: URL '{$url}' の cURL ハンドル初期化に失敗しました。\n"; 50 continue; 51 } 52 53 // cURL オプションを設定します。 54 curl_setopt($ch, CURLOPT_URL, $url); // 取得するURL 55 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // レスポンスを文字列で返す設定 (表示用) 56 curl_setopt($ch, CURLOPT_HEADER, false); // レスポンスヘッダは取得しない 57 58 // CURL_FNMATCHFUNC_MATCH の利用例を示すための設定です。 59 // 注意: `CURLOPT_FNMATCH_FUNCTION` は主にFTPなどのファイル転送プロトコルで 60 // ワイルドカードを扱う際に利用され、HTTPリクエストでは通常は効果がありません。 61 // このサンプルでは、リファレンス情報にある定数の存在と、それがコールバック関数の 62 // 戻り値として利用される可能性を示すために設定しています。 63 curl_setopt($ch, CURLOPT_FNMATCH_FUNCTION, 'myFnmatchCallback'); 64 65 // 個々の cURL ハンドルをマルチハンドルに追加します。 66 curl_multi_add_handle($multi_handle, $ch); 67 $handles[] = $ch; 68 } 69 70 // すべてのリクエストが完了するまで、`curl_multi_exec` をループで呼び出します。 71 $running = null; // アクティブな cURL ハンドルの数を格納 72 do { 73 // `curl_multi_exec` は、保留中の cURL ハンドルを処理します。 74 // これは、C言語の libcurl ライブラリにおける `curl_multi_perform()` に相当する PHP の関数です。 75 $status = curl_multi_exec($multi_handle, $running); 76 77 if ($status === CURLM_CALL_MULTI_PERFORM) { 78 // `curl_multi_exec` を直ちに再度呼び出す必要がある場合、ループを続行します。 79 continue; 80 } 81 82 // アクティブなハンドルがあり、エラーがない場合、ソケットのイベントを待機してCPU負荷を軽減します。 83 if ($running > 0 && $status === CURLM_OK) { 84 curl_multi_select($multi_handle, 1.0); // 最大1.0秒待機 85 } 86 } while ($running > 0); // アクティブなハンドルがなくなるまで繰り返します。 87 88 // 各 cURL ハンドルの結果を取得し、クリーンアップします。 89 foreach ($handles as $ch) { 90 $info = curl_getinfo($ch); // cURL 転送の情報を取得 91 $content = curl_multi_getcontent($ch); // リクエストのレスポンス本文を取得 92 93 echo "--- URL: " . $info['url'] . " ---\n"; 94 if ($content === false) { 95 echo " エラー: " . curl_error($ch) . "\n"; 96 } else { 97 echo " HTTP ステータスコード: " . $info['http_code'] . "\n"; 98 // 初心者向けに、取得したコンテンツの最初の100文字のみ表示します。 99 echo " コンテンツの冒頭 (100文字): " . substr($content, 0, 100) . "...\n"; 100 } 101 // 各 cURL ハンドルをマルチハンドルから削除し、クローズします。 102 curl_multi_remove_handle($multi_handle, $ch); 103 curl_close($ch); 104 } 105 106 // マルチハンドルをクローズします。 107 curl_multi_close($multi_handle); 108} 109 110// --- サンプル使用例 --- 111$targetUrls = [ 112 'https://www.example.com', 113 'https://www.php.net', 114 'https://www.google.com', 115]; 116 117// 関数を実行して、複数の cURL リクエストを並行処理します。 118performMultiCurlWithFnMatch($targetUrls); 119 120?>
このPHPサンプルコードは、cURL拡張機能で利用されるCURL_FNMATCHFUNC_MATCH定数と、複数のcURLリクエストを並行処理する方法を示しています。
CURL_FNMATCHFUNC_MATCHは、主にFTPなどのファイル転送プロトコルにおいて、ワイルドカードを含むファイル名がパターンにマッチした際に、CURLOPT_FNMATCH_FUNCTIONオプションで設定されたコールバック関数が戻り値として返す定数です。コールバック関数myFnmatchCallbackは、CurlHandle、マッチング対象のファイル名（string $filename）、マッチングパターン（string $pattern）を受け取り、ファイルがパターンにマッチしたと判断した場合にCURL_FNMATCHFUNC_MATCHの値を整数型（int）で返します。
performMultiCurlWithFnMatch関数は、複数のURLに対して同時にcURLリクエストを実行します。curl_multi_initでマルチハンドルを作成し、各URL用のcURLハンドルにオプションを設定後、マルチハンドルに追加します。リクエストの実行にはcurl_multi_execを使用し、これはC言語のcurlm_call_multi_performに相当し、複数の転送を効率的に管理します。すべてのリクエストが完了すると、各ハンドルの結果を取得し、適切にクローズされます。なお、CURL_FNMATCHFUNC_MATCHはHTTPリクエストでは通常使用されませんが、定数の利用方法を示すために例として含まれています。
CURL_FNMATCHFUNC_MATCH定数は、主にFTPなどのファイル転送プロトコルにおけるワイルドカードマッチング機能で利用されるものです。そのため、HTTPリクエストでこの定数を用いたコールバック関数を設定しても、通常は期待する効果を発揮しない点にご注意ください。このサンプルは定数の利用方法を示す目的で含められています。
複数のcURLリクエストを並行処理するcurl_multi_exec関数は、すべての処理が完了するまでループ内で繰り返し呼び出す必要があります。CURLM_CALL_MULTI_PERFORMが返された場合は、処理を滞りなく進めるために、すぐにcurl_multi_execを再度呼び出すようにしてください。また、curl_multi_select関数を使用することで、リクエストの完了を待機する間のCPU使用率を抑え、効率的な並行処理を実現できます。
PHP cURLマルチで非同期リクエストする
1<?php 2 3/** 4 * 複数のURLに対して非同期にHTTP GETリクエストを送信し、結果を取得します。 5 * curl_multi_select を使用して、データ転送の準備ができたソケットを効率的に待機します。 6 * 7 * @param array $urls リクエストを送信するURLの配列。例: ['http://example.com/api', 'http://another.com/data'] 8 * @return array 各URLをキーとし、それに対応するレスポンスボディを値とする連想配列。 9 * エラーが発生した場合は、そのURLのコンテンツは空文字列になることがあります。 10 */ 11function fetchMultipleUrlsAsync(array $urls): array 12{ 13 // cURLマルチハンドルの初期化 14 $mh = curl_multi_init(); 15 $ch = []; // 個々のcURLハンドルの配列 16 17 // 各URLに対してcURLハンドルを作成し、マルチハンドルに追加 18 foreach ($urls as $key => $url) { 19 $ch[$key] = curl_init($url); 20 curl_setopt($ch[$key], CURLOPT_RETURNTRANSFER, true); // レスポンスを文字列として取得 21 curl_setopt($ch[$key], CURLOPT_HEADER, false); // レスポンスヘッダーを含めない 22 curl_multi_add_handle($mh, $ch[$key]); 23 } 24 25 $running = null; // 実行中のcURLハンドル数を追跡するための変数 26 $responses = []; // 各URLからのレスポンスを格納する配列 27 28 // 全てのリクエストが完了するまでループ 29 do { 30 // cURLアクティビティを継続し、データ転送を試みる 31 // curl_multi_exec は、実行中のハンドルが残っている場合、CURLM_CALL_MULTI_PERFORM を返すことがあります。 32 do { 33 $mrc = curl_multi_exec($mh, $running); 34 } while ($mrc == CURLM_CALL_MULTI_PERFORM); 35 36 // $running が0より大きい場合（まだリクエストが残っている場合）のみ待機 37 if ($running > 0) { 38 // curl_multi_select は、データ転送の準備ができたソケットを待機します。 39 // ここで0.1秒のタイムアウトを設定しています。 40 // CURL_FNMATCHFUNC_MATCH は、curl_multi_setopt(CURLMOPT_FNMATCH_FUNCTION, ...) で設定される 41 // コールバック関数内で、パターンマッチが成功したことを示すために使われる定数です。 42 // このサンプルではファイル名パターンマッチングを行わないため、直接使用していません。 43 $select_status = curl_multi_select($mh, 0.1); 44 if ($select_status === -1) { 45 // selectエラーが発生した場合など、selectがすぐに返ってきた場合は短い間隔でポーリング 46 usleep(10000); // 10ミリ秒待機 47 } 48 } 49 } while ($running > 0 && $mrc == CURLM_OK); // 実行中のハンドルがあり、かつエラーがない限り継続 50 51 // 各ハンドルの結果を取得し、クローズ 52 foreach ($ch as $key => $handle) { 53 $responses[$urls[$key]] = curl_multi_getcontent($handle); 54 curl_multi_remove_handle($mh, $handle); // マルチハンドルから削除 55 curl_close($handle); // 個々のcURLハンドルをクローズ 56 } 57 58 curl_multi_close($mh); // cURLマルチハンドルをクローズ 59 60 return $responses; 61} 62 63// --- サンプルコードの使用例 --- 64// 複数のURLを指定。中には意図的に遅延するURLを含めて、非同期処理の効果を確認します。 65$targetUrls = [ 66 'https://httpbin.org/get?id=1', 67 'https://httpbin.org/delay/1', // 1秒遅延するURL 68 'https://httpbin.org/status/200', 69 'https://httpbin.org/get?id=2', 70 'https://httpbin.org/get?id=3', 71]; 72 73echo "複数のURLへ非同期リクエストを開始...\n"; 74$startTime = microtime(true); 75 76$results = fetchMultipleUrlsAsync($targetUrls); 77 78$endTime = microtime(true); 79echo "全リクエスト完了。所要時間: " . round($endTime - $startTime, 2) . "秒\n\n"; 80 81foreach ($results as $url => $content) { 82 echo "URL: " . $url . "\n"; 83 // 実際のコンテンツを表示すると長くなる可能性があるため、長さを制限して表示 84 echo "Content (first 100 chars): " . substr((string)$content, 0, 100) . "...\n"; 85 echo "Content Length: " . strlen((string)$content) . " bytes\n"; 86 echo "--------------------------\n"; 87}
このPHPサンプルコードは、cURL拡張機能を利用して複数のURLへHTTP GETリクエストを非同期で送信し、その結果を効率的に取得するfetchMultipleUrlsAsync関数を示しています。これにより、複数のリクエストを並行して処理できるため、全体の実行時間を短縮できます。
関数内では、まずcurl_multi_init()で複数のcURLリクエストを管理するマルチハンドルを初期化します。次に、指定された各URLに対して個別のcURLハンドルを作成し、レスポンスを文字列として取得するよう設定した後、これらをマルチハンドルに追加します。
データ転送はループ内でcurl_multi_exec()を繰り返し実行することで進められます。この際、curl_multi_select()関数が重要な役割を果たします。これは、データ転送の準備ができたソケットが発生するまで、CPUを消費せずに効率的に待機するための機能です。引数には最大待機秒数を指定でき、このサンプルでは0.1秒に設定されています。これにより、ネットワークI/Oイベントを待ちながら、他の処理を阻害することなく進行できます。
全てのリクエストが完了すると、各ハンドルからcurl_multi_getcontent()でレスポンスボディを取得し、すべてのcURLハンドルを適切にクローズします。fetchMultipleUrlsAsyncは、リクエスト対象のURL配列を引数として受け取り、各URLをキー、対応するレスポンスボディを値とする連想配列を戻り値として返します。
なお、CURL_FNMATCHFUNC_MATCH定数は、curl_multi_setoptでファイル名パターンマッチング用コールバック関数が設定された際に、パターンが成功したことを示すために使用される定数です。このサンプルコードではファイル名パターンマッチングを行わないため、直接は使用されていません。
CURL_FNMATCHFUNC_MATCH定数は、サンプルコードで直接使われていませんが、CURLMOPT_FNMATCH_FUNCTIONオプションで設定するファイル名パターンマッチング機能のコールバック内で、成功を示す際に利用されるものです。curl_multi_selectは、非同期通信でソケットの準備を効率的に待機する重要な関数です。タイムアウト値はシステムの応答性とCPU負荷に影響するため、環境や要件に合わせて調整が必要です。curl_multi_execはCURLM_CALL_MULTI_PERFORMを返す間は繰り返し実行する必要がある点にご注意ください。処理完了後は、個々のcURLハンドルとマルチハンドルを忘れずにクローズし、リソースを適切に解放することが重要です。また、通信エラー発生時の具体的なエラーハンドリングを追加し、より堅牢なコードを目指しましょう。