Skip to main content
Contents

Implementation · PHP

Persian (Jalali) calendar in PHP

Dependency-free PHP implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license.

Requires
PHP 8.1+
Tested with
PHP 8.5
Cross-checked against
ICU4C 77.1 (intl)
Language-specific checks
strict_types=1, distant DateTime objects, negative years
License
MIT
Version
1.0.0

Quick start

  1. Copy or download the source file into your project (no dependencies).

  2. Optionally, run its tests. The .zip keeps the folder layout they expect; from the language folder:

    implementations/php
    php test.php
  3. Call the shared API: function reference

Source

PersianCalendar.php

· 244 lines
Download
<?php
// Copyright (C) 2026 Goudarz Jafari <hi@goudarzjafari.com>
// SPDX-License-Identifier: MIT

/**
 * Solar Hijri (Persian, Jalali, Shamsi) calendar.
 *
 * Algorithm: 33-year arithmetic rule + 78-year correction table,
 * the same algorithm as ICU 77.1+ and ICU4X. Matches the astronomical calendar (52.5 E meridian)
 * for 1178-3000 AP. Months are 1-based; weekdays 0 = Saturday ... 6 = Friday.
 *
 * Inputs outside MIN_YEAR..MAX_YEAR / MIN_JDN..MAX_JDN and invalid dates throw
 * InvalidArgumentException. Within that range every intermediate value fits in
 * 32 bits, so 32-bit PHP builds work too. Requires PHP 8.1+.
 */

declare(strict_types=1);

namespace PersianCalendar;

final class PersianCalendar
{
    /** Years checked against the astronomical calendar. */
    public const VERIFIED_MIN_YEAR = 1178;
    public const VERIFIED_MAX_YEAR = 3000;

    /** Accepted input range. */
    public const MIN_YEAR = -100000;
    public const MAX_YEAR = 100000;
    /** 1 Farvardin -100000 (Gregorian -99379-03-29). */
    public const MIN_JDN = -34576287;
    /** 29 Esfand 100000 (Gregorian 100622-03-13). */
    public const MAX_JDN = 38472562;

    private const EPOCH_JDN = 1948320;

    /** Years the 33-year rule calls leap but are not; the next year is leap instead (keys for O(1) lookup). */
    private const NON_LEAP_CORRECTION = [
        1502 => 1, 1601 => 1, 1634 => 1, 1667 => 1, 1700 => 1, 1733 => 1, 1766 => 1, 1799 => 1,
        1832 => 1, 1865 => 1, 1898 => 1, 1931 => 1, 1964 => 1, 1997 => 1, 2030 => 1, 2059 => 1,
        2063 => 1, 2096 => 1, 2129 => 1, 2158 => 1, 2162 => 1, 2191 => 1, 2195 => 1, 2224 => 1,
        2228 => 1, 2257 => 1, 2261 => 1, 2290 => 1, 2294 => 1, 2323 => 1, 2327 => 1, 2356 => 1,
        2360 => 1, 2389 => 1, 2393 => 1, 2422 => 1, 2426 => 1, 2455 => 1, 2459 => 1, 2488 => 1,
        2492 => 1, 2521 => 1, 2525 => 1, 2554 => 1, 2558 => 1, 2587 => 1, 2591 => 1, 2620 => 1,
        2624 => 1, 2653 => 1, 2657 => 1, 2686 => 1, 2690 => 1, 2719 => 1, 2723 => 1, 2748 => 1,
        2752 => 1, 2756 => 1, 2781 => 1, 2785 => 1, 2789 => 1, 2818 => 1, 2822 => 1, 2847 => 1,
        2851 => 1, 2855 => 1, 2880 => 1, 2884 => 1, 2888 => 1, 2913 => 1, 2917 => 1, 2921 => 1,
        2946 => 1, 2950 => 1, 2954 => 1, 2979 => 1, 2983 => 1, 2987 => 1,
    ];

