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

Copy
1<?php
2
3/**
4 * 指定されたURLにHTTP GETリクエストを送り、タイムアウトを設定します。
5 * システムエンジニアを目指す初心者向けに、cURLを使った基本的なリクエストと
6 * タイムアウト設定の方法を示します。
7 *
8 * @param string $url リクエストを送信するURL。
9 * @param int $timeout 全体的な操作のタイムアウト時間（秒）。0は無限。
10 * @param int $connectTimeout 接続試行のタイムアウト時間（秒）。
11 * @return string|false 成功した場合はレスポンスボディ、失敗した場合はfalseを返します。
12 */
13function fetchDataWithTimeout(string $url, int $timeout = 10, int $connectTimeout = 5): string|false
14{
15    // cURLセッションを初期化します。
16    // これからHTTPリクエストを行うためのハンドルを取得します。
17    $ch = curl_init();
18
19    // cURLオプションを設定します。
20    // CURLOPT_URL: リクエスト先のURLを指定します。
21    curl_setopt($ch, CURLOPT_URL, $url);
22
23    // CURLOPT_RETURNTRANSFER: curl_exec() が結果を直接出力せず、文字列として返すようにします。
24    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
25
26    // CURLOPT_TIMEOUT: cURL操作全体のタイムアウト時間を秒単位で設定します。
27    // この時間内にデータ転送が完了しない場合、操作は中断されます。
28    curl_setopt($ch, CURLOPT_TIMEOUT, $timeout);
29
30    // CURLOPT_CONNECTTIMEOUT: 接続試行のタイムアウト時間を秒単位で設定します。
31    // この時間内にサーバーへの接続が確立できない場合、操作は中断されます。
32    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $connectTimeout);
33
34    // CURLOPT_HEADER: HTTPレスポンスヘッダをレスポンスボディに含めないようにします。
35    curl_setopt($ch, CURLOPT_HEADER, false);
36
37    // cURLセッションを実行し、結果を取得します。
38    $response = curl_exec($ch);
39
40    // エラーチェックを行います。
41    // curl_errno() は最後に発生したcURLエラー番号を返します。
42    if (curl_errno($ch)) {
43        // エラーが発生した場合、エラーメッセージをログに出力します。
44        // curl_error() は最後に発生したcURLエラーの文字列を返します。
45        error_log('cURLエラー発生: ' . curl_error($ch));
46        $response = false; // エラー時はfalseを返します。
47    }
48
49    // cURLセッションを終了し、リソースを解放します。
50    curl_close($ch);
51
52    return $response;
53}
54
55// --- 使用例 ---
56// 実際のHTTPリクエストを送信するURLに置き換えてください。
57$targetUrl = 'https://www.example.com/'; 
58
59echo "対象URL: " . $targetUrl . "\n";
60
61// fetchDataWithTimeout関数を呼び出し、データ取得を試みます。
62// 全体タイムアウトを10秒、接続タイムアウトを5秒に設定しています。
63echo "データ取得を試行中 (全体タイムアウト: 10秒, 接続タイムアウト: 5秒)...\n";
64$data = fetchDataWithTimeout($targetUrl, 10, 5);
65
66if ($data !== false) {
67    echo "データ取得に成功しました。先頭200文字を表示します。\n";
68    echo substr($data, 0, 200) . "...\n"; // 取得したデータの先頭200文字のみ表示
69} else {
70    echo "データ取得に失敗しました。タイムアウトが発生した可能性があります。\n";
71}
72
73// 短いタイムアウトで失敗する可能性のある例 (必要に応じてコメント解除して試してください)
74// echo "\n短いタイムアウトでデータ取得を試行中 (全体タイムアウト: 1秒, 接続タイムアウト: 0.5秒)...\n";
75// $shortTimeoutData = fetchDataWithTimeout($targetUrl, 1, 0.5);
76// if ($shortTimeoutData !== false) {
77//     echo "短いタイムアウトでもデータ取得成功。\n";
78// } else {
79//     echo "短いタイムアウトでデータ取得失敗（タイムアウトした可能性が高い）。\n";
80// }
81

このPHPサンプルコードは、cURLというライブラリを使用して、指定されたURLへHTTP GETリクエストを送信し、データ取得時のタイムアウトを設定する方法を学ぶためのものです。システムエンジニアを目指す初心者の方にとって、外部サービスとの連携における基本的な技術となります。

