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

Copy
1<?php
2
3/**
4 * Fetches multiple URLs concurrently, only if they have NOT been modified since a specific timestamp.
5 *
6 * This function demonstrates the use of CURL_TIMECOND_IFUNMODSINCE within a multi-cURL context,
7 * which is an efficient way to make parallel HTTP requests.
8 *
9 * @param array $urls An array of URLs to fetch.
10 * @param int $ifUnmodifiedSinceTimestamp Unix timestamp. Resources will only be fetched
11 *                                       if their modification time is earlier than or equal to this timestamp.
12 *                                       If a resource has been modified *after* this timestamp,
13 *                                       the server might respond with a 412 Precondition Failed.
14 * @return array An associative array where keys are URLs and values are the fetched content
15 *               or an error message if an error occurred.
16 */
17function fetchUrlsConditionallyMulti(array $urls, int $ifUnmodifiedSinceTimestamp): array
18{
19    // Initialize the cURL multi handle for parallel requests.
20    $mh = curl_multi_init();
21    $chHandles = []; // Stores individual cURL handles.
22    $results = [];   // Stores the fetched content or error messages.
23
24    foreach ($urls as $id => $url) {
25        // Initialize a cURL handle for each URL.
26        $ch = curl_init();
27        curl_setopt($ch, CURLOPT_URL, $url);
28        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return the transfer as a string.
29
30        // --- Core part: Using CURL_TIMECOND_IFUNMODSINCE ---
31        // Sets the time condition for the request.
32        // The resource will only be fetched if it has NOT been modified AFTER the given time.
33        curl_setopt($ch, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFUNMODSINCE);
34        // Sets the specific Unix timestamp for the condition.
35        curl_setopt($ch, CURLOPT_TIMEVALUE, $ifUnmodifiedSinceTimestamp);
36        // --- End of core part ---
37
38        // Add the individual cURL handle to the multi handle.
39        curl_multi_add_handle($mh, $ch);
40        $chHandles[$id] = $ch; // Store the handle for later retrieval of results.
41    }
42
43    // Execute all cURL requests in parallel.
44    $running = null;
45    do {
46        // Perform the cURL requests.
47        curl_multi_exec($mh, $running);
48        // Wait for activity on any connection if there are still running requests.
49        if ($running > 0) {
50            curl_multi_select($mh);
51        }
52    } while ($running > 0); // Loop while there are still active requests.
53
54    // Collect the results from each individual handle.
55    foreach ($chHandles as $id => $ch) {
56        $url = $urls[$id];
57        $content = curl_multi_getcontent($ch);
58        $error = curl_error($ch);
59
60        if ($error) {
61            $results[$url] = "Error fetching {$url}: " . $error;
62        } else {
63            // Content might be empty or a 412 response if the condition was not met
64            // and the server correctly implemented the If-Unmodified-Since header.
65            $results[$url] = $content;
66        }
67
68        // Remove and close the individual cURL handle.
69        curl_multi_remove_handle($mh, $ch);
70        curl_close($ch);
71    }
72
73    // Close the cURL multi handle.
74    curl_multi_close($mh);
75
76    return $results;
77}
78
79// --- Example Usage ---
80// This block ensures the example runs only when the script is executed directly via CLI.
81if (php_sapi_name() === 'cli') {
82    $targetUrls = [
83        'https://example.com',
84        'https://www.google.com',
85    ];
86
87    // Define a timestamp (e.g., 1 hour ago).
88    // The server is requested to return content only if it has NOT been modified since this time.
89    $oneHourAgo = time() - 3600;
90    echo "Fetching URLs using CURL_TIMECOND_IFUNMODSINCE (timestamp: " . date('Y-m-d H:i:s', $oneHourAgo) . "):\n";
91    $fetchedContent = fetchUrlsConditionallyMulti($targetUrls, $oneHourAgo);
92
93    foreach ($fetchedContent as $url => $content) {
94        echo "--- " . $url . " ---\n";
95        // Show only a snippet of content for brevity.
96        echo substr($content, 0, 200) . "...\n\n";
97    }
98
99    // Demonstrating with a future timestamp (e.g., 1 hour in the future).
100    // Most resources would not have been modified since a future time, so the condition
101    // should generally allow fetching content without triggering a 412.
102    $oneHourFuture = time() + 3600;
103    echo "Fetching URLs using CURL_TIMECOND_IFUNMODSINCE (timestamp: " . date('Y-m-d H:i:s', $oneHourFuture) . "):\n";
104    $fetchedContentFuture = fetchUrlsConditionallyMulti($targetUrls, $oneHourFuture);
105
106    foreach ($fetchedContentFuture as $url => $content) {
107        echo "--- " . $url . " ---\n";
108        echo substr($content, 0, 200) . "...\n\n";
109    }
110}

