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

Copy
1<?php
2
3/**
4 * 指定されたURLから条件付きでコンテンツを取得し、転送タイムアウトを設定する関数。
5 *
6 * この関数は、cURLライブラリを使用してHTTPリクエストを送信します。
7 * `CURLOPT_TIMEOUT` オプションで全体の転送時間を制限し、
8 * `CURL_TIMECOND_LASTMOD` 定数を使用して最終更新日時以降に
9 * コンテンツが更新された場合のみ取得するよう設定できます。
10 *
11 * @param string $url 取得するURL。
12 * @param int $timeout 転送全体の最大タイムアウト秒数。
13 * @param int|null $ifModifiedSince UNIXタイムスタンプ。この日時以降にコンテンツが更新された場合にのみ取得を試みます。
14 *                                  nullの場合、条件付きGETは使用されません。
15 * @return string|false 取得したコンテンツ（HTTP 200の場合）、
16 *                      コンテンツが更新されていない場合（HTTP 304）は空文字列、
17 *                      失敗した場合は false を返します。
18 */
19function fetchUrlWithConditionalGetAndTimeout(string $url, int $timeout, ?int $ifModifiedSince = null): string|false
20{
21    // cURLセッションを初期化
22    $ch = curl_init();
23
24    if ($ch === false) {
25        // cURLの初期化に失敗した場合、エラーを記録してfalseを返す
26        error_log("cURLセッションの初期化に失敗しました。");
27        return false;
28    }
29
30    // 取得するURLを設定
31    curl_setopt($ch, CURLOPT_URL, $url);
32
33    // 取得したデータを文字列として返すように設定
34    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
35
36    // 転送全体のタイムアウトを秒数で設定
37    // この時間内に転送が完了しない場合、cURLはエラーを返します
38    curl_setopt($ch, CURLOPT_TIMEOUT, $timeout);
39
40    // 接続試行のタイムアウトも設定すると、より細かく制御できます
41    // curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5); // 接続フェーズのタイムアウトを5秒に設定
42
43    // 条件付きGETを設定 (CURL_TIMECOND_LASTMOD を使用)
44    if ($ifModifiedSince !== null) {
45        // CURLOPT_TIMECONDITION を CURL_TIMECOND_LASTMOD に設定することで、
46        // `If-Modified-Since` ヘッダーが送信され、指定された日時以降に
47        // サーバー上のリソースが更新された場合にのみコンテンツが転送されます。
48        curl_setopt($ch, CURLOPT_TIMECONDITION, CURL_TIMECOND_LASTMOD);
49        // CURLOPT_TIMEVALUE で基準となるUNIXタイムスタンプを指定します
50        curl_setopt($ch, CURLOPT_TIMEVALUE, $ifModifiedSince);
51    }
52
53    // SSL証明書の検証を無効にする設定 (開発環境などでのみ使用し、本番環境では推奨されません)
54    // curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
55    // curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
56
57    // cURLリクエストを実行し、レスポンスを取得
58    $response = curl_exec($ch);
59
60    // cURLでエラーが発生したかどうかをチェック
61    if (curl_errno($ch)) {
62        $error_msg = curl_error($ch);
63        error_log("cURLエラーが発生しました: {$error_msg}");
64        curl_close($ch);
65        return false;
66    }
67
68    // HTTPステータスコードを取得
69    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
70
71    // cURLセッションを閉じる
72    curl_close($ch);
73
74    // HTTPステータスコードが 304 Not Modified (更新なし) の場合
75    // CURL_TIMECOND_LASTMOD を使用している場合によく発生します
76    if ($httpCode === 304) {
77        error_log("コンテンツは指定された日時以降更新されていません。(HTTP 304)");
78        return ''; // 更新がないことを示すために空文字列を返す
79    }
80    // HTTPステータスコードが 200 OK 以外の場合 (例: 404 Not Found, 500 Internal Server Error など)
81    elseif ($httpCode !== 200) {
82        error_log("URLからの取得に失敗しました。HTTPステータスコード: {$httpCode}");
83        return false;
84    }
85
86    // 正常に取得できた場合はコンテンツを返す
87    return $response;
88}
89
90// --- 関数利用例 ---
91
92// 実際にアクセス可能なURLに置き換えてください
93$targetUrl = 'https://www.example.com/';
94$timeoutSeconds = 5; // 全体のタイムアウトを5秒に設定
95
96// 1時間前のUNIXタイムスタンプを計算
97// これを CURLOPT_TIMEVALUE に設定することで、1時間前に比べてコンテンツが更新されているかをサーバーに問い合わせます。
98$oneHourAgo = time() - 3600;
99
100echo "--- タイムアウトと条件付きGETのサンプル ---" . PHP_EOL;
101echo "ターゲットURL: {$targetUrl}" . PHP_EOL;
102echo "全体タイムアウト: {$timeoutSeconds}秒" . PHP_EOL;
103echo "条件付きGET: 最終更新日時が " . date('Y-m-d H:i:s', $oneHourAgo) . " 以降の場合に取得" . PHP_EOL;
104
105$contentWithCondition = fetchUrlWithConditionalGetAndTimeout($targetUrl, $timeoutSeconds, $oneHourAgo);
106
107if ($contentWithCondition === false) {
108    echo "エラー: コンテンツの取得に失敗しました。" . PHP_EOL;
109} elseif ($contentWithCondition === '') {
110    echo "情報: コンテンツは指定された日時以降に更新されていません。(HTTP 304)" . PHP_EOL;
111} else {
112    echo "成功: コンテンツを条件付きで取得しました。サイズ: " . strlen($contentWithCondition) . "バイト。" . PHP_EOL;
113    echo "--- コンテンツの一部 ---" . PHP_EOL;
114    echo substr($contentWithCondition, 0, 200) . "..." . PHP_EOL;
115}
116
117echo PHP_EOL;
118
119// --- タイムアウトのみを設定した別のサンプル ---
120echo "--- タイムアウトのみのサンプル ---" . PHP_EOL;
121echo "ターゲットURL: {$targetUrl}" . PHP_EOL;
122echo "全体タイムアウト: {$timeoutSeconds}秒" . PHP_EOL;
123echo "条件付きGET: なし (null)" . PHP_EOL;
124
125$contentWithoutCondition = fetchUrlWithConditionalGetAndTimeout($targetUrl, $timeoutSeconds);
126
127if ($contentWithoutCondition === false) {
128    echo "エラー: コンテンツの取得に失敗しました。" . PHP_EOL;
129} else {
130    echo "成功: コンテンツをタイムアウト設定のみで取得しました。サイズ: " . strlen($contentWithoutCondition) . "バイト。" . PHP_EOL;
131    echo "--- コンテンツの一部 ---" . PHP_EOL;
132    echo substr($contentWithoutCondition, 0, 200) . "..." . PHP_EOL;
133}
134
135?>

