islamic-network / calendar
A calendar / date conversion library from Gregorian to Hijri and vice versa.
Requires (Dev)
- phpunit/phpunit: ^9.6.2
README
This typed PHP library is an enhancement on the existing Hijri Calculations in the Al Adhan API (https://aladhan.com). It adds new calculation methods and unit tests leaves room for additional calculation methods to be added.
It will be replacing the current calculation in the API from January 1, 2025 onwards.
Supported Methods
This library supports the following methods for calculating the Hijri Date from a Gregorian Date:
- The existing mathematical method used on the aladhan.com API. This is the only method that accepts an adjustment parameter.
- The Umm Al Qura astronomical calculation method. This method only works (as of this writing, as the data gets enhanced more years may be supported) from 1356 AH to 2077 AH.
- The High Judiciary Council of Saudi Arabia calulcation method. This method is based on the Umm al-Qura calendar, but the dates for the months of Muḥarram, Ramaḍān, Shawwāl and Dhu ʾl-Ḥijja are adjusted after reported sightings of the lunar crescent announced by the Majlis al-Qadāʾ al-Aʿlā (High Judiciary Council of Saudi Arabia). Please also see https://webspace.science.uu.nl/~gent0113/islam/ummalqura_adjust.htm for more details.
- The Diyanet astronomical calculation method. This method only works (as of this writing, as the data gets enhanced more years may be supported) from 1318 AH to 1449 AH.
Method Credits
Both the Umm Al Qura and Diyanet calendars are based on the work of Robert Harry van Gent at https://webspace.science.uu.nl/~gent0113/islam/ and inspired by the JS script written by Tariq Alomaireeni at https://github.com/talomaireeni/Umm-Al-Qura-Calendar/tree/master?tab=readme-ov-file.
Installation
composer require islamic-network/calendar
Usage
Instantiate the Appropriate class for the method you are interested in.
Umm al Qura
use IslamicNetwork\Calendar\Models\Astronomical\UmmAlQura; // This will become the default method in the AlAdhan API in 2025 $uaq = new UmmAlQura(); /** * @var $hijriDate \IslamicNetwork\Calendar\Types\Hijri\Date */ $h = $uaq->gToH('14-02-2025'); /** * @var $g DateTime */ $g = $uaq->hToG('15-08-1446'); // Access the typed hijri date object. $h->day->number; $h->month->number; // And the standard DateTime object for the gregorian date $g->format('Y-m-d');
High Judiciary Council of Saudi Arabia
This will become the default method in the AlAdhan API in 2025.
use IslamicNetwork\Calendar\Models\Astronomical\HighJudiciaryCouncilOfSaudiArabia; // This will become the default method in the AlAdhan API in 2025 $hjcosa = new \IslamicNetwork\Calendar\Models\Astronomical\HighJudiciaryCouncilOfSaudiArabia(); /** * @var $hijriDate \IslamicNetwork\Calendar\Types\Hijri\Date */ $h = $hjcosa->gToH('14-02-2025'); /** * @var $g DateTime */ $g = $hjcosa->hToG('15-08-1446'); // Access the typed hijri date object. $h->day->number; $h->month->number; // And the standard DateTime object for the gregorian date $g->format('Y-m-d');
Diyanet
use IslamicNetwork\Calendar\Models\Astronomical\Diyanet; $diyanet = new Diyanet(); /** * @var $hijriDate \IslamicNetwork\Calendar\Types\Hijri\Date */ $h = $diyanet->gToH('14-02-2025'); /** * @var $g DateTime */ $g = $diyanet->hToG('15-08-1446'); // Access the typed hijri date object. $h->day->number; $h->month->number; // And the standard DateTime object for the gregorian date $g->format('Y-m-d');
Mathematical
This is the method used in the AlAdhan API prior to 2025.
use IslamicNetwork\Calendar\Models\Mathematical\Calculator; // This is the method used in the AlAdhan API prior to 2025 $mathematical = new Calculator(); /** * @var $hijriDate \IslamicNetwork\Calendar\Types\Hijri\Date */ $h = $mathematical->gToH('14-02-2025'); // OR $h = $mathematical->gToH('14-02-2025', 1); // to adjust the resulting hijri date forward by 1 day /** * @var $g DateTime */ $g = $mathematical->hToG('15-08-1446'); // Access the typed hijri date object. $h->day->number; $h->month->number; // And the standard DateTime object for the gregorian date $g->format('Y-m-d');
Run Unit Tests
vendor/bin/phpunit tests/
License
Apache 2.0
To Do
- Astronomical Methods - Hijri to Julian calculcation
- Jalaali Calendar