cal_from_jd()

PHP cal_from_jd() Function

The cal_from_jd() function converts a Julian Day Count (a single integer) into a date in the calendar of your choice — Gregorian, Julian, Jewish, or French Republican. It returns an associative array containing the year, month, day, and several handy formatted strings (day name, month name, day of week).

This page explains what a Julian Day Count is, how cal_from_jd() works, every key in the array it returns, and how it differs from the related calendar functions in PHP. The calendar extension must be enabled for these functions to be available.

Syntax

cal_from_jd(int $julian_day, int $calendar): array

• $julian_day — the Julian Day Count to convert. It is an integer; a float is truncated.
• $calendar — which calendar to convert into. Use one of the constants below.

The function always returns an array — there is no failure return value for a valid integer input.

What is a Julian Day Count?

A Julian Day Count (JDC) is a continuous count of whole days starting from noon UTC on January 1, 4713 BCE in the proleptic Julian calendar. Because it is a single growing integer with no months or leap-year rules, it is ideal as a neutral pivot when converting between calendar systems: you convert any calendar date to a JDC, then convert that JDC into the target calendar.

Astronomy, software, and historical research all use it for exactly this reason — date arithmetic on a plain integer is simple and unambiguous.

Don't confuse the Julian Day Count with the Julian calendar. The day count is just a number; the Julian calendar is the older calendar that Pope Gregory XIII reformed in October 1582 to create the Gregorian calendar we use today.

The array cal_from_jd() returns

For a given Julian Day Count, cal_from_jd() returns an associative array with these keys:

Basic example

Convert a Julian Day Count to a Gregorian date and read the components:

<?php
$jd = gregoriantojd(3, 22, 2021); // JDC for March 22, 2021

$date = cal_from_jd($jd, CAL_GREGORIAN);

echo "Date string: " . $date['date'] . "\n";
echo "Year:  " . $date['year'] . "\n";
echo "Month: " . $date['monthname'] . "\n";
echo "Day:   " . $date['day'] . "\n";
echo "Weekday: " . $date['dayname'] . "\n";
?>

This prints:

Date string: 3/22/2021
Year:  2021
Month: March
Day:   22
Weekday: Monday

Inspecting the whole array

If you are unsure which keys you need, dump the full return value:

<?php
$jd = gregoriantojd(12, 25, 2021); // Christmas 2021
print_r(cal_from_jd($jd, CAL_GREGORIAN));
?>

Output:

Array
(
    [date] => 12/25/2021
    [month] => 12
    [day] => 25
    [year] => 2021
    [dow] => 6
    [abbrevdayname] => Sat
    [dayname] => Saturday
    [abbrevmonth] => Dec
    [monthname] => December
)

Common gotchas

• Integer, not a float with .5. Unlike astronomical Julian Date, cal_from_jd() expects a whole-day integer. Passing a float simply truncates the fractional part.
• The calendar extension must be loaded. If you get "Call to undefined function cal_from_jd()", enable the calendar extension in your PHP build.
• Choose the matching calendar constant. The same JDC produces different year/month/day values for CAL_GREGORIAN versus CAL_JULIAN; always pass the constant you actually mean.

Related functions

• cal_to_jd() — the inverse: convert a calendar date to a Julian Day Count.
• gregoriantojd() — get a Julian Day Count from a Gregorian date.
• jdtogregorian() — convert a Julian Day Count back to a Gregorian date string.
• cal_info() — list month/day names and other metadata for a calendar.
• jddayofweek() — get the day of the week for a Julian Day Count.

Conclusion

cal_from_jd() turns a Julian Day Count into a rich array of date parts for any of PHP's four supported calendars. Combined with cal_to_jd() (or gregoriantojd()), it lets you convert dates between calendar systems by routing through a single integer — the Julian Day Count — as a neutral intermediate.

Practice