PHP jdtounix() — Преобразование юлианского дня в Unix-метку

Функция jdtounix() преобразует номер юлианского дня в Unix-временную метку. Она входит в расширение calendar и служит мостом между календарными вычислениями (которые оперируют целыми днями) и временем в секундах, используемым остальными функциями работы с датами в PHP.

На этой странице объясняется, что представляют собой обе системы счёта времени, показывается jdtounix() в действии, рассматривается допустимый диапазон и подводные камни, а в конце описываются более часто используемые функции работы с Unix-метками — date() и strtotime().

Два способа отсчёта времени

Перед использованием jdtounix() полезно точно понимать, что именно она преобразует.

Unix-временная метка — это количество секунд, прошедших с момента 1970-01-01 00:00:00 UTC («эпоха Unix»). Это стандарт, который PHP использует повсеместно: time(), date(), strtotime() и DateTime работают именно с Unix-временными метками.

Номер юлианского дня (Julian Day Count, JDC) — это количество целых дней, прошедших с полудня 1 января 4713 года до нашей эры (по пролептическому юлианскому календарю). Астрономы и библиотеки для работы с календарями используют его, потому что каждому дню присваивается единственное целое число, что упрощает подсчёт промежутков между датами в разных календарных системах. Функции PHP gregoriantojd(), jdtogregorian() и им подобные работают именно с такими номерами.

jdtounix() переводит JDC в эквивалентную Unix-временную метку, соответствующую полуночи UTC указанного дня.

Синтаксис

jdtounix(int $julian_day): int

$julian_day — номер юлианского дня для преобразования.
Возвращает соответствующую Unix-временную метку. День должен попадать в поддерживаемый диапазон; при выходе за его пределы в PHP 8.0+ генерируется исключение ValueError (в более ранних версиях возвращалось false).

Простой пример

Готовый номер юлианского дня встречается редко, поэтому обычный порядок действий таков: сначала преобразовать григорианскую дату в JDC с помощью gregoriantojd(), а затем передать результат в jdtounix().

<?php

// Build the Julian Day Count for 15 February 2022 (month, day, year).
$jd = gregoriantojd(2, 15, 2022);
echo $jd, "\n";                       // 2459626

// Convert that day to a Unix timestamp (midnight UTC).
$timestamp = jdtounix($jd);
echo $timestamp, "\n";                // 1644883200

// Confirm by formatting it back to a readable date.
echo gmdate('Y-m-d H:i:s', $timestamp); // 2022-02-15 00:00:00

Поскольку номер юлианского дня представляет целый день, а не конкретный момент, jdtounix() всегда возвращает метку для 00:00:00 UTC этого дня. Информация о времени суток просто не содержится во входных данных.

Допустимый диапазон

jdtounix() работает только в пределах диапазона Unix-эпохи. Наименьший допустимый день — 1970-01-01, которому соответствует метка 0:

<?php

// 1 January 1970 is the lowest day jdtounix() can represent.
var_dump(jdtounix(gregoriantojd(1, 1, 1970))); // int(0)

Передача дня, предшествующего эпохе, является ошибкой: в PHP 8.0 и новее генерируется исключение ValueError, тогда как PHP 7 возвращал false. Если входной день задаётся пользователем, проверяйте диапазон (или оборачивайте вызов в блок try/catch), прежде чем использовать результат. На системах, где временные метки хранятся как знаковые 32-битные целые числа, практическая верхняя граница приходится на 2038 год.

Обратная функция — unixtojd(), которая преобразует Unix-временную метку обратно в номер юлианского дня.

Преобразование Unix-метки в читаемую дату

Когда у вас есть временная метка — из jdtounix(), time() или базы данных — для отображения её в удобочитаемом виде используйте функцию date(). Она принимает строку формата и временную метку:

php— editable, runs on the server

Обратные косые черты в \a\t экранируют буквы a и t, чтобы они выводились буквально, а не интерпретировались как символы форматирования. Наиболее распространённые символы формата:

Y — четырёхзначный год
m — месяц с ведущим нулём (01–12)
M — сокращённое название месяца (Jan–Dec)
d — день месяца с ведущим нулём (01–31)
D — сокращённое название дня недели (Sun–Sat)
g — часы в 12-часовом формате без ведущего нуля (1–12)
H — часы в 24-часовом формате с ведущим нулём (00–23)
i — минуты с ведущим нулём (00–59)
s — секунды с ведущим нулём (00–59)
a — строчные am/pm

Замечание о временных зонах

PHP форматирует каждую временную метку относительно часового пояса, установленного по умолчанию для скрипта, поэтому одна и та же метка может отображаться как разное время на разных серверах. Явно задавайте часовой пояс в начале скрипта — с помощью date_default_timezone_set(), как показано выше, — чтобы результаты были воспроизводимы везде. В примерах на этой странице используется UTC.

Преобразование читаемой даты в Unix-метку

В обратном направлении функция strtotime() разбирает описание даты на английском языке в Unix-временную метку:

<?php

date_default_timezone_set('UTC');

$timestamp = strtotime('February 15, 2022 6:17 pm');
echo $timestamp; // 1644949020

strtotime() понимает множество форматов — 2022-02-15, next Friday, +1 week, — но требовательна к формулировкам. Вспомогательные слова, такие как at, не допускаются: strtotime('February 15, 2022 at 6:17 pm') вернёт false. При неудачном разборе strtotime() возвращает false, поэтому всегда проверяйте результат перед использованием.

Когда стоит использовать jdtounix()?

Для повседневных задач «сохранить и отобразить дату» используйте date(), strtotime() и DateTime — они работают непосредственно с реальными датами и временем. Прибегайте к jdtounix() (вместе с gregoriantojd()) тогда, когда вы уже работаете с номерами юлианских дней: например, при интеграции с астрономическими данными, взаимодействии с другой календарной системой или подсчёте целых дней между датами с последующей потребностью в стандартной временной метке.

Схема преобразования

graph LR;
    A[Gregorian date] -->|gregoriantojd| B[Julian Day Count];
    B -->|jdtounix| C[Unix timestamp];
    C -->|unixtojd| B;
    C -->|date| D[Readable string];

Заключение

jdtounix() преобразует номер юлианского дня в Unix-временную метку, соответствующую полуночи UTC этого дня, и возвращает false для дней, выходящих за пределы диапазона эпохи. Функция естественно сочетается с gregoriantojd() при входном преобразовании и unixtojd() при обратном. Для обычной работы с датами чаще всего применяется расширенный набор инструментов из раздела PHP Date and Time — в первую очередь date() и strtotime().

Практика

Что делает функция PHP jdtounix()?

Преобразует номер юлианского дня в Unix-временную метку.Преобразует Unix-временную метку в номер юлианского дня.Возвращает текущие дату и время в виде строки.Разбирает строку с датой на английском языке в временную метку.