README

Accurate Gregorian ⇄ Hijri date conversion for PHP, based on the official Umm al-Qura calendar of Saudi Arabia — not a fixed arithmetic approximation.

Why this instead of a tabular Hijri calendar?

A tabular/arithmetic Hijri calendar (fixed 30-year leap cycle) is simple but can drift a day or two from the real, officially-recognized Hijri date. This package instead does a table lookup against actual Umm al-Qura month-start data, so results match the civil calendar used in Saudi Arabia for government and business dates.

Coverage: 1 Muharram 1356 AH (14 March 1937 CE) to approximately 1500 AH (16 November 2077 CE). Dates outside this range throw OutOfRangeException.

Note: This is the civil/administrative Umm al-Qura calendar. For religious observance (e.g. the exact start of Ramadan), local moon-sighting announcements may differ by a day.

Installation

composer require mariamalandejani/hijri-date

Usage

use HijriDate\HijriDate;

// Gregorian -> Hijri
$hijri = HijriDate::fromGregorian(new DateTimeImmutable('2024-03-11'));
echo $hijri; // 1445-09-01
echo $hijri->format('j F Y'); // 1 Ramadan 1445
echo $hijri->monthName('ar'); // رمضان

// Hijri -> Gregorian
$hijri = new HijriDate(1445, 9, 1);
echo $hijri->toGregorian()->format('Y-m-d'); // 2024-03-11

// Today
$today = HijriDate::today();

// Arithmetic
$eid = $hijri->addDays($hijri->daysInMonth); // roll into Shawwal
$nextMonth = $hijri->addMonths(1);
$diff = $hijri->diffInDays($eid);

API

HijriDate::fromGregorian(DateTimeInterface $date): self
HijriDate::today(?DateTimeZone $tz = null): self
new HijriDate(int $year, int $month, int $day) — throws OutOfRangeException if invalid or out of the table's range
->toGregorian(): DateTimeImmutable
->addDays(int), ->addMonths(int), ->diffInDays(HijriDate $other): int
->format(string $format) — tokens: Y m n d j F M
->monthName(string $locale = 'en') — 'en' or 'ar'
HijriConverter::daysInHijriMonth(int $year, int $month): int — static helper, 29 or 30

Data source

The bundled month-boundary table (src/UmmAlQuraData.php) derives from the reference dataset compiled by R.H. van Gent (Utrecht University), "The Umm al-Qura calendar of Saudi Arabia". This same dataset underlies numerous independent open-source Hijri converters across languages (e.g. xsoh/Hijri.js, tytkal/python-hijiri-ummalqura, hablullah/go-hijri), and the conversion algorithm here has been cross-checked against their published example outputs.

Testing

composer install
composer test

License

MIT

mariamalandejani / hijri-date

Package info

Security

Statistics