Download the PHP package rizqshadi/hijri-date without Composer
On this page you can find all versions of the php package rizqshadi/hijri-date. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download rizqshadi/hijri-date
More information about rizqshadi/hijri-date
Files in rizqshadi/hijri-date
Package hijri-date
Short Description Hijri (Islamic) calendar for PHP: today's Hijri date by location, Gregorian <-> Hijri conversion (Umm al-Qura & tabular civil), and a Ramadan countdown.
License MIT
Homepage https://github.com/ShadiRq/hijri-date
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package hijri-date
Hijri Date
A Hijri (Islamic) calendar library for PHP 8.1+.
- Today's Hijri date based on where the user is (timezone, coordinates, or country), with an optional day starts at sunset (maghrib) mode.
- Gregorian ↔ Hijri conversion. Umm al-Qura (Saudi Arabia's official calendar) is the default, and the tabular civil calendar is available in pure PHP.
- Ramadan countdown in Hijri months and days, e.g. "4 months and 16 days until Ramadan 1448" / "باقي 4 أشهر و16 يومًا على رمضان 1448".
- English and Arabic month and day names, Arabic-Indic digits, right-to-left display helpers, JSON serialization, and immutable value objects throughout.
Requirements
- PHP 8.1 or newer
- ext-intl for the Umm al-Qura calendar (recommended). Without it, you can still use the civil calendar.
Installation
About ext-intl
| Calendar | CalendarType |
Needs |
|---|---|---|
| Umm al-Qura (default) | CalendarType::UmmAlQura |
ext-intl (ICU) |
| Tabular / civil | CalendarType::Civil |
nothing, pure PHP |
If you request Umm al-Qura without intl, an IntlNotAvailableException explains how to install it. The library never silently falls back to the civil calendar, because the two can differ by a day or two.
Quick start
Usage
Location
"Today" depends on the local date: 1 am in Riyadh is still the previous day in New York.
fromCoordinates()without a timezone picks the zone whose reference city is nearest. A few extra anchor cities (Mecca, Jeddah, Alexandria, Lahore, Delhi…) cover large zones. This is a heuristic, not a border lookup, so pass the timezone explicitly near borders.fromCountry()uses the main timezone of countries that have several (US→ America/New_York,RU→ Europe/Moscow,AU→ Australia/Sydney…). UsefromTimezone()when you know the exact zone.
Today's date
Gregorian → Hijri
Hijri → Gregorian
Formatting
format($pattern, $locale = 'en', $arabicDigits = false, $rtl = false) accepts PHP date()-style tokens:
| Token | Meaning | Example |
|---|---|---|
j |
day | 1 |
d |
day, 2 digits | 01 |
n |
month | 9 |
m |
month, 2 digits | 09 |
F |
month name | Ramadan / رمضان |
Y |
year | 1447 |
y |
year, 2 digits | 47 |
l |
weekday name | Wednesday / الأربعاء |
Prefix a character with a backslash to print it literally.
Ramadan countdown
- The months and days are Hijri months and days. The days are what is left of the current month, including today.
- During Ramadan (day 2 onward),
isRamadanNowistrue,dayOfRamadanis set, and the countdown targets next year's Ramadan. - On 1 Ramadan itself,
months = days = totalDays = 0,isRamadanNow = true, anddayOfRamadan = 1. - From Shawwal onward, it counts to next year's Ramadan.
- Arabic output uses the correct plural forms: شهر واحد، شهران، 3–10 أشهر، 11+ شهرًا (and likewise for days).
Arabic and right-to-left display
Arabic output is plain text in logical order. It displays correctly in any right-to-left context, such as an HTML element with dir="rtl":
When Arabic is mixed into left-to-right text (English sentences, logs, LTR UIs), the Unicode bidi algorithm can reorder the surrounding numbers. For example, (1 رمضان 1447) displays as (1447 رمضان 1). Pass rtl: true to wrap Arabic output in an invisible right-to-left isolate (U+2067 … U+2069):
rtl is off by default so that stored and compared strings contain no invisible characters. It only affects 'ar' output.
Terminals / CLI
Most terminals (the VS Code terminal, Windows Terminal, the Windows console) support neither right-to-left text nor Arabic letter joining. They draw characters left to right in stored order, so Arabic appears reversed with unjoined letters. Rtl::visual() prepares text for them. It joins the letters into their connected forms (including لا) and reorders each line with the Unicode Bidirectional Algorithm, keeping numbers left to right and honouring rtl: true isolates:
Use Rtl::visual() only for such displays. Never use it for HTML, databases or APIs. A bidi-aware display (browser, GNOME Terminal, Konsole) reverses the text itself and would show it backwards.
Calendar choice
Moon-sighting adjustment
Local announcements can differ from Umm al-Qura by a day. Shift the calendar by -2 to +2 days:
Day starts at sunset
The Islamic day begins at maghrib. With this option, the Hijri date advances once local time passes sunset. Sunset is computed with PHP's built-in date_sun_info() from the location's coordinates:
- The location needs coordinates, or a
LocationExceptionis thrown (e.g.Location::fromTimezone('UTC')has none). - The result doesn't depend on your server's default timezone.
- At high latitudes in summer, sunset can come after midnight. The date then changes at that sunset.
- During polar day or polar night there is no sunset, so the day changes at midnight.
fromGregorian()andtoGregorian()work with calendar days, so sunset does not affect them.
Immutability
Hijri, Location, HijriDate and RamadanCountdown are immutable. The with*() methods return new instances: withLocation(), withCalendar(), withAdjustment(), withDayStartsAtSunset().
Exceptions
Every exception implements RizqShadi\HijriDate\Exception\HijriDateException, so one catch handles them all:
InvalidDateException(extendsInvalidArgumentException): a bad Gregorian or Hijri date, or one before the Hijri calendar began.LocationException(extendsInvalidArgumentException): an unknown timezone or country, invalid coordinates, or missing coordinates for sunset mode.InvalidArgumentException(extends PHP'sInvalidArgumentException): an unsupported locale or an out-of-range adjustment.IntlNotAvailableException(extendsRuntimeException): Umm al-Qura was requested without ext-intl.
Low-level converters
Conversions are done at 12:00 UTC, so DST and midnight edge cases cannot shift the result. The converters don't validate their input; Hijri does.
Example
A runnable example prints today's date in Riyadh (English and Arabic), both conversions and the Ramadan countdown:
On a terminal it passes its output through Rtl::visual(). If your terminal handles right-to-left text itself, set HIJRI_TERMINAL_BIDI=1.
Testing
From a clone of the repository:
The tests check known Umm al-Qura dates against ICU and round-trip conversions over 20 years. They also compare the pure-PHP civil calendar with ICU's islamic-civil day by day over 40 years, and cover timezones, sunset rollover, adjustments and every Ramadan countdown edge case.
Support
Found a bug or have a question? Open an issue at github.com/ShadiRq/hijri-date.
License
MIT © Shadi Rizq. See LICENSE.