fetchDataWithTimeout関数は、まずcurl_init()でcURLセッションを初期化し、curl_setopt()で様々なオプションを設定します。特に、CURLOPT_URLでリクエスト先のURLを、CURLOPT_RETURNTRANSFERでHTTPレスポンスを文字列として取得する設定を行います。

タイムアウトの設定は非常に重要です。CURLOPT_TIMEOUTはデータ転送を含む操作全体のタイムアウト時間（秒）を設定し、この時間内に完了しない場合は操作が中断されます。一方、CURLOPT_CONNECTTIMEOUTは、サーバーへの接続確立に要するタイムアウト時間（秒）を設定します。これらを設定することで、ネットワークの遅延などによりプログラムが長時間停止するのを防ぐことができます。

curl_exec()でリクエストを実行し、その結果を取得します。エラーが発生した場合はcurl_errno()やcurl_error()で詳細を確認し、curl_close()でセッションを終了します。

この関数の引数$urlはリクエスト先のURL、$timeoutは全体タイムアウト、$connectTimeoutは接続タイムアウトを表し、それぞれ秒単位の整数で指定します。戻り値は、成功時には取得したレスポンスボディの文字列、失敗時にはfalseを返します。これにより、プログラムはタイムアウトやエラー時に適切に対応できるようになります。

Copy
1<?php
2
3/**
4 * 複数のcURLリクエストを並行して実行し、そのうちの一つで
5 * CURL_TIMECOND_IFMODSINCE を使用するサンプル関数。
6 *
7 * システムエンジニアを目指す初心者向けに、
8 * 複数のHTTPリクエストを効率的に処理する方法と、
9 * 条件付きリクエスト（リソースが更新されていない場合に再ダウンロードを避ける）
10 * の基本的な使い方を示します。
11 */
12function perform_multi_curl_with_time_condition(): void
13{
14    // cURLマルチハンドルの初期化
15    // これにより、複数のcURLリクエストを並行して実行できるようになります。
16    $multi_handle = curl_multi_init();
17
18    // 個々のcURLハンドルを準備
19    // 各ハンドルが独立したHTTPリクエストを表します。
20    $ch1 = curl_init();
21    $ch2 = curl_init();
22
23    // --- ハンドル1の設定（CURL_TIMECOND_IFMODSINCEを使用） ---
24    // ここでは架空のURLを使用しています。実際にはアクセス可能なURLに置き換えてください。
25    // このURLがHTTPの条件付きGET (If-Modified-Since) をサポートしていると、
26    // 実際に304 Not Modified レスポンスを受け取ることができます。
27    curl_setopt($ch1, CURLOPT_URL, "https://www.example.com/api/data1");
28    curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true); // レスポンスを文字列として取得する設定
29
30    // CURL_TIMECONDITION は、リクエストに条件付きGETヘッダを追加するためのオプションです。
31    // CURL_TIMECOND_IFMODSINCE は、指定したタイムスタンプ以降にリソースが変更されていない場合に
32    // コンテンツをダウンロードしないようサーバーに要求します (HTTP If-Modified-Sinceヘッダに相当)。
33    curl_setopt($ch1, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE);
34    // CURLOPT_TIMEVALUE には、条件の基準となるUnixタイムスタンプを指定します。
35    // ここでは、現在時刻から24時間前のタイムスタンプを設定しています。
36    // これにより、「もしこのリソースが24時間以内に変更されていなければ、送ってこないでほしい」
37    // というリクエストになります。
38    curl_setopt($ch1, CURLOPT_TIMEVALUE, time() - (24 * 60 * 60)); // 24時間前のタイムスタンプ
39
40    // --- ハンドル2の設定（一般的なGETリクエスト） ---
41    // こちらは特に条件をつけず、通常のGETリクエストとして設定します。
42    curl_setopt($ch2, CURLOPT_URL, "https://www.example.com/api/data2");
43    curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true); // レスポンスを文字列として取得する設定
44
45    // 各cURLハンドルをマルチハンドルに追加
46    // これにより、これら2つのリクエストを並行して処理できるようになります。
47    curl_multi_add_handle($multi_handle, $ch1);
48    curl_multi_add_handle($multi_handle, $ch2);
49
50    $running_handles = null; // 現在アクティブなハンドルの数を追跡する変数
51    $all_handles = [$ch1, $ch2]; // 後でクリーンアップするために全てのハンドルを保持
52
53    // 全てのリクエストが完了するまでループを実行
54    do {
55        // curl_multi_exec は、マルチハンドル内の全てのリクエストを非同期に実行します。
56        // 第2引数 $running_handles には、まだ処理中のハンドルの数が設定されます。
57        curl_multi_exec($multi_handle, $running_handles);
58
59        // アクティブなハンドルがある間は、I/O イベントを待機してCPU使用率を抑えます。
60        // curl_multi_select は、データが利用可能になるか、タイムアウトするまでブロックします。
61        if ($running_handles > 0) {
62            curl_multi_select($multi_handle);
63        }
64
65    } while ($running_handles > 0); // アクティブなハンドルがなくなるまでループを続行
66
67    // --- 結果の取得と表示 ---
68
69    echo "--- リソース1の結果 (CURL_TIMECOND_IFMODSINCE) ---\n";
70    $response1 = curl_multi_getcontent($ch1); // 完了したリクエストのレスポンスを取得
71    $http_code1 = curl_getinfo($ch1, CURLINFO_HTTP_CODE); // HTTPステータスコードを取得
72    echo "HTTPステータスコード: " . $http_code1 . "\n";
73    if ($http_code1 === 304) {
74        echo "リソースは指定した時刻以降に変更されていません。ダウンロードはスキップされました。\n";
75    } else {
76        echo "レスポンスの長さ: " . strlen($response1) . " バイト\n";
77        // echo "レスポンスボディの一部: " . substr($response1, 0, 200) . "...\n"; // 長いレスポンスの一部を表示する場合
78    }
79    echo "\n";
80
81    echo "--- リソース2の結果 (通常のGET) ---\n";
82    $response2 = curl_multi_getcontent($ch2);
83    $http_code2 = curl_getinfo($ch2, CURLINFO_HTTP_CODE);
84    echo "HTTPステータスコード: " . $http_code2 . "\n";
85    echo "レスポンスの長さ: " . strlen($response2) . " バイト\n";
86    // echo "レスポンスボディの一部: " . substr($response2, 0, 200) . "...\n";
87    echo "\n";
88
89    // --- 後処理（リソースの解放） ---
90    // 各cURLハンドルをマルチハンドルから削除し、個別に閉じます。
91    foreach ($all_handles as $ch) {
92        curl_multi_remove_handle($multi_handle, $ch);
93        curl_close($ch);
94    }
95    // 最後にマルチハンドル自体を閉じます。
96    curl_multi_close($multi_handle);
97
98    echo "全てのcURL操作が完了しました。\n";
99}
100
101// 関数を実行
102perform_multi_curl_with_time_condition();

