easter_date()

Введение

Программное вычисление даты Пасхи — удивительно распространённая задача: календарные приложения, системы планирования и программы для расчёта зарплаты должны знать, на какой день года приходится Пасха, поскольку эта дата меняется каждый год. PHP поставляется с двумя встроенными функциями для этого: easter_date() и easter_days(). В этой главе объясняется, как вычисляется Пасха, как ведёт себя каждая функция и какую из них выбрать, чтобы избежать проблем с часовыми поясами.

Почему дата Пасхи меняется

Пасха — переходящий праздник: в отличие от Рождества, у неё нет фиксированной даты в календаре. По правилу, установленному на Никейском соборе в 325 году н. э., Пасхальное воскресенье — это первое воскресенье после первого полнолуния, наступившего в день весеннего равноденствия или после него. Поскольку это зависит от лунного цикла, дата смещается в промежутке с 22 марта по 25 апреля год от года.

PHP реализует стандартный алгоритм computus внутри, поэтому вам никогда не придётся вычислять лунную фазу самостоятельно.

easter_date()

easter_date() возвращает Unix-временну́ю метку Пасхального воскресенья для заданного года.

• Сигнатура: easter_date(?int $year = null, int $mode = CAL_EASTER_DEFAULT): int
• Параметры: Четырёхзначный $year (по умолчанию — текущий год). Необязательный параметр $mode выбирает григорианский или юлианский алгоритм вычисления.
• Возвращаемое значение: Unix-временна́я метка Пасхального воскресенья.

Примечание: Распространённая ошибка — передавать временну́ю метку в easter_date(). Аргумент — это год (например, 2023), а не временна́я метка. Передача mktime(...) даёт неверный результат.

Здесь есть подводный камень, связанный с часовыми поясами. Возвращаемая временна́я метка указывает на полдень UTC Пасхального воскресенья, поэтому форматирование с помощью date() при часовом поясе по умолчанию западнее UTC может сместить результат на предыдущий день. Для отображения предпочтительнее использовать подход с easter_days(), описанный ниже.

easter_days()

easter_days() возвращает количество дней после 21 марта, на которое приходится Пасха, вместо временно́й метки. Это безопасный с точки зрения часовых поясов строительный блок: в сочетании с обычной календарной датой он даёт правильный день независимо от date_default_timezone_set().

• Сигнатура: easter_days(?int $year = null, int $mode = CAL_EASTER_DEFAULT): int
• Возвращаемое значение: Целочисленное смещение (например, 19 означает 21 марта + 19 дней).

Доступность: easter_date() и easter_days() являются частью модуля calendar в PHP. Они были перенесены в ядро в PHP 8.0 и по-прежнему доступны в текущих версиях PHP (8.x) — они не были удалены. Если вы видите Call to undefined function easter_date() в более старой сборке, подключите модуль calendar.

Примеры кода

Рекомендуемый способ — безопасный для часовых поясов через easter_days()

<?php

$year = 2023;
$easter = (new DateTimeImmutable("$year-03-21"))
    ->modify('+' . easter_days($year) . ' days');

echo $easter->format('F j, Y'); // Outputs: April 9, 2023

Быстрый однострочник с easter_date()

<?php

$year = 2023;
echo date('F j, Y', easter_date($year));

easter_date() привязывает временну́ю метку к полудню UTC, поэтому отображаемый календарный день зависит от часового пояса форматирования — обратите внимание, как один и тот же год выводится по-разному в примере ниже. Именно поэтому версия с easter_days() является более безопасным выбором:

<?php

date_default_timezone_set('UTC');
echo date('F j, Y H:i', easter_date(2024)); // Outputs: March 30, 2024 20:00

Дополнительные материалы

• PHP функция date()
• PHP date_default_timezone_set()
• PHP Дата и время

Заключение

Пасха — переходящий праздник, поэтому её дата должна вычисляться по лунному календарю каждый год. PHP берёт на себя сложные вычисления через модуль calendar. Для кода отображения предпочитайте easter_days() в сочетании с DateTimeImmutable, чтобы результат не зависел от часового пояса сервера; используйте easter_date() для быстрого получения временно́й метки, если вы управляете часовым поясом по умолчанию.

Практика