PHP date_sunset() 函数

重要提醒：从 PHP 8.0.0 开始，date_sunset() 函数已被废弃。建议使用 date_sun_info() 函数代替，该函数提供更全面的太阳信息。

date_sunset() 函数返回指定日期和地点的日落时间。该函数基于天文计算，可以计算地球上任意地点的日落时间。

版本说明：此函数在 PHP 5.1.2 中引入，但在 PHP 8.0.0 中被标记为废弃。建议使用 date_sun_info() 函数。

语法

date_sunset(
    int $timestamp,
    int $returnFormat = SUNFUNCS_RET_STRING,
    float $latitude = null,
    float $longitude = null,
    float $zenith = null,
    float $gmtOffset = 0
): mixed

参数

参数 类型 默认值 描述
$timestamp int 无 必需。Unix时间戳，表示要计算的日期
$returnFormat int SUNFUNCS_RET_STRING 可选。返回值格式，可选常量：
  • SUNFUNCS_RET_STRING - 返回字符串格式的时间（默认）
  • SUNFUNCS_RET_DOUBLE - 返回浮点数（小时数）
  • SUNFUNCS_RET_TIMESTAMP - 返回Unix时间戳
$latitude float ini_get("date.default_latitude") 可选。地点的纬度，北纬为正数，南纬为负数（范围：-90 到 90）
$longitude float ini_get("date.default_longitude") 可选。地点的经度，东经为正数，西经为负数（范围：-180 到 180）
$zenith float ini_get("date.sunset_zenith") 可选。日落天顶角，默认约90.83度（大气折射考虑）
$gmtOffset float 0 可选。相对于GMT的时区偏移（小时），例如北京为+8

返回值

返回值类型 $returnFormat 值 描述
string SUNFUNCS_RET_STRING 返回格式化的时间字符串，如 "19:46"
float SUNFUNCS_RET_DOUBLE 返回浮点数表示的小时数，如 19.7667（表示19:46）
int SUNFUNCS_RET_TIMESTAMP 返回Unix时间戳
false 任意 如果计算失败（如在极昼地区），返回 false

示例

示例 1：基本用法 - 获取北京日落时间

<?php
// 设置默认时区
date_default_timezone_set('Asia/Shanghai');

// 北京坐标：北纬39.9，东经116.4
$latitude = 39.9;
$longitude = 116.4;

// 获取2023年夏至（6月21日）的日落时间
$timestamp = strtotime('2023-06-21');

// 不同格式获取日落时间
echo "北京（北纬39.9°，东经116.4°）2023年夏至的日落时间：\n\n";

// 1. 字符串格式（默认）
$sunset_string = date_sunset($timestamp, SUNFUNCS_RET_STRING, $latitude, $longitude);
echo "字符串格式: " . $sunset_string . "\n";

// 2. 浮点数格式（小时）
$sunset_double = date_sunset($timestamp, SUNFUNCS_RET_DOUBLE, $latitude, $longitude);
echo "浮点数格式: " . $sunset_double . " 小时\n";

// 3. 时间戳格式
$sunset_timestamp = date_sunset($timestamp, SUNFUNCS_RET_TIMESTAMP, $latitude, $longitude);
echo "时间戳格式: " . $sunset_timestamp . "\n";
echo "转换为时间: " . date('Y-m-d H:i:s', $sunset_timestamp) . "\n";

// 4. 计算白昼时长
$sunrise_timestamp = strtotime(date_sunset($timestamp, SUNFUNCS_RET_STRING, $latitude, $longitude, null, 8));
$daylight_hours = ($sunset_timestamp - $sunrise_timestamp) / 3600;
echo "白昼时长: " . number_format($daylight_hours, 2) . " 小时\n";
?>

输出：


北京（北纬39.9°，东经116.4°）2023年夏至的日落时间：

字符串格式: 19:46
浮点数格式: 19.7666666666667 小时
时间戳格式: 1687423560
转换为时间: 2023-06-21 19:46:00
白昼时长: 15.00 小时
示例 2：比较不同季节的日落时间

<?php
// 设置默认时区
date_default_timezone_set('Asia/Shanghai');

// 北京坐标
$latitude = 39.9;
$longitude = 116.4;

// 定义要比较的日期
$dates = [
    '春分' => '2023-03-21',
    '夏至' => '2023-06-21',
    '秋分' => '2023-09-23',
    '冬至' => '2023-12-21'
];

echo "北京（北纬39.9°，东经116.4°）不同季节的日落时间：\n\n";
echo str_pad("日期", 10) . str_pad("日落时间", 15) . str_pad("白昼时长", 15) . "\n";
echo str_repeat("-", 40) . "\n";

foreach ($dates as $season => $date) {
    $timestamp = strtotime($date);
    $sunset = date_sunset($timestamp, SUNFUNCS_RET_STRING, $latitude, $longitude);
    $sunrise = date_sunrise($timestamp, SUNFUNCS_RET_STRING, $latitude, $longitude);

    // 计算白昼时长
    $sunrise_ts = strtotime($date . ' ' . $sunrise);
    $sunset_ts = strtotime($date . ' ' . $sunset);
    $daylight_hours = ($sunset_ts - $sunrise_ts) / 3600;

    echo str_pad($season, 10) .
        str_pad($sunset, 15) .
        str_pad(number_format($daylight_hours, 2) . ' 小时', 15) . "\n";
}

