jddayofweek()

PHP's jddayofweek() returns the day of the week for a given Julian day count. This page explains what a Julian day number is, the exact value each mode returns (the part most people get wrong), and a runnable, verified example.

What is a Julian Day Number?

A Julian day number (JDN) is a single integer that counts the number of days that have elapsed since noon on January 1, 4713 BC (the Julian period epoch). Because it is just one continuous counter, with no months, years, or calendar rules, it is the common "currency" used to convert dates between different calendar systems and to do date arithmetic in astronomy and history.

You rarely type a Julian day number by hand. Instead you produce one from a calendar date using a converter such as cal_to_jd() (and convert back with jdtogregorian()). jddayofweek() then tells you which weekday that JDN falls on.

The "Julian day number" used here is unrelated to the Julian calendar (the Caesar-era calendar replaced by the Gregorian calendar in 1582). The names are similar but they are different concepts.

Syntax

jddayofweek(int $julian_day, int $mode = CAL_DOW_DAYNO): int|string

• $julian_day — the Julian day number to inspect (an integer, e.g. the result of cal_to_jd()).
• $mode — optional. Selects what the function returns. Defaults to CAL_DOW_DAYNO (0).

The mode parameter

The mode is the part of this function that trips people up. There are three modes, and the default returns a number starting at 0 for Sunday — not a Monday-first 1–7 range.

Use the named constants (CAL_DOW_LONG, etc.) rather than the raw numbers to keep your code readable.

How to Use jddayofweek() in PHP

First convert your target date to a Julian day number with cal_to_jd(), which takes the calendar type plus separate integers for month, day, and year (in that order). Then pass the result to jddayofweek() with the mode you want.

The jddayofweek() function in PHP

<?php
// Convert the Gregorian date 2023-03-02 to a Julian day number.
// Argument order is: calendar, month, day, year.
$julianDay = cal_to_jd(CAL_GREGORIAN, 3, 2, 2023);

// Mode 0 (default): integer, 0 = Sunday ... 6 = Saturday
echo "Day number: " . jddayofweek($julianDay, CAL_DOW_DAYNO) . "\n";

// Mode 1: full weekday name
echo "Full name:  " . jddayofweek($julianDay, CAL_DOW_LONG) . "\n";

// Mode 2: abbreviated weekday name
echo "Short name: " . jddayofweek($julianDay, CAL_DOW_SHORT) . "\n";
?>

This prints:

Day number: 4
Full name:  Thursday
Short name: Thu

March 2, 2023 was a Thursday, so the default mode returns 4 (Sunday is 0, so Thursday is the fourth index), CAL_DOW_LONG returns "Thursday", and CAL_DOW_SHORT returns "Thu".

Common gotchas

• The default is Sunday-based, not Monday-based. Mode 0 returns 0 for Sunday, not 1 for Monday. If you expect ISO-8601 numbering (Monday = 1), add your own offset or use DateTime.
• The calendar extension must be enabled. jddayofweek() and cal_to_jd() live in PHP's calendar extension. It ships with most builds but can be disabled.
• Wrong argument order in cal_to_jd(). It is (calendar, month, day, year), not (year, month, day). Swapping month and day silently produces the wrong weekday.

Conclusion

jddayofweek() maps a Julian day number to a weekday, either as a Sunday-based index (CAL_DOW_DAYNO), a full name (CAL_DOW_LONG), or an abbreviation (CAL_DOW_SHORT). Combined with cal_to_jd(), it lets you accurately determine weekdays for historical, astronomical, or cross-calendar date work.

Practice