juliantojd()

Introduction

The juliantojd() function converts a date in the Julian calendar into a Julian Day Count — a single integer that counts days continuously from noon UTC on January 1, 4713 BC. Because every date maps to one number, the Julian Day Count makes it easy to compute the number of days between two dates or to translate dates between different calendars (Gregorian, Jewish, French Republican, and so on).

This chapter covers the function's signature, its argument order (a common source of bugs), valid ranges, return values, and several worked examples. It also shows how the Julian Day Count (an integer, as PHP uses it) relates to the astronomical Julian Date (which can include a fractional time of day).

Terminology: PHP's calendar functions work with the Julian Day Count — an integer number of whole days. Astronomers use the closely related Julian Date, which adds a fractional part for the time of day (a Julian Date begins at noon, so JD = count + 0.5 at midnight).

Syntax

juliantojd(int $month, int $day, int $year): int

The argument order is month, day, year — not day, month, year. Mixing these up is the most common mistake with this function, and an out-of-range value silently returns 0 instead of raising an error.

Return value: the Julian Day Count as an integer, or 0 if the date falls outside the valid range.

juliantojd() is part of PHP's Calendar extension, which must be enabled (it is bundled with most PHP distributions).

Basic example

Convert October 15, 1582 — the first day of the Gregorian calendar in many countries — from a Julian calendar date to a Julian Day Count:

<?php
$month = 10;
$day   = 15;
$year  = 1582;

$jdCount = juliantojd($month, $day, $year);
echo $jdCount; // 2299171
?>

Note the order: $month comes first. Passing the day first by mistake usually produces an invalid month (for example juliantojd(15, 10, 1582)), which returns 0.

Detecting invalid dates

Because an out-of-range value returns 0 rather than throwing, check the result before using it. (Note that a slightly out-of-range day, like February 30, is normalized rather than rejected; an out-of-range month or year is what triggers the 0.)

<?php
$jdCount = juliantojd(13, 1, 2024); // Month 13 does not exist

if ($jdCount === 0) {
    echo "Invalid Julian calendar date";
} else {
    echo $jdCount;
}
// Invalid Julian calendar date
?>

Calculating the days between two dates

A common reason to convert to a Julian Day Count is arithmetic: subtract two counts to get the number of days between the dates, regardless of months or leap years.

<?php
$start = juliantojd(1, 1, 2000);  // 2451558
$end   = juliantojd(12, 31, 2000); // 2451923

echo $end - $start; // 365
?>

Julian Day Count vs. astronomical Julian Date

PHP returns a whole-day integer. To get the astronomical Julian Date — which starts at noon — add 0.5 for a midnight timestamp:

<?php
$jdCount = 2451558;
$julianDate = $jdCount + 0.5;
echo $julianDate; // 2451558.5
?>

To go the other way, subtract 0.5 and take the integer part:

<?php
$julianDate = 2451558.5;
$jdCount = (int) floor($julianDate - 0.5);
echo $jdCount; // 2451558
?>

When would I use this?

• Date arithmetic that must ignore month lengths and leap years — convert both dates to a count and subtract.
• Calendar conversion — pair juliantojd() with jdtogregorian() or jdtojewish() to translate a Julian date into another calendar.
• Astronomy and chronology, where the continuous day count is the standard way to reference historical and celestial events.

Related functions

• jdtojulian() — the inverse: Julian Day Count back to a Julian calendar date.
• gregoriantojd() — convert a Gregorian date to a Julian Day Count.
• jddayofweek() — find the day of the week for a Julian Day Count.
• jdmonthname() — get a month name for a Julian Day Count.

Summary

juliantojd() turns a Julian calendar date into a Julian Day Count, using the argument order month, day, year. It returns an integer (or 0 for invalid dates), which you can subtract to measure spans of days, convert between calendars, or derive the astronomical Julian Date by adding 0.5.

graph TD;
    A[Julian calendar date<br/>month, day, year] --> B[juliantojd()];
    B --> C[Julian Day Count<br/>integer];
    C --> D[jdtojulian() / jdtogregorian()];
    D --> E[Calendar date in another system];

Practice