このPHPサンプルコードは、複数のURLに対してHTTPリクエストを並行して実行し、特定の条件を満たす場合にのみコンテンツを取得するfetchUrlsConditionallyMulti関数を説明しています。主要な機能は、CURL_TIMECOND_IFUNMODSINCE定数とCURLOPT_TIMEVALUEオプションを組み合わせて使用する点です。

CURL_TIMECOND_IFUNMODSINCEは、CURLOPT_TIMEVALUEオプションで指定されたUnixタイムスタンプ以降にウェブサイトのコンテンツが更新されていない場合に限り、そのコンテンツを取得するという条件を設定するために利用されます。これにより、サーバーへの不要な負荷を減らし、既に手元にある情報が最新である場合に再度ダウンロードする手間を省くことができます。

関数はまず、curl_multi_init()で並行リクエストのためのマルチcURLハンドルを初期化します。次に、引数$urlsで渡された各URLに対し、個別のcURLハンドルを作成し、CURLOPT_TIMECONDITIONにCURL_TIMECOND_IFUNMODSINCEを、引数$ifUnmodifiedSinceTimestampで渡されたUnixタイムスタンプをCURLOPT_TIMEVALUEに設定します。これにより、更新されていない場合にのみ取得する条件が適用されます。これらの個々のハンドルはcurl_multi_add_handle()でマルチハンドルに追加されます。

全てのリクエストはcurl_multi_exec()とcurl_multi_select()によって並行して実行され、完了するまで待機します。処理が完了すると、curl_multi_getcontent()で各URLから取得したコンテンツやエラーメッセージを収集し、URLをキー、取得したコンテンツまたはエラーメッセージを値とする連想配列として返します。条件に合致しなかった場合は、サーバーの応答に応じて空のコンテンツやHTTPステータスコード412（Precondition Failed）などが含まれることがあります。

