پرش به محتوای اصلی
فهرست مطالب

پیاده‌سازی · PHP

تقویم شمسی (جلالی) در PHP

پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در PHP: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT.

پیش‌نیاز
PHP 8.1+
تست‌شده با
PHP 8.5
مقایسه‌شده با
ICU4C 77.1 (intl)
بررسی‌های اختصاصی
فعال بودن strict_types، تست DateTime برای تاریخ‌های خیلی دور و سال‌های منفی
مجوز
MIT
نسخه
1.0.0

شروع سریع

  1. فایل کد را کپی یا دانلود کنید و در پروژه‌تان بگذارید (بدون هیچ وابستگی).

  2. در صورت تمایل تست‌هایش را هم اجرا کنید. فایل zip همان ساختار پوشه‌ای را دارد که تست‌ها لازم دارند؛ از داخل پوشهٔ زبان:

    implementations/php
    php test.php
  3. توابع مشترک را صدا بزنید: راهنمای توابع

کد

PersianCalendar.php

· ۲۴۴ خط
دانلود
<?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;
    }
}

تست‌ها

test.php

۱۵۵ خط
PHPدانلود
<?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";

زبان‌های دیگر