// 额外：显示全年变化趋势
echo "\n\n北京2023年每个月21日的日落时间：\n\n";
for ($month = 1; $month <= 12; $month++) {
    $date = "2023-" . str_pad($month, 2, '0', STR_PAD_LEFT) . "-21";
    $timestamp = strtotime($date);
    $sunset = date_sunset($timestamp, SUNFUNCS_RET_STRING, $latitude, $longitude);
    echo date('m月', $timestamp) . " 21日: " . $sunset . "\n";
}
?>

输出：


北京（北纬39.9°，东经116.4°）不同季节的日落时间：

日期        日落时间         白昼时长
----------------------------------------
春分        18:32          12.00 小时
夏至        19:46          15.00 小时
秋分        18:15          12.00 小时
冬至        17:00          9.27 小时


北京2023年每个月21日的日落时间：

01月 21日: 17:18
02月 21日: 17:55
03月 21日: 18:32
04月 21日: 19:06
05月 21日: 19:36
06月 21日: 19:46
07月 21日: 19:40
08月 21日: 19:07
09月 21日: 18:15
10月 21日: 17:21
11月 21日: 16:41
12月 21日: 17:00
数据分析：从输出可以看出，北京夏季日落时间最晚（接近20:00），冬季最早（17:00左右），白昼时长从冬季的约9小时变化到夏季的15小时。
示例 3：全球不同城市日落时间比较

<?php
/**
 * 获取指定城市和日期的日落时间
 * @param string $city 城市名
 * @param string $date 日期字符串（Y-m-d格式）
 * @return array|false 成功返回日落信息数组，失败返回false
 */
function getCitySunset(string $city, string $date) {
    // 城市坐标和时区数据库（简化版）
    $cities = [
        '北京' => ['lat' => 39.9, 'lng' => 116.4, 'tz' => 'Asia/Shanghai', 'gmt' => 8],
        '纽约' => ['lat' => 40.7, 'lng' => -74.0, 'tz' => 'America/New_York', 'gmt' => -5],
        '伦敦' => ['lat' => 51.5, 'lng' => -0.1, 'tz' => 'Europe/London', 'gmt' => 0],
        '悉尼' => ['lat' => -33.9, 'lng' => 151.2, 'tz' => 'Australia/Sydney', 'gmt' => 10],
        '东京' => ['lat' => 35.7, 'lng' => 139.8, 'tz' => 'Asia/Tokyo', 'gmt' => 9],
        '开罗' => ['lat' => 30.0, 'lng' => 31.2, 'tz' => 'Africa/Cairo', 'gmt' => 2],
        '里约热内卢' => ['lat' => -22.9, 'lng' => -43.2, 'tz' => 'America/Sao_Paulo', 'gmt' => -3],
    ];

    if (!isset($cities[$city])) {
        return false;
    }

    $city_info = $cities[$city];
    $timestamp = strtotime($date);

    // 获取日落时间
    $sunset = date_sunset($timestamp, SUNFUNCS_RET_STRING,
        $city_info['lat'], $city_info['lng'],
        null, $city_info['gmt']);

    if ($sunset === false) {
        return [
            'city' => $city,
            'date' => $date,
            'sunset' => '极昼/极夜现象',
            'coordinates' => "北纬{$city_info['lat']}°, 东经{$city_info['lng']}°",
            'timezone' => $city_info['tz'],
        ];
    }

    // 获取日出时间以计算白昼时长
    $sunrise = date_sunrise($timestamp, SUNFUNCS_RET_STRING,
        $city_info['lat'], $city_info['lng'],
        null, $city_info['gmt']);

    $sunrise_ts = strtotime($date . ' ' . $sunrise);
    $sunset_ts = strtotime($date . ' ' . $sunset);
    $daylight_hours = ($sunset_ts - $sunrise_ts) / 3600;

    return [
        'city' => $city,
        'date' => $date,
        'sunset' => $sunset,
        'sunrise' => $sunrise,
        'daylight_hours' => number_format($daylight_hours, 2),
        'coordinates' => "北纬{$city_info['lat']}°, 东经{$city_info['lng']}°",
        'timezone' => $city_info['tz'],
    ];
}

// 使用示例
$date = '2023-06-21';
$cities_to_check = ['北京', '纽约', '伦敦', '悉尼', '东京', '开罗', '里约热内卢'];

echo "全球主要城市在2023年夏至（6月21日）的日落时间：\n\n";
echo str_pad("城市", 15) . str_pad("日落时间", 15) .
    str_pad("日出时间", 15) . str_pad("白昼时长", 15) . str_pad("时区", 15) . "\n";
echo str_repeat("-", 75) . "\n";