PHPのサンプルコードは、fetchUrlWithConditionalGetAndTimeout関数を通じて、指定されたURLからコンテンツを取得する際に「条件付きGET」と「転送タイムアウト」を設定する方法を示しています。この関数はcURLライブラリを利用し、HTTPリクエストを送信します。

まず、CURLOPT_TIMEOUTオプションは、URLへの接続からデータ転送完了までの全体の最大時間を秒数で指定します。引数$timeoutで設定されるこのタイムアウトは、ネットワークの遅延などで処理が長時間停止することを防ぎ、アプリケーションの応答性を維持するために重要です。

次に、CURL_TIMECOND_LASTMOD定数とCURLOPT_TIMEVALUEオプションを組み合わせることで、「条件付きGET」を実現しています。引数$ifModifiedSinceにUNIXタイムスタンプを指定すると、サーバーに対して「この日時以降にコンテンツが更新されていたら送ってください」というリクエスト（If-Modified-Sinceヘッダー）を送信します。これにより、コンテンツが更新されていない場合はサーバーからのデータ転送が省略され、HTTPステータスコード304（Not Modified）が返されるため、ネットワーク帯域と処理負荷を節約できます。

この関数は、引数$urlで取得対象のURL、$timeoutで最大転送時間、$ifModifiedSinceで条件付きGETの基準日時を受け取ります。コンテンツの取得に成功した場合はその内容を文字列で、HTTP 304で更新がない場合は空文字列を、エラーが発生した場合はfalseを戻り値として返します。この仕組みは、ウェブサイトのクローラーやキャッシュシステムの実装において、効率的なデータ取得に役立ちます。

