jdmonthname()

PHP-функция cal_jdmonthname()

Функция PHP cal_jdmonthname() возвращает название месяца для заданного юлианского номера дня в указанной календарной системе. На этой странице описано, что такое юлианский номер дня, синтаксис функции и её константы режима, приведены примеры с запуском кода, а также указано, что возвращает функция и на какие подводные камни следует обратить внимание.

Внимание: URL этой главы исторически называется jdmonthname, однако современная PHP-функция — cal_jdmonthname(). Старый псевдоним jdmonthname() из семейства jd был удалён в PHP 8.0 — используйте вместо него cal_jdmonthname().

Синтаксис

cal_jdmonthname(int $julian_day, int $mode): string

• $julian_day — юлианский номер дня (целое число), как правило, полученный с помощью cal_to_jd() из обычной даты.
• $mode — из какой календарной системы читать название месяца. Допустимые значения:

Функция возвращает название месяца в виде string. Функция работает на основе расширения calendar, которое должно быть включено в вашей сборке PHP.

Что такое юлианский номер дня?

Прежде чем разобраться, как работает функция cal_jdmonthname(), важно понять, что такое юлианский номер дня. Юлианский номер дня — это непрерывный счёт дней, начавшийся в полдень 1 января 4713 года до н.э. Он был введён Жозефом Скалигером в 1583 году для упрощения астрономических вычислений и сравнения дат.

Что делает функция cal_jdmonthname?

Функция cal_jdmonthname() принимает два параметра: юлианский номер дня и константу режима (одно из значений CAL_MONTH_* из таблицы выше), которая выбирает календарь и определяет, нужно ли полное или сокращённое название. Функция возвращает соответствующее название месяца в виде string.

Частая точка путаницы: первый шаг (cal_to_jd()) использует константы календаря, например CAL_GREGORIAN, тогда как режим, передаваемый в cal_jdmonthname(), должен быть константой CAL_MONTH_*. Они не взаимозаменяемы.

Пример:

Пример использования функции cal_jdmonthname() в PHP

<?php
// Convert today's date to a Julian day count.
$jd = cal_to_jd(CAL_GREGORIAN, (int) date("m"), (int) date("d"), (int) date("Y"));

// Read the long Gregorian month name back from that Julian day.
echo "Today is " . cal_jdmonthname($jd, CAL_MONTH_GREGORIAN_LONG) . ".";
?>

В месяце, например, марте это выведет: Today is March.

Как использовать функцию cal_jdmonthname?

Чтобы использовать функцию cal_jdmonthname() в своём PHP-коде, выполните следующие шаги:

1. Определите юлианский номер дня для нужной даты. Для преобразования григорианской даты в юлианский номер дня можно использовать функцию cal_to_jd().
2. Вызовите функцию cal_jdmonthname(), передав юлианский номер дня и константу режима (например, CAL_MONTH_GREGORIAN_LONG или CAL_MONTH_JULIAN_LONG).
3. Используйте возвращённое значение в своём коде по мере необходимости.

Примечание: Старые функции расширения jd были удалены в PHP 8.0. Для операций с календарями в современном PHP всегда используйте функции cal_*.

Пример

Вот как можно получить и полное, и сокращённое название месяца для одной и той же даты, изменив только константу режима:

Как использовать функцию cal_jdmonthname() в PHP?

<?php
$jd = cal_to_jd(CAL_GREGORIAN, 3, 1, 2023);   // March 1, 2023

echo "Long:  " . cal_jdmonthname($jd, CAL_MONTH_GREGORIAN_LONG)  . "\n"; // Long:  March
echo "Short: " . cal_jdmonthname($jd, CAL_MONTH_GREGORIAN_SHORT) . "\n"; // Short: Mar
?>

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

Примечание о юлианском календаре: Передача режима CAL_MONTH_JULIAN_* читает тот же юлианский номер дня через старый юлианский календарь. Поскольку юлианский календарь в настоящее время отстаёт от григорианского примерно на 13 дней, дата вблизи начала или конца месяца может оказаться в другом названии месяца по сравнению с григорианским чтением.

Преимущества использования функции cal_jdmonthname

Использование функции cal_jdmonthname() значительно упрощает и ускоряет работу с юлианскими номерами дней в PHP. Вот несколько преимуществ этой функции:

1. Экономия времени: вместо того чтобы вручную вычислять название месяца для заданного юлианского номера дня, можно просто вызвать функцию cal_jdmonthname().
2. Согласованность: функция гарантирует правильное название месяца каждый раз, что снижает риск ошибок в коде.
3. Гибкость: функция позволяет указать календарную систему, что даёт больший контроль над отображением информации в различных исторических или региональных календарях.

Подводные камни

• Используйте константу CAL_MONTH_*, а не CAL_*. Передача CAL_GREGORIAN (значение 0) случайно совпадает с CAL_MONTH_GREGORIAN_LONG, однако CAL_JULIAN не даст вам названий месяцев юлианского календаря — используйте вместо него CAL_MONTH_JULIAN_LONG.
• Расширение calendar должно быть включено. Во многих стандартных сборках оно отключено. Если вы получаете ошибку Call to undefined function cal_jdmonthname(), включите ext-calendar в конфигурации PHP.
• Старые псевдонимы jd* удалены. jdmonthname() и аналогичные функции были удалены в PHP 8.0; в современном коде всегда используйте функции cal_*.

Связанные функции

• cal_to_jd() — преобразование даты календаря в юлианский номер дня (входные данные для этой функции).
• cal_from_jd() — преобразование юлианского номера дня обратно в части даты, включая номер и название месяца.
• cal_days_in_month() — количество дней в заданном месяце.
• cal_info() — названия месяцев и дней для всего календаря сразу.

Заключение

Функция cal_jdmonthname() — удобный инструмент для PHP-разработчиков, работающих с юлианскими номерами дней: она превращает числовой номер дня в человекочитаемое название месяца в выбранной календарной системе. Используйте её в паре с cal_to_jd() для преобразования даты, не забывайте передавать константу CAL_MONTH_* и убедитесь, что расширение calendar включено.

Practice