cal_to_jd()

PHP cal_to_jd(): Convert a Calendar Date to a Julian Day Count

The cal_to_jd() function converts a date from a supported calendar (Gregorian, Julian, Jewish, or French Republican) into a Julian Day Count — a single integer that uniquely identifies a day. Because the result is just a number, it is an easy common denominator for comparing dates, calculating the number of days between two dates, or converting between calendar systems.

This page covers the function's signature, a working example, the supported calendars, the most common pitfalls, and where to go next.

Note: cal_to_jd() is part of PHP's Calendar extension. The extension is bundled with PHP but must be enabled (it is compiled in by default on most builds). If the function is undefined, enable ext-calendar.

What is a Julian Day Count?

The Julian Day Count (often called the Julian Day Number, JDN) is a continuous count of days starting from January 1, 4713 BC in the proleptic Julian calendar, which is defined as day 0. Every later date maps to a larger positive integer, and earlier dates would be negative.

This count is calendar-agnostic: it does not depend on months, leap years, or which calendar system a culture uses. That makes it the standard "pivot" representation in astronomy, scientific computing, and any code that has to interoperate across different calendars.

Do not confuse the Julian Day Count (a day number) with the Julian calendar (the pre-Gregorian calendar). They are unrelated despite the similar name.

Syntax

cal_to_jd(int $calendar, int $month, int $day, int $year): int

Return value: the Julian Day Count as an int, or 0 if the date is invalid for the chosen calendar.

Basic example

Convert March 2, 2023 (Gregorian) to its Julian Day Count:

Note the argument order: it is month, day, year, not day-month-year or year-month-day. Mixing this up is the single most common mistake with cal_to_jd().

Choosing the calendar constant

The first argument selects which calendar your month/day/year values belong to:

The same calendar date can produce different Julian Day Counts depending on the constant you pass, so always match the constant to the calendar your input came from:

<?php
// October 15, 1582 — the day the Gregorian calendar began.
echo cal_to_jd(CAL_GREGORIAN, 10, 15, 1582), "\n"; // 2299161
echo cal_to_jd(CAL_JULIAN,    10, 5,  1582), "\n";  // 2299161
?>

Both print the same Julian Day Count because the Gregorian reform skipped 10 days: Gregorian Oct 15 and Julian Oct 5 are the same physical day.

Common gotchas

• Invalid dates return 0, not false. Passing a non-existent date such as February 30 yields 0. Validate user input with checkdate() before converting if you need to detect bad dates.
• Argument order is month, day, year. See the note above.
• The extension must be enabled. Call relies on ext-calendar; an "undefined function" error means it is not loaded.

Round-tripping with cal_from_jd()

cal_to_jd() has an inverse: cal_from_jd() turns a Julian Day Count back into a calendar date. Together they let you convert between calendar systems by going through the Julian Day Count as a neutral pivot:

<?php
$jd = cal_to_jd(CAL_GREGORIAN, 3, 2, 2023);

$date = cal_from_jd($jd, CAL_GREGORIAN);
echo $date['date']; // 3/2/2023
?>

Related functions

• cal_from_jd() — the inverse: Julian Day Count to a calendar date.
• cal_info() — metadata (month names, etc.) about a calendar.
• cal_days_in_month() — number of days in a given month.
• gregoriantojd(), juliantojd(), jewishtojd(), frenchtojd() — calendar-specific shortcuts for the same conversion.
• See the full PHP Calendar functions overview.

Conclusion

cal_to_jd() reduces any supported calendar date to a single integer — the Julian Day Count — giving you a calendar-neutral way to compare dates, measure intervals, and convert between calendars. Remember the month, day, year argument order, pick the calendar constant that matches your input, and use cal_from_jd() to convert back.

Practice