PHPのCURL_TIMECOND_IFMODSINCE定数は、cURLを利用してHTTPリクエストを送信する際に、リソースの条件付き取得を行うための設定値です。この定数自体には引数や戻り値はありませんが、curl_setopt関数でCURLOPT_TIMECONDITIONオプションに指定することで、特定の日時以降にリソースが更新された場合にのみコンテンツをダウンロードするようサーバーに要求できます。これはHTTPの「If-Modified-Since」ヘッダに対応し、指定した日時（CURLOPT_TIMEVALUEオプションで設定）以降に変更がない場合、サーバーは「304 Not Modified」というステータスコードを返し、コンテンツの再送信を避けます。これにより、不要なデータ転送を削減し、ネットワーク帯域と処理負荷を効率化することが可能です。

提示されたサンプルコードは、curl_multi_initおよび関連関数を使って複数のHTTPリクエストを並行して実行する方法を示しています。一つのリクエストではCURL_TIMECOND_IFMODSINCEを設定し、過去のある時点以降に変更がなければダウンロードしないよう指定しています。もう一つのリクエストは通常のダウンロードとして実行され、両者の結果を比較できます。curl_multi_execが非同期でリクエストを処理し、curl_multi_selectで効率的に待機しながら、すべてのリクエストが完了するまで処理を進めます。最終的に各リクエストのHTTPステータスコードやレスポンスを確認し、リソースを解放する流れが示されています。