【PHP8.x】date_sun_info()関数の使い方

Copy
1<?php
2
3/**
4 * 特定の場所と日付の太陽の情報を取得し、表示する関数。
5 * システムエンジニアを目指す初心者向けに、date_sun_info()関数の基本的な使い方を示します。
6 */
7function displaySunInfoForLocation(): void
8{
9    // タイムゾーンを設定します。これにより、date()関数が正しい時刻で動作します。
10    date_default_timezone_set('Asia/Tokyo');
11
12    // タイムスタンプを設定します（例: 今日の正午）。
13    // date_sun_info() は指定された日時の太陽の情報を計算します。
14    $timestamp = strtotime('today 12:00:00');
15
16    // 計算したい場所の緯度と経度を設定します（例: 東京タワー付近）。
17    $latitude = 35.658058;  // 東京の緯度
18    $longitude = 139.745433; // 東京の経度
19
20    // date_sun_info() 関数を呼び出し、太陽に関する詳細な情報を取得します。
21    // 戻り値は配列で、日の出、日の入り、正午などの時刻や、太陽の方位角・仰角が含まれます。
22    $sunInfo = date_sun_info($timestamp, $latitude, $longitude);
23
24    echo "--- 太陽の情報 ---" . PHP_EOL;
25    echo "対象日時: " . date('Y-m-d H:i:s', $timestamp) . PHP_EOL;
26    echo "対象場所: 緯度 " . $latitude . ", 経度 " . $longitude . PHP_EOL . PHP_EOL;
27
28    // 取得した太陽情報を表示します。
29    // 配列に含まれる時刻情報はUNIXタイムスタンプ形式なので、date()関数で人間が読める形式に変換します。
30    echo "日の出: " . date('H:i:s', $sunInfo['sunrise']) . PHP_EOL;
31    echo "日の入り: " . date('H:i:s', $sunInfo['sunset']) . PHP_EOL;
32    echo "太陽の南中 (正午): " . date('H:i:s', $sunInfo['transit']) . PHP_EOL;
33    echo "市民薄明の始まり: " . date('H:i:s', $sunInfo['civil_twilight_begin']) . PHP_EOL;
34    echo "市民薄明の終わり: " . date('H:i:s', $sunInfo['civil_twilight_end']) . PHP_EOL;
35    echo "航海薄明の始まり: " . date('H:i:s', $sunInfo['nautical_twilight_begin']) . PHP_EOL;
36    echo "航海薄明の終わり: " . date('H:i:s', $sunInfo['nautical_twilight_end']) . PHP_EOL;
37    echo "天文薄明の始まり: " . date('H:i:s', $sunInfo['astronomical_twilight_begin']) . PHP_EOL;
38    echo "天文薄明の終わり: " . date('H:i:s', $sunInfo['astronomical_twilight_end']) . PHP_EOL;
39
40    // 太陽の方位角と仰角は角度の値です。
41    echo "太陽の方位角: " . round($sunInfo['azimuth'], 2) . "度 (南を0度、東を正、西を負)" . PHP_EOL;
42    echo "太陽の仰角: " . round($sunInfo['elevation'], 2) . "度 (地平線を0度)" . PHP_EOL;
43
44    echo "-------------------" . PHP_EOL;
45}
46
47// 上記で定義した関数を実行します。
48displaySunInfoForLocation();
49

PHPのdate_sun_info()関数は、指定された日付と場所の太陽に関する詳細な情報を取得するために使用されます。この関数は、日付をUNIXタイムスタンプで、場所を緯度と経度で受け取り、太陽の日の出、日の入り、薄明の時間帯、太陽の方位角や仰角といった情報を連想配列として返します。

サンプルコードでは、まずdate_default_timezone_set()でタイムゾーンを「Asia/Tokyo」に設定し、正確な時刻計算を保証しています。次に、strtotime('today 12:00:00')で今日の正午のタイムスタンプを取得し、東京タワー付近の緯度と経度を設定しています。これらの情報をdate_sun_info()関数に渡すと、結果として太陽に関する情報が格納された配列が返されます。

戻り値の配列には、sunrise（日の出）、sunset（日の入り）、transit（太陽の南中時刻）などの時刻情報が含まれており、これらはUNIXタイムスタンプ形式で提供されるため、date()関数を使って人間が読める形式に変換して表示しています。また、civil_twilight_beginやnautical_twilight_endといった薄明の種類ごとの開始・終了時刻や、太陽のazimuth（方位角）とelevation（仰角）も取得できるため、太陽の位置を詳細に知ることができます。この関数は、天文学的な計算や特定の場所での日照時間の分析などに役立ちます。

