date_sunset()

Введение

date_sunset() — устаревшая функция PHP, которая возвращает время заката для заданной даты и географического местоположения. На этой странице объясняется, что она возвращала, как работали её параметры, почему она была удалена из современного PHP и чем её заменить. Если вы пишете новый код, переходите сразу к разделу Переход на современный PHP — но понимание оригинальной сигнатуры по-прежнему полезно при поддержке старых кодовых баз.

Что делает date_sunset()

date_sunset() вычисляла момент, когда солнце опускается за горизонт для конкретной даты и конкретной точки на Земле. Функции требовалось четыре элемента:

• Дата, передаваемая в виде Unix-временной метки.
• Широта и долгота, определяющие положение наблюдателя.
• Угол зенита — угол, измеренный от вертикали вниз, при котором солнце считается «зашедшим». Значение по умолчанию 90.83° чуть больше прямого угла, так как компенсирует атмосферную рефракцию (которая изгибает солнечный свет и делает солнце видимым выше его реального положения) и видимый радиус солнечного диска.

По умолчанию функция возвращала строку вида "18:12", но с соответствующим флагом она могла возвращать результат как Unix-временную метку, которую затем можно форматировать с помощью date() или преобразовывать любой другой функцией работы с датами.

Синтаксис

date_sunset(
    int $timestamp,
    int $returnFormat = SUNFUNCS_RET_STRING,
    float $latitude = ini_get("date.default_latitude"),
    float $longitude = ini_get("date.default_longitude"),
    float $zenith = ini_get("date.sunset_zenith"),
    float $utcOffset = 0
): mixed

Параметры

• timestamp — Unix-временная метка дня, для которого рассчитывается закат. Используйте strtotime() или mktime().
• returnFormat — Одна из трёх констант, определяющих тип возвращаемого значения:
  • SUNFUNCS_RET_STRING — string вида "HH:MM" (по умолчанию).
  • SUNFUNCS_RET_DOUBLE — время в часах от полуночи (число с плавающей точкой, например 18.2).
  • SUNFUNCS_RET_TIMESTAMP — Unix-временная метка.
• latitude — Широта наблюдателя в градусах (положительная = север).
• longitude — Долгота наблюдателя в градусах (положительная = восток, отрицательная = запад).
• zenith — Угол зенита солнца на закате; по умолчанию 90.83°.
• utcOffset — Смещение от UTC в часах; игнорируется, когда returnFormat возвращает временную метку.

Функция возвращала false для местоположений и дат, где солнце не заходит или не восходит (например, на полюсах летом или зимой).

Пример (устаревший PHP 7.x)

Следующий код работает на PHP 7.x и более ранних версиях, где функция ещё существует:

Вывод:

Sunset on March 3, 2023 in San Francisco was at 18:12

Поскольку результат является временной меткой, его можно форматировать по-разному — например, date("g:i A", $sunset) выведет 6:12 PM.

Переход на современный PHP

date_sunset() больше не существует, а встроенный класс PHP DateTime управляет часовыми поясами и форматированием, но не вычисляет положение солнца. Поэтому в современном приложении есть два практических варианта.

Вариант 1 — Обращение к API восхода/заката

Самый простой переносимый подход — запросить публичный сервис и считать возвращаемую им временную метку. Это работает на любой версии PHP и не требует математических вычислений на вашей стороне:

<?php
// Free, no-key API: https://sunrise-sunset.org/api
$lat = 37.7749;
$lng = -122.4194;
$date = '2023-03-03';

$url = "https://api.sunrise-sunset.org/json?lat={$lat}&lng={$lng}&date={$date}&formatted=0";
$response = json_decode(file_get_contents($url), true);

// The API returns ISO-8601 UTC strings
$sunsetUtc = new DateTime($response['results']['sunset']);
$sunsetUtc->setTimezone(new DateTimeZone('America/Los_Angeles'));

echo "Sunset: " . $sunsetUtc->format('H:i');
?>

Вариант 2 — Использование астрономической библиотеки

Для автономного вычисления без подключения к интернету установите поддерживаемый Composer-пакет, реализующий тот же алгоритм расчёта заката (ищите на Packagist по запросу «sunrise sunset»; популярные варианты — tienvx/php-sunrise-sunset и andreas-glaser/php-sun-info). Конкретные имена классов зависят от пакета, поэтому всегда проверяйте его README — общая схема такова: создайте объект-вычислитель на основе широты и долготы, затем запросите время заката для нужной даты.

Где применяется время заката

Независимо от того, используете ли вы date_sunset() (устаревший вариант) или одну из современных альтернатив выше, данные о закате применяются во многих типах приложений:

1. Погодные приложения — отображают время заката вместе с прогнозом погоды для местоположения.
2. Приложения для фотографии — вычисляют «золотой час» — период незадолго до заката, когда свет мягкий и тёплый — путём вычитания часа от времени заката.
3. Приложения для мероприятий и планирования — отмечают открытые мероприятия, продолжающиеся до темноты, или переключают оформление сайта на тёмное после наступления сумерек.
4. Умный дом и освещение — включают свет или запускают сценарии в момент местного заката.

Сочетайте время заката с date_sunrise(), чтобы получить полный световой день для любого местоположения.

Заключение

date_sunset() была удобным способом получить время заката в PHP 7.x одним вызовом, но она была удалена в PHP 8.1 и не работает ни на одной современной версии PHP. Для нового кода обращайтесь к API восхода/заката или используйте поддерживаемую астрономическую библиотеку, а результат форматируйте с помощью класса DateTime. Сценарии использования — погода, фотография, мероприятия, автоматизация — остались прежними; изменился лишь источник вычислений, который переехал за пределы ядра PHP.

Практика