Skip to content
Tutorials Center
My learning

Topics

Lesson 109 of 147 ยท Advanced PHP

Calendar and Julian Day Functions

Use PHP's calendar extension - cal_days_in_month, easter_date, gregoriantojd, jddayofweek and jdmonthname - and learn the DateTime equivalents for when the extension is missing.

Date and Time teaches DateTimeImmutable, which handles nearly everything you need. PHP also has an older, smaller toolbox called the calendar extension. It converts between calendar systems through a common number called the Julian Day (JD), and it knows a few facts that DateTime does not, such as the date of Easter. The functions all start with cal_, jd, easter_ or end in tojd, and they are common in programs like "how many days are in this month" and "which weekday was this date".

This lesson shows the useful ones, explains what a Julian Day number is, and gives you plain DateTime replacements for each, because the extension is optional: it is enabled on the runner behind our examples, but a hosting provider may not have it. Check with extension_loaded('calendar').

What is a Julian Day?

A Julian Day number counts days continuously from a fixed starting point (noon on 1 January 4713 BC in the Julian calendar). It has no months or leap years, so date arithmetic becomes plain subtraction. Every calendar (Gregorian, Julian, Jewish, French Republican) can convert to and from it. The function names follow a pattern: gregoriantojd() goes from a Gregorian date to a JD and jdtogregorian() goes back.

This is the astronomers' Julian Day, not "the Julian calendar". PHP's jd* functions work with whole days, so the fractional part of a day is dropped. Note also the argument order of gregoriantojd($month, $day, $year): month first, which surprises many people.

Days in a month and leap years

cal_days_in_month($calendar, $month, $year) answers the most common calendar question. The calendar argument is a constant; CAL_GREGORIAN is the one you want.

PHP Days in a month

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Without the extension the format('t') approach is exactly as good, and it also tells you about leap years with format('L').

Converting to and from Julian Day numbers

PHP Gregorian to JD and back

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

jdtogregorian() returns the string month/day/year without leading zeros, which is rarely what you want in output. cal_from_jd() returns an array with the parts, and cal_to_jd() is the generic version of gregoriantojd() that takes a calendar constant first.

Weekdays and month names

jddayofweek($jd, $mode) takes a JD and returns the weekday. Mode 0 returns a number (0 = Sunday), mode 1 the full name and mode 2 the abbreviation. jdmonthname($jd, $mode) does the same for months; its modes choose abbreviated or full names for the Gregorian, Julian and other calendars.

PHP Weekday of a date

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

For user-facing text prefer DateTime::format('l') or IntlDateFormatter (see Internationalization), because the calendar functions only produce English names.

Easter

Easter's date follows a lunar rule that is awkward to program. The extension offers two helpers:

  • easter_date($year) returns the Unix timestamp of midnight on Easter Sunday (in the default time zone).
  • easter_days($year) returns how many days after 21 March Easter falls, which is handy for computing movable holidays (Good Friday is easter_days - 2).
PHP Easter and movable holidays

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

easter_days() is the safer choice: it works with plain day counts and does not depend on the server's time zone. Both functions use the Western (Gregorian) rule; the Orthodox Easter has its own computation and is not covered by the extension.

Other calendars and cal_info()

Because every calendar converts through the Julian Day, the extension can translate between four calendar systems: Gregorian, Julian, Jewish and French Republican. Each has its own xxxtojd() and jdtoxxx() pair, with the same month-first argument order as gregoriantojd(). The calendar constants are CAL_GREGORIAN, CAL_JULIAN, CAL_JEWISH and CAL_FRENCH.

cal_info() describes a calendar: its name, the number of months, month names and the longest month. Called with no argument it returns an array describing all four.

PHP Four calendars and cal_info

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

jdtofrench() only handles the short life of the French Republican calendar (1792 to 1806), so it returns 0/0/0 for a modern date. jdtojewish() returns the month number in the Jewish calendar, where leap years add an extra month (Adar I and Adar II), so month numbers are not simple names. jdmonthname() accepts a mode constant for each calendar if you need names.

Without the extension

If calendar is missing, these two helpers cover most needs using only core PHP: the number of days in a month with format('t'), and a Julian Day number from a Unix timestamp (the Unix epoch is JD 2440587.5).

PHP Core PHP replacements

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

For differences between two dates you do not need a Julian Day at all: $a->diff($b)->days does the same job and is covered in Date and Time.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the argument order of gregoriantojd()?

    The function takes month, then day, then year. This is a common source of off-by-order bugs.
  2. 2. What does cal_days_in_month(CAL_GREGORIAN, 2, 2024) return?

    2024 is a leap year, so February has 29 days. DateTime's format('t') gives the same answer.
  3. 3. Why can subtracting two Julian Day numbers be useful?

    A JD is a continuous day count, so the difference of two JDs is the number of days between the dates.
  4. 4. Which of these is NOT provided by the calendar extension?

    DateTimeImmutable belongs to PHP's core date extension. The other three come from the optional calendar extension.

Summary

  • The calendar extension converts between calendars through the Julian Day number; check it with extension_loaded('calendar').
  • cal_days_in_month(CAL_GREGORIAN, $month, $year) gives month length; format('t') is the core-PHP equivalent.
  • gregoriantojd($month, $day, $year) and jdtogregorian() convert both ways; JD subtraction counts days.
  • jddayofweek() and jdmonthname() give English weekday and month names.
  • easter_date() and easter_days() calculate Western Easter; derive other movable holidays from easter_days().
  • For most date work, DateTimeImmutable is more flexible and always available.

Next: Performance