The PHP calendar extension is a set of functions for calendar math that goes beyond date() and Unix timestamps. It knows four calendars: Gregorian, Julian, Jewish, and French Republican. You can ask how many days a month has, turn a date from one calendar into another, find the date of Easter, or get the weekday name for any day.
The idea that ties the extension together is the Julian Day number, a plain count of days. Every calendar can be turned into that count, and every count can be turned back into a date. That makes it a hub: cal_to_jd() and cal_from_jd() move a date into and out of the count for any calendar, while gregoriantojd() and jdtogregorian() do the same for the Gregorian calendar only.
Use cal_days_in_month() for month lengths, cal_to_jd() and cal_from_jd() to move between calendars, and easter_days() or easter_date() for Easter. For everyday date formatting and timezones, stay with DateTimeImmutable.
The extension may need enabling.
The calendar functions are not always loaded. If you see Call to undefined function cal_days_in_month(), run var_dump(extension_loaded('calendar'));. When it prints false, enable the extension in your PHP build or package (for a source build, use --enable-calendar) and restart the web server or PHP-FPM.
A Julian Day is not the Julian calendar.
The Julian Day is a count of days used by astronomers. The Julian calendar is an older way of writing dates that PHP can read and write with juliantojd() and jdtojulian(). The two share a name but do different jobs.
Syntax
PHP Syntax
The usual pattern: pick a calendar constant, convert to a Julian Day, then read the result back as a date or a name:
PHP
// int: days in a month (calendar, month, year)
echo cal_days_in_month(CAL_GREGORIAN, 2, 2024); // 29
// int: Julian Day number from a date (calendar, month, day, year)
$jd = cal_to_jd(CAL_GREGORIAN, 1, 15, 2024); // 2460325
// array: date parts for a Julian Day (jd, calendar)
$parts = cal_from_jd($jd, CAL_GREGORIAN);
echo $parts['dayname']; // Monday
// Gregorian shortcuts: month, day, year in, "m/d/Y" string out
$same = gregoriantojd(1, 15, 2024); // 2460325
echo jdtogregorian($same); // 1/15/2024
// Easter: days after March 21, and the Unix timestamp
echo easter_days(2024); // 10
echo date('Y-m-d', easter_date(2024)); // 2024-03-31
Reference
Core Ideas
What to remember when you work with the calendar extension:
Link the Julian Day to time() values; jdtounix() only accepts days from 1970 onward
Why the Julian Day is the hub
Converting directly between every pair of calendars would need a function for each pair. Instead, every calendar has one function that goes to a Julian Day and one that comes from it. To turn a Gregorian date into a Jewish date, call gregoriantojd() and pass the result to jdtojewish(). Adding or subtracting days is also plain integer math on the Julian Day.
January 2024: 31 days
February 2024: 29 days
March 2024: 31 days
Days in 2024: 366
How It Works
cal_days_in_month(CAL_GREGORIAN, $month, $year) takes the calendar first, then the month, then the year. It returns the number of days as an integer.
mktime(0, 0, 0, $month, 1, $year) builds a timestamp for the first day of the month, and date('F', ...) turns it into the month name. The calendar extension is not needed for that part.
February 2024 has 29 days because 2024 is a leap year, so the twelve months add up to 366 instead of 365.
Example 2 — The Julian Day bridge
Turn January 15, 2024 into a Julian Day number two ways, read it back as a date, and use plain integer math on the count.
cal_to_jd: 2460325
gregoriantojd: 2460325
Date: 1/15/2024
Weekday: Monday
Month: January
30 days later: 2/14/2024
Days to March 20: 65
How It Works
cal_to_jd() and gregoriantojd() return the same number, 2460325. The first takes a calendar constant; the second is fixed to the Gregorian calendar and takes month, day, and year.
cal_from_jd() returns an array. The date key is a month/day/year string, and dayname and monthname give the full English names.
Because a Julian Day is just a count, $jd + 30 is thirty days later. jdtogregorian() turns that count back into 2/14/2024.
Subtracting two Julian Days gives the number of days between them. From January 15 to March 20 in 2024 that is 65, the same figure date_diff() reports on the Date/Time page.
Example 3 — easter_days() and easter_date() for 2024
Find Easter Sunday for 2024 in two ways and check that both agree. Good Friday is two days earlier.
Days after March 21: 10
From easter_days(): 2024-03-31
From easter_date(): 2024-03-31
Good Friday: 2024-03-29
How It Works
easter_days(2024) returns 10: Easter Sunday falls ten days after March 21.
mktime(0, 0, 0, 3, 21 + $days, $year) adds those days to March 21, and PHP rolls the date forward to March 31.
easter_date(2024) returns a Unix timestamp for midnight on Easter Sunday in the default timezone. date_default_timezone_set('UTC') keeps the result the same on every server.
Subtracting 2 * 86400 seconds moves back two days to Good Friday, March 29. Older PHP versions limit easter_date() to the years 1970 to 2037; easter_days() has no such limit.
Continue
Next: PHP Calendar Functions Index
After you know the Julian Day hub, month lengths, and Easter, open the functions index for all 18 guides.
It is a group of functions for working with calendar systems other than the Unix timestamp: Gregorian, Julian, Jewish, and French Republican. It can count the days in a month, convert a date between calendars through a Julian Day number, find the date of Easter, and name the weekday or month of a Julian Day.
A Julian Day number is a plain count of days from a fixed starting point in the past. Because every calendar can be turned into the same count, it works as a bridge: convert a Gregorian date to a Julian Day with gregoriantojd(), then convert that number to a Jewish, Julian, or French date. It is not the same thing as the Julian calendar.
Call cal_days_in_month(CAL_GREGORIAN, $month, $year). For February 2024 it returns 29 because 2024 is a leap year. If the calendar extension is not available, date('t', mktime(0, 0, 0, $month, 1, $year)) gives the same answer.
Use easter_date($year) to get a Unix timestamp for midnight on Easter Sunday, or easter_days($year) to get the number of days after March 21. For 2024, easter_days() returns 10, so Easter falls on March 31.
They return the same Julian Day number. gregoriantojd($month, $day, $year) is fixed to the Gregorian calendar. cal_to_jd($calendar, $month, $day, $year) takes the calendar as its first argument, so one call works for Gregorian, Julian, Jewish, and French dates.
The calendar extension is not loaded. Check with extension_loaded('calendar'). If it returns false, enable the extension in your PHP build or package; when you compile PHP yourself, add --enable-calendar. Restart the web server or PHP-FPM after the change.