PHP cal_to_jd() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Calendar

Definition

In PHP, cal_to_jd() converts a date in a chosen calendar into a Julian Day number, which is a simple count of days.

It works as a single entry point for all four supported calendars. You pass the calendar, then the month, day and year, and you get a number back. Once you have Julian Day numbers, comparing dates or counting the days between them is just subtraction.

Syntax

Call cal_to_jd() with the values you need. Start with this line.

PHP
$jd = cal_to_jd(CAL_GREGORIAN, 1, 1, 2000);
CallWhat it does
cal_to_jd(CAL_GREGORIAN, 1, 1, 2000)Returns 2451545, the Julian Day for January 1, 2000.
cal_to_jd(CAL_JULIAN, 12, 19, 1999)Returns 2451545 too, because it is the same day in the Julian calendar.
cal_to_jd(CAL_GREGORIAN, 13, 1, 2024)Returns 0 because month 13 is not valid.

Notice the argument order: calendar, month, day, year. Month comes before day, which is the American order. For Gregorian-only code, gregoriantojd() does the same job with one argument less.

Library declarations
PHP
cal_to_jd(int $calendar, int $month, int $day, int $year): int

Parameters

ParameterDescription
calendarRequired. The calendar of the input date: CAL_GREGORIAN (0), CAL_JULIAN (1), CAL_JEWISH (2) or CAL_FRENCH (3). Any other value throws a ValueError.
monthRequired. The month number in that calendar, such as 1 to 12 for the Gregorian calendar.
dayRequired. The day of the month.
yearRequired. The year in that calendar. Year 0 is not valid for the Gregorian and Julian calendars.

Return Value

Return ValueDescription
intThe Julian Day number for the date. It returns 0 if the date is not valid for that calendar.

PHP Examples

Example 1 — Convert Dates from Four Calendars

Convert a Gregorian date first, then the same day in the Julian calendar, and then one date each from the Jewish and French calendars.

PHP
<?php
echo cal_to_jd(CAL_GREGORIAN, 1, 1, 2000), PHP_EOL;
echo cal_to_jd(CAL_JULIAN, 12, 19, 1999), PHP_EOL;
echo cal_to_jd(CAL_JEWISH, 4, 20, 5784), PHP_EOL;
echo cal_to_jd(CAL_FRENCH, 1, 1, 1), PHP_EOL;

How It Works

  1. January 1, 2000 in the Gregorian calendar is the Julian Day number 2451545.
  2. December 19, 1999 in the Julian calendar is the very same day, so the number is the same.
  3. The Jewish date 20 Tevet 5784 (month 4) is January 1, 2024, which is 2460311.
  4. The French Republican calendar starts on 1/1/1, which is 2375840.

Example 2 — Invalid Dates Return 0

When the date does not exist in the calendar, cal_to_jd() quietly returns 0. A calendar ID that does not exist throws an error.

PHP
<?php
var_dump(cal_to_jd(CAL_GREGORIAN, 13, 1, 2024));
var_dump(cal_to_jd(CAL_GREGORIAN, 1, 1, 0));
var_dump(cal_to_jd(CAL_FRENCH, 1, 1, 15));

try {
    cal_to_jd(9, 1, 1, 2024);
} catch (ValueError $e) {
    echo 'Invalid calendar ID', PHP_EOL;
}

How It Works

  1. Month 13 does not exist in the Gregorian calendar, so the result is 0.
  2. There is no year 0 in the Gregorian calendar (1 BC is followed directly by 1 AD), so this also returns 0.
  3. The French calendar only supports years 1 to 14, so year 15 returns 0.
  4. Calendar number 9 is not valid, so PHP 8 throws a ValueError.

Example 3 — Count Days Between Two Dates

Convert two dates to Julian Day numbers and subtract them to get the number of days in between.

PHP
<?php
$start = cal_to_jd(CAL_GREGORIAN, 1, 1, 2024);
$end = cal_to_jd(CAL_GREGORIAN, 12, 25, 2024);

echo 'Start JD: ', $start, PHP_EOL;
echo 'End JD: ', $end, PHP_EOL;
echo 'Days between: ', $end - $start, PHP_EOL;
echo 'Full weeks: ', intdiv($end - $start, 7), PHP_EOL;

How It Works

  1. Each date is converted to a Julian Day number, which is just an integer.
  2. Subtracting the two integers gives the number of days between the dates.
  3. From January 1 to December 25 in a leap year is 359 days.
  4. intdiv() divides by 7 and drops the remainder, giving 51 full weeks.

Frequently Asked Questions

It converts a date from a chosen calendar into a Julian Day number. This number counts days, so it is easy to compare, add and subtract.
The order is calendar, month, day, year. Many beginners put the day first by mistake, which gives a wrong date or a zero result.
A result of 0 means the date is not valid in that calendar, for example month 13 in the Gregorian calendar or year 0. Check your numbers before calling the function.
gregoriantojd() only handles Gregorian dates. cal_to_jd() handles Gregorian, Julian, Jewish and French dates by taking an extra calendar argument.
Yes. Convert both dates to Julian Day numbers and subtract the smaller one from the larger one. The result is the number of days between them.

Next: easter_date()

easter_date() returns the Unix timestamp for midnight on Easter Sunday of a given year.

easter_date() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful