jdmonthname()

PHP Function: cal_jdmonthname()

The PHP cal_jdmonthname() function returns the month name for a given Julian day count, in the calendar system you ask for. This page covers what a Julian day count is, the function's syntax and its mode constants, runnable examples, what it returns, and the gotchas to watch for.

Heads up: This chapter's URL is historically named jdmonthname, but the modern PHP function is cal_jdmonthname(). The old jdmonthname() alias was part of the jd family that PHP removed in PHP 8.0 — use cal_jdmonthname() instead.

Syntax

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

• $julian_day — a Julian day count (an integer), typically produced by cal_to_jd() from a regular date.
• $mode — which calendar to read the month name from. The accepted values are:

It returns the month name as a string. The function works on the whole calendar extension, which must be enabled in your PHP build.

What is a Julian day count?

Before we dive into how the cal_jdmonthname() function works, it's essential to understand what a Julian day count is. A Julian day count is a continuous count of days that started at noon on January 1st, 4713 BCE. It was introduced by Joseph Scaliger in 1583 to facilitate astronomical calculations and date comparisons.

What does the cal_jdmonthname function do?

The cal_jdmonthname() function takes two parameters: the Julian day count and a mode constant (one of the CAL_MONTH_* values in the table above) that selects the calendar and whether you want the long or short name. The function returns the matching month name as a string.

A common point of confusion: the first step (cal_to_jd()) uses calendar constants like CAL_GREGORIAN, but the mode passed to cal_jdmonthname() must be a CAL_MONTH_* constant. They are not interchangeable.

Here's an example:

Example of cal_jdmonthname() function in 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) . ".";
?>

In a month such as March, this prints: Today is March.

How to use the cal_jdmonthname function?

To use the cal_jdmonthname() function in your PHP code, you need to follow these steps:

1. Determine the Julian day count for the date you're interested in. You can use the cal_to_jd() function to convert a Gregorian date to a Julian day count.
2. Call the cal_jdmonthname() function, passing in the Julian day count and a mode constant (e.g., CAL_MONTH_GREGORIAN_LONG or CAL_MONTH_JULIAN_LONG).
3. Use the returned value in your code as needed.

Note: The older jd extension functions were removed in PHP 8.0. Always use the cal_* functions for calendar operations in modern PHP.

Example

Here's how you can read both the long and the short month name for the same date by changing only the mode constant:

How to use cal_jdmonthname() function in 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
?>

Because the only thing that changed is the mode, this is the cleanest way to switch between full names (March) and abbreviations (Mar), or between calendar systems, without recomputing the date.

Note on the Julian calendar: Passing a CAL_MONTH_JULIAN_* mode reads the same Julian day count through the older Julian calendar. Since the Julian calendar currently runs about 13 days behind the Gregorian one, a date near the start or end of a month can land in a different month name than the Gregorian reading.

Benefits of using the cal_jdmonthname function

Using the cal_jdmonthname() function can make working with Julian day counts in PHP much easier and more efficient. Here are a few benefits of using this function:

1. Saves time: Instead of manually calculating the month name for a given Julian day count, you can simply call the cal_jdmonthname() function.
2. Consistency: The function ensures that you get the correct month name every time, which reduces the risk of errors in your code.
3. Flexibility: The function allows you to specify the calendar system, which gives you more control over how your code displays information across different historical or regional calendars.

Gotchas

• Use a CAL_MONTH_* mode, not a CAL_* calendar constant. Passing CAL_GREGORIAN (value 0) happens to map to CAL_MONTH_GREGORIAN_LONG, but CAL_JULIAN will not give you Julian month names — use CAL_MONTH_JULIAN_LONG instead.
• The calendar extension must be enabled. On many default builds it is not. If you get Call to undefined function cal_jdmonthname(), enable ext-calendar in your PHP configuration.
• The old jd* aliases are gone. jdmonthname() and friends were removed in PHP 8.0; always reach for the cal_* functions in modern code.

Related functions

• cal_to_jd() — convert a calendar date into a Julian day count (the input for this function).
• cal_from_jd() — convert a Julian day count back into date parts, including the month number and name.
• cal_days_in_month() — number of days in a given month.
• cal_info() — month and day names for a whole calendar at once.

Conclusion

The cal_jdmonthname() function is a handy tool for PHP developers working with Julian day counts: it turns a raw day number into a human-readable month name in the calendar system of your choice. Pair it with cal_to_jd() for the date conversion, remember to pass a CAL_MONTH_* mode, and make sure the calendar extension is enabled.

Practice