Copy
1<?php
2
3/**
4 * 指定された場所と日付の日の出・日の入り情報を計算し、
5 * その詳細を人間が読みやすい形式で表示します。
6 *
7 * date_sun_info() 関数は、与えられたタイムスタンプ、緯度、経度に基づき、
8 * 特定の日付における日の出、日の入り、様々な薄明（市民薄明、航海薄明、天文薄明）の
9 * 開始・終了時刻を計算します。
10 * 戻り値はUnixタイムスタンプを含む連想配列です。
11 *
12 * この関数は、取得したUnixタイムスタンプを date_default_timezone_set() で設定された
13 * タイムゾーンに合わせて date() 関数でフォーマットし、国際化された時刻表示の概念を
14 * 間接的に示します。
15 *
16 * @param int    $timestamp UNIXタイムスタンプ (日の出・日の入りを計算したい日付の任意の時刻)
17 * @param float  $latitude  緯度 (例: 東京は北緯約35.68度)
18 * @param float  $longitude 経度 (例: 東京は東経約139.69度)
19 * @param string $timezone  結果を表示するためのタイムゾーン識別子 (例: 'Asia/Tokyo')
20 * @return void
21 */
22function displaySunInfo(int $timestamp, float $latitude, float $longitude, string $timezone = 'UTC'): void
23{
24    // 結果を表示するタイムゾーンを設定します。
25    // date() 関数などがこの設定を尊重します。
26    date_default_timezone_set($timezone);
27
28    // date_sun_info 関数を呼び出し、日の出・日の入りに関する詳細情報を取得します。
29    $sunInfo = date_sun_info($timestamp, $latitude, $longitude);
30
31    // エラーが発生した場合の処理
32    // 'error' キーは、エラーがない場合は0を返します。
33    if (isset($sunInfo['error']) && $sunInfo['error'] !== 0) {
34        echo "エラーが発生しました。エラーコード: " . $sunInfo['error'] . "\n";
35        return;
36    }
37
38    echo "--- 日の出・日の入り情報 ---" . "\n";
39    echo "計算基準日時: " . date('Y-m-d H:i:s', $timestamp) . "\n";
40    echo "緯度: " . $latitude . ", 経度: " . $longitude . "\n";
41    echo "表示タイムゾーン: " . $timezone . "\n\n";
42
43    // 取得した情報をループで処理し、人間が読める形式で表示します。
44    foreach ($sunInfo as $key => $value) {
45        // 時刻を表すキー（日の出、日の入り、薄明など）はUnixタイムスタンプなので、
46        // date() 関数で指定されたタイムゾーンに基づいて整形します。
47        // 'error' キーはエラーコード、'tzoffset' はタイムゾーンのオフセットです。
48        if (is_int($value) && $value > 0 && (
49            $key === 'sunrise' ||
50            $key === 'sunset' ||
51            $key === 'transit' ||
52            strpos($key, 'twilight') !== false // 薄明に関するキーをすべて対象
53        )) {
54            // キー名を整形して表示 (例: 'sunrise' -> 'Sunrise')
55            echo str_replace('_', ' ', ucfirst($key)) . ": " . date('Y-m-d H:i:s', $value) . "\n";
56        } elseif ($key === 'tzoffset') {
57            // タイムゾーンオフセットを時間単位で表示
58            echo str_replace('_', ' ', ucfirst($key)) . ": " . ($value / 3600) . "時間\n";
59        }
60        // 'error' キーは既に処理済みか、値が0なのでここでは表示しません。
61    }
62}
63
64// --- サンプル実行 ---
65
66// 例1: 日本の東京 (おおよその緯度経度) で現在の日付の情報を取得します。
67$currentTimestamp = time();          // 今日の日付を使用
68$tokyoLatitude = 35.6895;            // 東京の緯度 (北緯)
69$tokyoLongitude = 139.6917;           // 東京の経度 (東経)
70$tokyoTimezone = 'Asia/Tokyo';       // 東京のタイムゾーン
71
72echo "--- 東京の日の出・日の入り情報 --- \n";
73displaySunInfo($currentTimestamp, $tokyoLatitude, $tokyoLongitude, $tokyoTimezone);
74
75echo "\n"; // 区切り線
76
77// 例2: アメリカのニューヨーク (おおよその緯度経度) で特定の日付の情報を取得します。
78$specificDateTimestamp = strtotime('2024-07-20 12:00:00'); // 2024年7月20日の情報
79$newYorkLatitude = 40.7128;            // ニューヨークの緯度 (北緯)
80$newYorkLongitude = -74.0060;         // ニューヨークの経度 (西経)
81$newYorkTimezone = 'America/New_York'; // ニューヨークのタイムゾーン
82
83echo "--- ニューヨーク (2024年7月20日) の日の出・日の入り情報 --- \n";
84displaySunInfo($specificDateTimestamp, $newYorkLatitude, $newYorkLongitude, $newYorkTimezone);
85
86?>

PHPのdate_sun_info関数は、指定された日付と地球上の場所（緯度と経度）に基づいて、日の出、日の入り、および市民薄明、航海薄明、天文薄明といったさまざまな薄明の開始・終了時刻を計算し、その結果を連想配列として返します。引数には、計算したい日付を表すUNIXタイムスタンプ、場所の緯度（float型）、経度（float型）を渡します。戻り値の配列には、計算された各時刻がUNIXタイムスタンプで格納されており、errorキーで計算エラーの有無も確認できます。

サンプルコードでは、displaySunInfo関数を通じてdate_sun_infoの具体的な利用方法を示しています。この関数は、まずdate_default_timezone_setで結果を表示するタイムゾーンを設定し、その後date_sun_infoで取得した各時刻のUNIXタイムスタンプをdate関数で人間が読みやすい形式に整形して出力しています。これにより、異なる地域や日付における日の出・日の入り時刻を、その地域のタイムゾーンに合わせて正確に表示できることを示しています。また、エラー発生時のチェックも含まれており、堅牢なプログラム作成の参考になります。このコードは、タイムゾーンを考慮した時刻表示の重要性を理解する上でも役立ちます。