PHP Calendar

Beginner
8 min read
Updated: Nov 2026
3 examples
Julian Day, months & Easter

Definition and Usage

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.

Two more helpers stand on their own. cal_days_in_month() returns the length of a month, and easter_days() with easter_date() find the date of Easter for a given year.

This page explains the ideas. The Calendar Functions index lists all 18 function guides.

Pick the right tool.

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.

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

Core Ideas

What to remember when you work with the calendar extension:

IdeaFunctionRemember
Calendar detailscal_info()Returns month names, month count, and the calendar name as an array; pass -1 to list all four calendars
Month lengthcal_days_in_month()Argument order is calendar, month, year; February 2024 gives 29
Date to Julian Daycal_to_jd() / gregoriantojd()Both return an integer day count; the order is month, day, year, not year first
Julian Day to datecal_from_jd() / jdtogregorian()cal_from_jd() returns an array with dayname and monthname; jdtogregorian() returns a string such as 1/15/2024
Eastereaster_days() / easter_date()easter_days() counts days after March 21; easter_date() returns a Unix timestamp for midnight in the default timezone
Other calendarsjuliantojd() / jewishtojd() / frenchtojd()Each has a matching jdto* function; the French Republican calendar only covers years 1 to 14
Day and month namesjddayofweek() / jdmonthname()Both start from a Julian Day; the second argument is a mode that picks a number or a name
Unix timestampsunixtojd() / jdtounix()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.

Calendar Constants

cal_days_in_month(), cal_to_jd(), cal_from_jd(), and cal_info() take a calendar constant to say which calendar to use. Use the constant name, not the number, so the code is easy to read.

ConstantValueCalendar
CAL_GREGORIAN0Gregorian, the calendar used by most of the world today
CAL_JULIAN1Julian, the calendar the Gregorian one replaced
CAL_JEWISH2Jewish (Hebrew) calendar
CAL_FRENCH3French Republican calendar, years 1 to 14 only

PHP Examples

Three short scripts that show how the calendar functions work. Each one uses fixed dates in 2024, so the output is the same every time you run it.

Example 1 — cal_days_in_month() for 2024

Print the length of the first three months of 2024, then add up all twelve to confirm that 2024 is a leap year.

PHP
<?php
$year = 2024;

foreach ([1, 2, 3] as $month) {
    $days = cal_days_in_month(CAL_GREGORIAN, $month, $year);
    echo date('F', mktime(0, 0, 0, $month, 1, $year)), " $year: $days days", PHP_EOL;
}

$total = 0;
for ($month = 1; $month <= 12; $month++) {
    $total += cal_days_in_month(CAL_GREGORIAN, $month, $year);
}
echo "Days in $year: $total", PHP_EOL;
?>

How It Works

  1. 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.
  2. 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.
  3. 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.

PHP
<?php
$jd = cal_to_jd(CAL_GREGORIAN, 1, 15, 2024);
echo "cal_to_jd: ", $jd, PHP_EOL;
echo "gregoriantojd: ", gregoriantojd(1, 15, 2024), PHP_EOL;

$info = cal_from_jd($jd, CAL_GREGORIAN);
echo "Date: ", $info['date'], PHP_EOL;
echo "Weekday: ", $info['dayname'], PHP_EOL;
echo "Month: ", $info['monthname'], PHP_EOL;

echo "30 days later: ", jdtogregorian($jd + 30), PHP_EOL;

$end = gregoriantojd(3, 20, 2024);
echo "Days to March 20: ", $end - $jd, PHP_EOL;
?>

How It Works

  1. 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.
  2. cal_from_jd() returns an array. The date key is a month/day/year string, and dayname and monthname give the full English names.
  3. Because a Julian Day is just a count, $jd + 30 is thirty days later. jdtogregorian() turns that count back into 2/14/2024.
  4. 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.

PHP
<?php
date_default_timezone_set('UTC');

$year = 2024;

$days = easter_days($year);
echo "Days after March 21: ", $days, PHP_EOL;

$byDays = date('Y-m-d', mktime(0, 0, 0, 3, 21 + $days, $year));
echo "From easter_days(): ", $byDays, PHP_EOL;

$easter = easter_date($year);
echo "From easter_date(): ", date('Y-m-d', $easter), PHP_EOL;

echo "Good Friday: ", date('Y-m-d', $easter - 2 * 86400), PHP_EOL;
?>

How It Works

  1. easter_days(2024) returns 10: Easter Sunday falls ten days after March 21.
  2. mktime(0, 0, 0, 3, 21 + $days, $year) adds those days to March 21, and PHP rolls the date forward to March 31.
  3. 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.
  4. 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.

Next: PHP Calendar Functions Index

After you know the Julian Day hub, month lengths, and Easter, open the functions index for all 18 guides.

Start withWhy
cal_days_in_month()Get the number of days in a month for any calendar
cal_to_jd()Turn a date into a Julian Day number
cal_from_jd()Turn a Julian Day number back into date parts and names
easter_date()Get the Unix timestamp of Easter Sunday
easter_days()Get the number of days between March 21 and Easter
gregoriantojd()Convert a Gregorian date to a Julian Day number
jdtogregorian()Convert a Julian Day number to a Gregorian date string

Full list: PHP Calendar Functions index (/php/calendar/function).

Frequently Asked Questions

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.

Browse every Calendar function

Open the functions index for categorized guides with examples and FAQs.

Calendar Functions Index →

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