    public const MONTH_NAMES_FA = ['فروردین', 'اردیبهشت', 'خرداد', 'تیر', 'مرداد', 'شهریور',
        'مهر', 'آبان', 'آذر', 'دی', 'بهمن', 'اسفند'];
    public const MONTH_NAMES_EN = ['Farvardin', 'Ordibehesht', 'Khordad', 'Tir', 'Mordad', 'Shahrivar',
        'Mehr', 'Aban', 'Azar', 'Dey', 'Bahman', 'Esfand'];
    public const WEEKDAY_NAMES_FA = ['شنبه', 'یکشنبه', 'دوشنبه', "سه\u{200C}شنبه", 'چهارشنبه', 'پنجشنبه', 'جمعه'];
    public const WEEKDAY_NAMES_EN = ['Saturday', 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'];

    /** intdiv() and % truncate toward zero; the formulas need floor semantics. */
    private static function fdiv(int $a, int $b): int
    {
        $q = intdiv($a, $b);
        return ($a % $b !== 0 && (($a < 0) !== ($b < 0))) ? $q - 1 : $q;
    }

    /** Floor modulo for $b > 0. */
    private static function fmod(int $a, int $b): int
    {
        $r = $a % $b;
        return $r < 0 ? $r + $b : $r;
    }

    private static function checkYear(int $year): void
    {
        if ($year < self::MIN_YEAR || $year > self::MAX_YEAR) {
            throw new \InvalidArgumentException(
                sprintf('year out of range [%d, %d]: %d', self::MIN_YEAR, self::MAX_YEAR, $year)
            );
        }
    }

    private static function checkJdn(int $jdn): void
    {
        if ($jdn < self::MIN_JDN || $jdn > self::MAX_JDN) {
            throw new \InvalidArgumentException(
                sprintf('jdn out of range [%d, %d]: %d', self::MIN_JDN, self::MAX_JDN, $jdn)
            );
        }
    }

    public static function isLeapYear(int $year): bool
    {
        self::checkYear($year);
        if (isset(self::NON_LEAP_CORRECTION[$year])) {
            return false;
        }
        if (isset(self::NON_LEAP_CORRECTION[$year - 1])) {
            return true;
        }
        return self::fmod(25 * $year + 11, 33) < 8;
    }

    public static function daysInMonth(int $year, int $month): int
    {
        self::checkYear($year);
        if ($month < 1 || $month > 12) {
            throw new \InvalidArgumentException("month out of range: $month");
        }
        if ($month <= 6) {
            return 31;
        }
        if ($month <= 11) {
            return 30;
        }
        return self::isLeapYear($year) ? 30 : 29;
    }

    /** True for a real Persian date in the accepted range; never throws. */
    public static function isValidDate(int $year, int $month, int $day): bool
    {
        return $year >= self::MIN_YEAR && $year <= self::MAX_YEAR
            && $month >= 1 && $month <= 12 && $day >= 1 && $day <= self::daysInMonth($year, $month);
    }

    private static function nowruzJdn(int $year): int
    {
        $jdn = self::EPOCH_JDN + 365 * ($year - 1) + self::fdiv(8 * $year + 21, 33);
        if (isset(self::NON_LEAP_CORRECTION[$year - 1])) {
            $jdn--;
        }
        return $jdn;
    }

    private static function daysBeforeMonth(int $month): int
    {
        return $month <= 7 ? 31 * ($month - 1) : 30 * ($month - 1) + 6;
    }

    /** Julian Day Number of a Persian date. */
    public static function toJdn(int $year, int $month, int $day): int
    {
        if (!self::isValidDate($year, $month, $day)) {
            throw new \InvalidArgumentException("invalid Persian date: $year/$month/$day");
        }
        return self::nowruzJdn($year) + self::daysBeforeMonth($month) + $day - 1;
    }

    /** @return array{int, int, int} [year, month, day] */
    public static function fromJdn(int $jdn): array
    {
        self::checkJdn($jdn);
        $year = 1 + self::fdiv(33 * ($jdn - self::EPOCH_JDN) + 3, 12053);
        while ($jdn >= self::nowruzJdn($year + 1)) {
            $year++;
        }
        while ($jdn < self::nowruzJdn($year)) {
            $year--;
        }
        $doy = $jdn - self::nowruzJdn($year); // 0-based
        if ($doy < 186) {
            return [$year, intdiv($doy, 31) + 1, $doy % 31 + 1];
        }
        $doy -= 186;
        return [$year, intdiv($doy, 30) + 7, $doy % 30 + 1];
    }

    private static function gregorianDaysInMonth(int $year, int $month): int
    {
        if ($month === 2) {
            return ($year % 4 === 0 && ($year % 100 !== 0 || $year % 400 === 0)) ? 29 : 28;
        }
        return in_array($month, [4, 6, 9, 11], true) ? 30 : 31;
    }

    /** JDN of a proleptic Gregorian date (astronomical year numbering: 0 = 1 BC). */
    public static function gregorianToJdn(int $year, int $month, int $day): int
    {
        // Year bounds first, so the arithmetic below cannot overflow.
        if ($year < -99379 || $year > 100622 || $month < 1 || $month > 12
            || $day < 1 || $day > self::gregorianDaysInMonth($year, $month)) {
            throw new \InvalidArgumentException("invalid Gregorian date: $year-$month-$day");
        }
        $a = self::fdiv(14 - $month, 12);
        $y = $year + 4800 - $a;
        $m = $month + 12 * $a - 3;
        $jdn = $day + self::fdiv(153 * $m + 2, 5) + 365 * $y + self::fdiv($y, 4)
            - self::fdiv($y, 100) + self::fdiv($y, 400) - 32045;
        self::checkJdn($jdn);
        return $jdn;
    }

    /** @return array{int, int, int} proleptic Gregorian [year, month, day] */
    public static function jdnToGregorian(int $jdn): array
    {
        self::checkJdn($jdn);
        $a = $jdn + 32044;
        $b = self::fdiv(4 * $a + 3, 146097);
        $c = $a - self::fdiv(146097 * $b, 4);
        $d = self::fdiv(4 * $c + 3, 1461);
        $e = $c - self::fdiv(1461 * $d, 4);
        $m = self::fdiv(5 * $e + 2, 153);
        return [
            100 * $b + $d - 4800 + self::fdiv($m, 10),
            $m + 3 - 12 * self::fdiv($m, 10),
            $e - self::fdiv(153 * $m + 2, 5) + 1,
        ];
    }

    /** @return array{int, int, int} */
    public static function toGregorian(int $year, int $month, int $day): array
    {
        return self::jdnToGregorian(self::toJdn($year, $month, $day));
    }

    /** @return array{int, int, int} */
    public static function fromGregorian(int $year, int $month, int $day): array
    {
        return self::fromJdn(self::gregorianToJdn($year, $month, $day));
    }

    /**
     * Persian date of a DateTimeInterface, read in its own time zone.
     * Call ->setTimezone(new DateTimeZone('Asia/Tehran')) first if needed.
     * @return array{int, int, int}
     */
    public static function fromDateTime(\DateTimeInterface $dt): array
    {
        return self::fromGregorian((int) $dt->format('Y'), (int) $dt->format('n'), (int) $dt->format('j'));
    }

    /** 0 = Saturday (شنبه) ... 6 = Friday (جمعه). */
    public static function dayOfWeek(int $year, int $month, int $day): int
    {
        return self::fmod(self::toJdn($year, $month, $day) + 2, 7);
    }

    /** 1 ... 365/366. */
    public static function dayOfYear(int $year, int $month, int $day): int
    {
        if (!self::isValidDate($year, $month, $day)) {
            throw new \InvalidArgumentException("invalid Persian date: $year/$month/$day");
        }
        return self::daysBeforeMonth($month) + $day;
    }
}

Tests

test.php

155 lines
PHPDownload
<?php
// Copyright (C) 2026 Goudarz Jafari <hi@goudarzjafari.com>
// SPDX-License-Identifier: MIT

// Checks PersianCalendar.php against /data. Run: php implementations/php/test.php
declare(strict_types=1);

require __DIR__ . '/PersianCalendar.php';

use PersianCalendar\PersianCalendar as PC;

$checks = 0;
function check(bool $ok, string $context): void
{
    global $checks;
    $checks++;
    if (!$ok) {
        fwrite(STDERR, "failed: $context\n");
        exit(1);
    }
}

function csv(string $name): array
{
    $lines = file(__DIR__ . "/../../data/$name", FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
    return array_map(fn ($l) => explode(',', $l), array_slice($lines, 1));
}

foreach (csv('years.csv') as $r) {
    $y = (int) $r[0];
    $leap = $r[1] === '1';
    check(PC::isLeapYear($y) === $leap, "leap $y");
    check(PC::daysInMonth($y, 12) === ($leap ? 30 : 29), "esfand $y");
    check(vsprintf('%04d-%02d-%02d', PC::toGregorian($y, 1, 1)) === $r[3], "nowruz $y");
    check(PC::toJdn($y, 1, 1) === (int) $r[4], "jdn $y");
    check(PC::dayOfWeek($y, 1, 1) === (int) $r[5], "weekday $y");
    // every day of the year against the ground truth, both directions
    for ($doy = 0; $doy < (int) $r[2]; $doy++) {
        $p = $doy < 186 ? [$y, intdiv($doy, 31) + 1, $doy % 31 + 1] : [$y, intdiv($doy - 186, 30) + 7, ($doy - 186) % 30 + 1];
        $jdn = (int) $r[4] + $doy;
        check(PC::fromJdn($jdn) === $p && PC::toJdn(...$p) === $jdn, implode('/', $p));
    }
}

foreach (csv('test-vectors.csv') as $r) {
    $v = array_map('intval', $r);
    $p = [$v[0], $v[1], $v[2]];
    $g = [$v[3], $v[4], $v[5]];
    $ctx = implode('/', $p);
    check(PC::toGregorian(...$p) === $g, $ctx);
    check(PC::fromGregorian(...$g) === $p, $ctx);
    check(PC::toJdn(...$p) === $v[6], $ctx);
    check(PC::fromJdn($v[6]) === $p, $ctx);
    check(PC::dayOfWeek(...$p) === $v[7], $ctx);
}

$first = PC::toJdn(PC::VERIFIED_MIN_YEAR, 1, 1);
$last = PC::toJdn(PC::VERIFIED_MAX_YEAR, 12, PC::daysInMonth(PC::VERIFIED_MAX_YEAR, 12));
$prev = PC::fromJdn($first - 1);
for ($jdn = $first; $jdn <= $last; $jdn++) {
    $d = PC::fromJdn($jdn);
    check(PC::toJdn(...$d) === $jdn, "round trip $jdn");
    $consecutive = ($d[2] === $prev[2] + 1 && $d[1] === $prev[1] && $d[0] === $prev[0])
        || ($d[2] === 1 && (($d[1] === $prev[1] + 1 && $d[0] === $prev[0])
            || ($d[1] === 1 && $prev[1] === 12 && $d[0] === $prev[0] + 1)));
    check($consecutive, "consecutive $jdn");
    $prev = $d;
}

// Extrapolated years: years <= 0 make intermediate values negative (floor division matters).
check(PC::toJdn(-1000, 1, 1) === 1582713 && PC::toJdn(0, 1, 1) === 1947955 && PC::toJdn(4000, 1, 1) === 3408925, 'fixed jdn');
check(PC::fromJdn(0) === [-5334, 9, 3] && PC::dayOfWeek(-1000, 1, 1) === 1, 'jdn 0 / weekday');
check(PC::isLeapYear(-3) && !PC::isLeapYear(-1000), 'negative leap years');
foreach ([[-1000, 1177], [3001, 4000]] as [$firstYear, $lastYear]) {
    $a = PC::toJdn($firstYear, 1, 1);
    $b = PC::toJdn($lastYear, 12, PC::daysInMonth($lastYear, 12));
    $p = PC::fromJdn($a - 1);
    for ($jdn = $a; $jdn <= $b; $jdn++) {
        $d = PC::fromJdn($jdn);
        check(PC::toJdn(...$d) === $jdn && PC::gregorianToJdn(...PC::jdnToGregorian($jdn)) === $jdn, "round trip $jdn");
        $consecutive = ($d[2] === $p[2] + 1 && $d[1] === $p[1] && $d[0] === $p[0])
            || ($d[2] === 1 && (($d[1] === $p[1] + 1 && $d[0] === $p[0])
                || ($d[1] === 1 && $p[1] === 12 && $d[0] === $p[0] + 1)));
        check($consecutive, "consecutive $jdn");
        $p = $d;
    }
}
check(PC::isValidDate(1403, 12, 30), '1403/12/30');
check(!PC::isValidDate(1404, 12, 30), '1404/12/30');
check(PC::isValidDate(1404, 6, 31), '1404/6/31');
check(!PC::isValidDate(1404, 7, 31), '1404/7/31');
check(!PC::isValidDate(1404, 13, 1), '1404/13/1');
check(!PC::isValidDate(1404, 0, 1), '1404/0/1');
check(!PC::isValidDate(1404, 1, 0), '1404/1/0');
try {
    PC::toJdn(1404, 12, 30);
    check(false, 'should throw');
} catch (InvalidArgumentException) {
    $checks++;
}
check(PC::fromGregorian(2025, 3, 21) === [1404, 1, 1], '2025-03-21');
check(PC::fromGregorian(1979, 2, 11) === [1357, 11, 22], '1979-02-11');
$instant = new DateTimeImmutable('2025-03-20T21:00:00Z');
check(PC::fromDateTime($instant->setTimezone(new DateTimeZone('Asia/Tehran'))) === [1404, 1, 1], 'Tehran');
check(PC::fromDateTime($instant) === [1403, 12, 30], 'UTC');
check(PC::dayOfYear(1404, 7, 1) === 187, 'doy');
check(PC::WEEKDAY_NAMES_EN[PC::dayOfWeek(1404, 1, 1)] === 'Friday', 'friday');

// Limits: exact boundaries; everything outside throws (no overflow to float, no hang).
function throws(callable $f, string $class = InvalidArgumentException::class): bool
{
    try {
        $f();
        return false;
    } catch (Throwable $e) {
        return $e instanceof $class;
    }
}
check(PC::toJdn(PC::MIN_YEAR, 1, 1) === PC::MIN_JDN && PC::toJdn(PC::MAX_YEAR, 12, 29) === PC::MAX_JDN, 'limits');
check(PC::fromJdn(PC::MIN_JDN) === [PC::MIN_YEAR, 1, 1] && PC::fromJdn(PC::MAX_JDN) === [PC::MAX_YEAR, 12, 29], 'limit dates');
check(PC::jdnToGregorian(PC::MIN_JDN) === [-99379, 3, 29] && PC::jdnToGregorian(PC::MAX_JDN) === [100622, 3, 13], 'limit gregorian');
foreach ([PC::MIN_JDN - 1, PC::MAX_JDN + 1, PHP_INT_MAX, PHP_INT_MIN, 2 ** 53] as $bad) {
    check(throws(fn () => PC::fromJdn($bad)) && throws(fn () => PC::jdnToGregorian($bad)), "jdn $bad");
}
foreach ([PC::MIN_YEAR - 1, PC::MAX_YEAR + 1, PHP_INT_MAX, PHP_INT_MIN] as $bad) {
    check(!PC::isValidDate($bad, 1, 1), "isValidDate $bad");
    check(throws(fn () => PC::toJdn($bad, 1, 1)) && throws(fn () => PC::isLeapYear($bad)), "year $bad");
}
foreach ([[2025, 2, 29], [2025, 2, 30], [2025, 13, 1], [2025, 0, 1], [2025, 4, 31], [2025, 1, 0],
          [100622, 3, 14], [PHP_INT_MAX, 1, 1]] as $bad) {
    check(throws(fn () => PC::gregorianToJdn(...$bad)) && throws(fn () => PC::fromGregorian(...$bad)), implode('-', $bad));
}
check(PC::gregorianToJdn(2024, 2, 29) === 2460370 && PC::gregorianToJdn(2000, 2, 29) === 2451604, 'Gregorian leap days');
check(throws(fn () => PC::gregorianToJdn(1900, 2, 29)), '1900 is not a Gregorian leap year');
check(throws(fn () => PC::fromJdn(1.5), TypeError::class), 'non-integer');
check(throws(fn () => PC::fromDateTime((new DateTimeImmutable())->setDate(200000, 1, 1))), 'far DateTime');
check(PC::fromDateTime((new DateTimeImmutable('2025-03-21T00:00:00Z'))->setDate(-5, 1, 1)) === PC::fromGregorian(-5, 1, 1), 'negative-year DateTime');
// Every year MIN_YEAR..MAX_YEAR: years are contiguous, first and last day round-trip, and the leap
// years sit where every other implementation (and ICU 77.1+) puts them (checksums).
$expected = PC::MIN_JDN;
$leaps = 0;
$nowruzSum = 0;
for ($y = PC::MIN_YEAR; $y <= PC::MAX_YEAR; $y++) {
    $nowruz = PC::toJdn($y, 1, 1);
    $leap = PC::isLeapYear($y) ? 1 : 0;
    if ($nowruz !== $expected || PC::fromJdn($nowruz) !== [$y, 1, 1] || PC::daysInMonth($y, 12) !== 29 + $leap
        || PC::fromJdn($nowruz + 364 + $leap) !== [$y, 12, 29 + $leap]) {
        check(false, "year $y");
    }
    $leaps += $leap;
    $nowruzSum += $nowruz;
    $expected = $nowruz + 365 + $leap;
}
check($expected - 1 === PC::MAX_JDN && $leaps === 48485 && $nowruzSum === 389592978180, 'full-range checksums');
echo "OK: $checks checks passed\n";

Other languages