Copy
1<?php
2
3/**
4 * 指定されたURLからデータを取得します。
5 * 接続および実行のタイムアウトを設定し、さらに指定された時刻以降に
6 * リソースが変更されていない場合にのみデータを取得する条件付きリクエストを行います。
7 *
8 * @param string $url データを取得するターゲットURL。
9 * @return string 取得したデータ、またはエラーメッセージ。
10 */
11function fetchUrlContentWithTimeoutAndConditionalRequest(string $url): string
12{
13    // cURLリソースを初期化します。
14    $ch = curl_init();
15
16    // リクエストのターゲットURLを設定します。
17    curl_setopt($ch, CURLOPT_URL, $url);
18
19    // 接続タイムアウトを設定します (秒単位)。
20    // この時間内にサーバーへのTCP接続が確立できない場合、cURLはエラーを返します。
21    // システムエンジニアにとって、ネットワークの問題によるハングアップを防ぐために重要です。
22    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5); // 例: 5秒
23
24    // 全体の実行タイムアウトを設定します (秒単位)。
25    // 接続からデータ転送完了までの総時間を制限します。
26    // この時間内に操作が完了しない場合、cURLはエラーを返します。
27    // 遅い応答のAPIなどから保護するために使用されます。
28    curl_setopt($ch, CURLOPT_TIMEOUT, 10); // 例: 10秒
29
30    // 取得したデータをブラウザに出力せず、文字列として関数から返却するように設定します。
31    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
32
33    // HTTPヘッダーをレスポンスに含めないように設定します（通常、コンテンツのみが必要な場合）。
34    curl_setopt($ch, CURLOPT_HEADER, false);
35
36    // 条件付きGETリクエストを設定します。
37    // CURL_TIMECOND_IFUNMODSINCE は、CURLOPT_TIMECONDITION オプションで使われる定数です。
38    // これは、指定された日時 (CURLOPT_TIMEVALUE) 以降にリソースが変更されていない場合、
39    // サーバーがコンテンツを再送せず、HTTP 304 Not Modified ステータスを返すように要求します。
40    // これにより、不必要なデータ転送を避け、帯域幅の節約とパフォーマンスの向上が期待できます。
41    $oneHourAgo = strtotime('-1 hour'); // 例: 現在時刻の1時間前のUnixタイムスタンプ
42    curl_setopt($ch, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFUNMODSINCE);
43    curl_setopt($ch, CURLOPT_TIMEVALUE, $oneHourAgo);
44
45    // HTTPSを使用している場合、SSL証明書の検証を無効にする設定。
46    // 開発環境では便利ですが、本番環境ではセキュリティリスクが高まるため非推奨です。
47    // 本番環境では、信頼できる証明書を使用して適切に検証するように設定してください。
48    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
49    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
50
51    // cURLリクエストを実行し、レスポンスを取得します。
52    $response = curl_exec($ch);
53
54    // cURL実行中にエラーが発生したかチェックします。
55    if (curl_errno($ch)) {
56        $errorMsg = 'cURLエラー (' . curl_errno($ch) . '): ' . curl_error($ch);
57        curl_close($ch); // エラーが発生した場合はリソースをすぐに解放
58        return 'エラー: ' . $errorMsg;
59    }
60
61    // HTTPステータスコードを取得します。
62    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
63
64    // cURLリソースを解放します。
65    curl_close($ch);
66
67    // HTTP 304 Not Modified ステータスコードの場合、コンテンツは指定された時刻以降変更されていないことを示します。
68    if ($httpCode === 304) {
69        return "コンテンツは変更されていません (HTTP 304 Not Modified)。";
70    }
71
72    // 取得したコンテンツとHTTPステータスコードを返します。
73    return "取得成功 (HTTP " . $httpCode . "):\n" . $response;
74}
75
76// --- サンプル使用例 ---
77// 実際にコンテンツが存在するURLに置き換えてください。
78// 例: 'https://www.google.com' や 'https://api.example.com/data' など
79$targetUrl = 'https://example.com';
80
81// 設定されたタイムアウトと条件付きリクエストでURLコンテンツを取得します。
82$content = fetchUrlContentWithTimeoutAndConditionalRequest($targetUrl);
83
84// 結果を出力します。
85echo $content;
86
87?>

このPHPサンプルコードは、fetchUrlContentWithTimeoutAndConditionalRequest関数を通じて、指定されたURLからデータを安全かつ効率的に取得する方法を示しています。この関数は、PHPのcURL拡張機能を利用してHTTPリクエストを送信します。

まず、ネットワーク接続の安定性を確保するため、接続タイムアウトと全体の実行タイムアウトを設定しています。CURLOPT_CONNECTTIMEOUTでサーバーへの接続にかかる上限時間、CURLOPT_TIMEOUTで接続からデータ転送完了までの総時間の上限を設定することで、ネットワークの遅延や応答の遅いサーバーによるプログラムの長時間停止を防ぎます。これはシステムエンジニアにとって、信頼性の高いシステムを構築するために不可欠な設定です。

次に、CURL_TIMECOND_IFUNMODSINCE定数を使用して、条件付きGETリクエストを行います。この設定とCURLOPT_TIMEVALUEで指定された日時（例として1時間前）以降にリソースが変更されていない場合、サーバーはコンテンツの再送を避け、HTTP 304 Not Modified ステータスコードを返します。これにより、不要なデータ転送を削減し、ネットワーク帯域の節約とアプリケーションのパフォーマンス向上に繋がります。

この関数は、引数として取得対象のURL（string $url）を受け取ります。成功時には取得したデータ文字列、コンテンツが変更されていない場合はその旨を示す文字列、エラーが発生した場合はエラーメッセージを文字列（string）として返します。コードには開発環境向けのSSL証明書検証無効化設定も含まれますが、本番環境ではセキュリティ上の理由から適切な検証設定が必要です。