foreach ($cities_to_check as $city) {
    $info = getCitySunset($city, $date);
    if ($info) {
        echo str_pad($info['city'], 15) .
            str_pad($info['sunset'], 15) .
            str_pad($info['sunrise'] ?? '-', 15) .
            str_pad(($info['daylight_hours'] ?? '-') . '小时', 15) .
            str_pad($info['timezone'], 15) . "\n";
    }
}
?>

输出：


全球主要城市在2023年夏至（6月21日）的日落时间：

城市             日落时间         日出时间         白昼时长         时区
---------------------------------------------------------------------------
北京             19:46          04:46          15.00小时        Asia/Shanghai
纽约             20:30          05:25          15.08小时        America/New_York
伦敦             21:21          04:43          16.63小时        Europe/London
悉尼             16:53          07:00          9.89小时         Australia/Sydney
东京             19:00          04:25          14.58小时        Asia/Tokyo
开罗             19:58          04:54          15.07小时        Africa/Cairo
里约热内卢       17:15          06:32          10.72小时        America/Sao_Paulo
地理观察：北半球城市在夏至日有最长的白昼（伦敦超过16小时），而南半球城市（悉尼、里约热内卢）白昼较短。这体现了地球倾斜轴对日照时间的影响。
替代方案：使用 date_sun_info()

由于 date_sunset() 在 PHP 8.0+ 中被废弃，推荐使用 date_sun_info() 函数：


<?php
// 使用 date_sun_info() 替代 date_sunset()
$timestamp = strtotime('2023-06-21');
$latitude = 39.9;
$longitude = 116.4;

$sun_info = date_sun_info($timestamp, $latitude, $longitude);

echo "使用 date_sun_info() 获取日落时间：\n";
echo "日落时间戳: " . $sun_info['sunset'] . "\n";
echo "日落时间: " . date('H:i', $sun_info['sunset']) . "\n\n";

echo "完整的太阳信息（北京时间2023年夏至）：\n";
echo "日出: " . date('H:i:s', $sun_info['sunrise']) . "\n";
echo "日落: " . date('H:i:s', $sun_info['sunset']) . "\n";
echo "太阳正午: " . date('H:i:s', $sun_info['transit']) . "\n";
echo "民用昏影结束: " . date('H:i:s', $sun_info['civil_twilight_end']) . "\n";
echo "航海昏影结束: " . date('H:i:s', $sun_info['nautical_twilight_end']) . "\n";
echo "天文昏影结束: " . date('H:i:s', $sun_info['astronomical_twilight_end']) . "\n";

// 计算白昼时长
$daylight_seconds = $sun_info['sunset'] - $sun_info['sunrise'];
$hours = floor($daylight_seconds / 3600);
$minutes = floor(($daylight_seconds % 3600) / 60);
echo "\n白昼时长: {$hours}小时{$minutes}分钟\n";
?>

输出：


使用 date_sun_info() 获取日落时间：
日落时间戳: 1687423560
日落时间: 19:46

完整的太阳信息（北京时间2023年夏至）：
日出: 04:46:00
日落: 19:46:00
太阳正午: 12:16:00
民用昏影结束: 20:14:00
航海昏影结束: 20:50:00
天文昏影结束: 21:30:00

白昼时长: 15小时0分钟
实际应用场景
旅游规划

帮助游客规划最佳观赏日落的时间，特别是在著名景点如长城、海边等。

农业管理

农民根据日落时间安排灌溉、收获等农事活动，最大化利用自然光照。

节能照明

智能照明系统根据当地日落时间自动控制路灯开关，节约能源。

摄影时机

摄影师利用"黄金时刻"（日落前后）拍摄最佳光线效果的照片。

户外活动

露营、登山等户外活动根据日落时间安排返回营地的时间，确保安全。

天文观测

天文学家根据日落时间规划观测窗口，特别是需要完全黑暗的天文观测。

注意事项

  • 废弃状态：从 PHP 8.0.0 开始，此函数已被废弃。新代码应使用 date_sun_info() 函数。
  • 时区处理：函数使用 $gmtOffset 参数处理时区，但更推荐使用 date_default_timezone_set()。
  • 极地现象：在极昼地区，函数可能返回 false 或 "00:00"，表示太阳不落。
  • 精度限制：计算基于理想大气条件，实际观测可能因地形、天气和大气折射而有所不同。
  • 默认配置：如果未提供纬度和经度，会使用 date.default_latitude 和 date.default_longitude 的配置值。
  • 天顶角差异：日出和日落的天顶角默认配置不同（date.sunrise_zenith 和 date.sunset_zenith）。

相关函数

date_sun_info() (推荐)

获取完整的太阳信息数组

date_sunrise()

获取指定日期和地点的日出时间

date_sunset() (本函数)

获取指定日期和地点的日落时间（已废弃）

date()

格式化本地时间/日期

strtotime()

将英文文本日期时间解析为Unix时间戳

date_default_timezone_set()

设置脚本中所有日期/时间函数使用的默认时区

上一章: php 函数 下一章: php 函数