Copy
1<?php
2
3/**
4 * cURLリクエストを行い、接続および転送タイムアウトの設定方法をデモンストレーションします。
5 *
6 * デフォルトのcURLタイムアウトは0（無制限）です。これは、PHPスクリプトの実行時間制限
7 * (php.iniの max_execution_time など) や、サーバー・ネットワークの設定が先に適用される可能性があることを意味します。
8 * 通常、安定したアプリケーションでは明示的にタイムアウトを設定することが推奨されます。
9 *
10 * @param string $url リクエストを送信するURL。
11 * @param int $connectTimeoutSeconds 接続確立の最大秒数。この時間内に接続できない場合、エラーとなります。
12 * @param int $transferTimeoutSeconds 転送全体の最大秒数。この時間内に転送が完了しない場合、エラーとなります。
13 */
14function makeCurlRequestWithCustomTimeout(
15    string $url,
16    int $connectTimeoutSeconds = 5,
17    int $transferTimeoutSeconds = 10
18): void {
19    // cURLセッションを初期化します。
20    $ch = curl_init($url);
21
22    if ($ch === false) {
23        echo 'エラー: cURLセッションの初期化に失敗しました。' . PHP_EOL;
24        return;
25    }
26
27    // CURLOPT_CONNECTTIMEOUT: サーバーへの接続を試行する最大秒数を設定します。
28    // デフォルト値は0（無制限）です。
29    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $connectTimeoutSeconds);
30
31    // CURLOPT_TIMEOUT: cURL転送全体の最大秒数を設定します。
32    // デフォルト値は0（無制限）です。
33    curl_setopt($ch, CURLOPT_TIMEOUT, $transferTimeoutSeconds);
34
35    // レスポンスを文字列として取得し、直接出力しないように設定します。
36    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
37
38    // cURLリクエストを実行します。
39    $response = curl_exec($ch);
40
41    // cURL実行後にエラーが発生したかを確認します。
42    if ($response === false) {
43        echo 'cURLエラー: ' . curl_error($ch) . PHP_EOL;
44        echo 'エラーコード: ' . curl_errno($ch) . PHP_EOL;
45    } else {
46        // HTTPステータスコードを取得します。
47        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
48        echo 'HTTPステータスコード: ' . $httpCode . PHP_EOL;
49        echo 'レスポンス内容 (最初の200文字): ' . substr($response, 0, 200) . '...' . PHP_EOL;
50    }
51
52    // cURLセッションを閉じ、リソースを解放します。
53    curl_close($ch);
54}
55
56// 関数の使用例:
57// makeCurlRequestWithCustomTimeout('https://www.google.com', 3, 5); // 接続3秒、転送5秒のタイムアウト設定
58
59// 注意: 以下の例は意図的にタイムアウトを発生させるためのものです。
60// 接続タイムアウトの例: 存在しないポートへの接続
61// makeCurlRequestWithCustomTimeout('http://localhost:9999', 1, 3);
62
63// 転送タイムアウトの例: 遅延応答するサービス
64// makeCurlRequestWithCustomTimeout('https://httpbin.org/delay/7', 3, 5); // 7秒遅延するが、転送タイムアウトは5秒のためエラー

PHPのcURLは、ウェブサーバーとの通信を行うための強力な機能です。このサンプルコードは、cURLを使ったHTTPリクエストにおいて、接続および転送のタイムアウトを制御する方法をシステムエンジニアを目指す初心者の方にも理解しやすいように示しています。

makeCurlRequestWithCustomTimeout関数は、指定されたURLに対し、カスタムのタイムアウト設定でcURLリクエストを実行します。引数として、リクエスト先のURL（$url）、サーバーへの接続を確立するまでの最大秒数（$connectTimeoutSeconds、デフォルト5秒）、そしてリクエスト全体の転送が完了するまでの最大秒数（$transferTimeoutSeconds、デフォルト10秒）を受け取ります。この関数は処理結果を直接返すわけではないため、戻り値は特にありません（void）。

cURLのデフォルトタイムアウトは「0（無制限）」であり、これによりスクリプトが応答のないサーバーで長時間停止するリスクがあります。そのため、curl_setopt関数を使い、CURLOPT_CONNECTTIMEOUTで接続タイムアウトを、CURLOPT_TIMEOUTで転送タイムアウトを明示的に設定することが推奨されます。これにより、指定した時間内に処理が完了しない場合にエラーとして処理され、アプリケーションの安定性が向上します。通信中にエラーが発生した場合は、curl_errorやcurl_errnoで詳細を確認し、適切なエラーハンドリングを行う例も含まれています。