PHPackages                             mo7mud/hijri-date - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mo7mud/hijri-date

ActiveLibrary[Utility & Helpers](/categories/utility)

mo7mud/hijri-date
=================

Laravel helper package for Hijri dates.

v2.4.0(9mo ago)131↓78.6%MITPHPPHP >=8.0

Since Apr 5Pushed 9mo agoCompare

[ Source](https://github.com/Mo7mud/Laravel-hijri-date)[ Packagist](https://packagist.org/packages/mo7mud/hijri-date)[ RSS](/packages/mo7mud-hijri-date/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (1)Versions (13)Used By (0)

Hijri Date Umm al-Qura calendar
===============================

[](#hijri-date-umm-al-qura-calendar)

Laravel helper package for Hijri dates. Supports displaying dates in Arabic, Bengali, Dhivehi and English out of the box, with support for further customizations or adding a language of your choice.

- [Installation](#installation)
- [Creating dates](#creating-dates)
    - [Customizing how dates are converted between Hijri and Gregorian](#customizing-how-dates-are-converted-between-hijri-and-gregorian)
- [Available methods](#available-methods)
    - [Conversions](#conversions)
    - [Calculations](#calculations)
    - [Comparisons](#comparisons)
    - [Formatting](#formatting)
- [Casting](#casting)
- [Validation](#validation)
- [Localization](#localization)
    - [Adding a language](#adding-a-language)
- [Migrating from v1 to v2](#migrating-from-v1-to-v2)

Installation
------------

[](#installation)

```
composer require mo7mud/hijri-date

```

To publish configuration files:

```
php artisan vendor:publish --provider="Mo7mud\HijriDate\HijriDateServiceProvider" --tag="config"
```

Creating dates
--------------

[](#creating-dates)

All of the following methods return an instance of `Mo7mud\HijriDate\HijriDate`.

```
use Carbon\Carbon;

new HijriDate();                    // 1st Muharram 1000
new HijriDate(1443, 9, 1);          // 1st Ramadan 1443
HijriDate::parse('1443-09-01');     // 1st Ramadan 1443

// From Gregorian
HijriDate::createFromGregorian();              // Today's date
today_hijri();                                 // Today's date
HijriDate::createFromGregorian('1991-12-01');  // 20th Jumada al-Ula 1412
$input = Carbon::parse('2002-03-04');
HijriDate::createFromGregorian($input);        // 12th Dhul-Hijja 1422
```

### Customizing how dates are converted between Hijri and Gregorian

[](#customizing-how-dates-are-converted-between-hijri-and-gregorian)

By default, the package uses [an external map](https://gist.githubusercontent.com/Mo7mud/181391cfc18bbaf34ad3d961d659a6f4/raw) between Hijri and Gregorian dates in Umm al-Qura to convert between the two. This map is cached and reused for subsequent conversions.

You may customize for how long the map is cached by changing `config/hijri.php` > `conversion.cache_period`.

You may manually re-fetch data from the external source by running `php artisan hijri:fetch`.

The package also comes with an alternative class for converting dates using calculations instead of a map. You may enable it by changing `config/hijri.php` > `conversion.converter` to `\Remls\HijriDate\Converters\MakkaEstimateG2HConverter::class`.

You may customize how dates are converted by:

- providing your own map in `config/hijri.php` > `conversion.data_url`
- providing your own custom converter class in `config/hijri.php` > `conversion.converter`
    - The class must implement `\Remls\HijriDate\Converters\Contracts\GregorianToHijriConverter`.

Available methods
-----------------

[](#available-methods)

### Conversions

[](#conversions)

```
// Gregorian to Hijri
HijriDate::createFromGregorian('1991-12-01'); // returns HijriDate

// Hijri to Gregorian
$date = new HijriDate(1443, 9, 1);
$date->getGregorianDate();                    // returns Carbon
```

### Getters & Setters

[](#getters--setters)

```
$date = new HijriDate(1443, 9, 1);

$date->getYear();  // returns int 1443
$date->setYear(1447);  // takes int $year returns HijriDate
$date->getMonth() // returns int 9
$date->setMonth(5) // takes int $month returns HijriDate
$date->getDay() // returns int 1
$date->setDay(15) // takes int $day returns HijriDate
$date->getLocale() // returns string locale
$date->setLocale() // takes string locale (eg. "ar") returns HijriDate

```

You may customise how the conversion works, as detailed [here](#customizing-how-dates-are-converted-between-hijri-and-gregorian).

### Calculations

[](#calculations)

```
$date = new HijriDate(1443, 9, 1);   // 1st Ramadan 1443
$date->addDays(1);                   // 2nd Ramadan 1443
$date->subDays(3);                   // 28th Sha'ban 1443
$date2 = new HijriDate(1443, 8, 20); // 20th Sha'ban 1443
$date->diffInDays($date2);           // 8
```

### Comparisons

[](#comparisons)

You may compare two HijriDate objects `$a` and `$b` using the following methods:

MethodDescription`$a->compareWith($b)`Returns -1 if $a < $b.
Returns 0 if $a == $b.
Returns 1 if $a > $b.`$a->equalTo($b)`Returns true if $a == $b.`$a->greaterThan($b)`Returns true if $a > $b (a is after b).`$a->lessThan($b)`Returns true if $a < $b (a is before b).`$a->greaterThanOrEqualTo($b)`Returns true if $a >= $b (a is after or equal to b).`$a->lessThanOrEqualTo($b)`Returns true if $a <= $b (a is before or equal to b).### Formatting

[](#formatting)

Each HijriDate object will have a set locale when it is created. This locale will be used for formatting.

The locale is `'dv'` by default, but you may customize it by:

- passing locale in constructor (eg: `new HijriDate(1443, 9, 1, 'en')`)
- changing locale after creation (eg: `$date->setLocale('en')`)
- changing `default_locale` in configuration, so all HijriDate objects are created using that default locale

The following options are supported with `$date->format()`:

OptionDescriptionExampledDay of month (with leading zero)01 ... 30DWeekday (short)Sun ... SatjDay of month (without leading zero)1 ... 30l
(lowercase L)WeekdaySunday ... SaturdayFMonthMuharram ... Dhul-HijjamMonth (number, with leading zero)01 ... 12MMonth (short)Mhr ... DhHnMonth (number, without leading zero)1 ... 12YYear1000 ... 1999yYear (final two digits)00 ... 99```
$date = new HijriDate(1443, 9, 1);  // 1st Ramadan 1443
$date->format("F");                 // "ރަމަޟާން" (using default locale 'dv')

$date->setLocale('ar');
$date->format("F Y");               // "رمضان 1443"
// Use numerals from locale
$date->format("F Y", true);         // "رمضان ١٤٤٣"
```

Casting
-------

[](#casting)

The field to be cast must be a string field on database.

```
// App/Models/YourModel.php

class YourModel
{
    ...

    protected $casts = [
        ...
        'your_hijri_date_field' => HijriDate::class,
    ];
}
```

This will automatically store data as `Y-m-d` string in database, and cast to `Remls\HijriDate\HijriDate` when accessing.

Validation
----------

[](#validation)

Any string that passes the following conditions is considered a valid Hijri date:

- in the format `Y-m-d`
- year between 1000 and 1999 (This can be changed in config.)
- month between 1 and 12
- day between 1 and 30

```
use Remls\HijriDate\Rules\ValidHijriDate;

...
request()->validate([
    'your_hijri_date_field' => ['required', new ValidHijriDate],
]);
```

Note that validation error messages will use app's locale (unlike formatting).

Localization
------------

[](#localization)

Publish translation files by using:

```
php artisan vendor:publish --provider="Remls\HijriDate\HijriDateServiceProvider" --tag="lang"
```

You may then customize strings as needed.

### Adding a language

[](#adding-a-language)

To add support for another language:

1. Publish the configuration file. The file will be copied to `config/hijri.php`.
2. Publish the translation files. The files will be copied to `lang/vendor/hijri`.
3. Copy one of the existing translation folders, and rename it with the language code of your choice. Eg: `lang/vendor/hijri/es`
4. Change strings to their respective translations.
5. Add the language code to `supported_locales` in `config/hijri.php`.
6. (Optional) Change `default_locale` in `config/hijri.php` to the new language code.

Migrating from v1 to v2
-----------------------

[](#migrating-from-v1-to-v2)

The package no longer uses estimates when converting from Hijri to Gregorian by default.

- New keys have been added to `config/hijri.php`. You may need to update your configuration file.
- The function `getEstimateFromGregorian` has been **REMOVED** in favour of `createFromGregorian`.
    - To maintain the same behaviour as before:
        1. Change `config/hijri.php` > `conversion.converter` to `\Remls\HijriDate\Converters\MakkaEstimateG2HConverter::class`.
        2. Change all calls from `getEstimateFromGregorian` to `createFromGregorian`.
- The function `isEstimate` has been **REMOVED**. There is no more need to check if the date was made from an estimate, as you can now always just get the corresponding Gregorian date with a call to `getGregorianDate`, regardless of how it was created.
- The function `getEstimatedFrom` has been **REMOVED** in favour of `getGregorianDate`.
- The function `resetEstimation` has been **REMOVED** in favour of `resetGregorianDate`.
- The functions `addDays` and `subDays` will now use the underlying Gregorian date by default for calculations.
    - To maintain the same behaviour as before, pass `false` to `$useGregorian` parameter of these functions.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance57

Moderate activity, may be stable

Popularity9

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 55.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~114 days

Recently: every ~216 days

Total

12

Last Release

297d ago

Major Versions

v1.5.0 → v2.0.02023-04-26

PHP version history (2 changes)v1.2.0PHP ^8.0

v2.3.0PHP >=8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/12565380?v=4)[Mohammad](/maintainers/Mo7mud)[@Mo7mud](https://github.com/Mo7mud)

---

Top Contributors

[![Remls](https://avatars.githubusercontent.com/u/43497786?v=4)](https://github.com/Remls "Remls (32 commits)")[![Remls7](https://avatars.githubusercontent.com/u/86112728?v=4)](https://github.com/Remls7 "Remls7 (15 commits)")[![Mo7mud](https://avatars.githubusercontent.com/u/12565380?v=4)](https://github.com/Mo7mud "Mo7mud (8 commits)")[![HajMo](https://avatars.githubusercontent.com/u/50548630?v=4)](https://github.com/HajMo "HajMo (2 commits)")[![MdAnowarHosen](https://avatars.githubusercontent.com/u/85840896?v=4)](https://github.com/MdAnowarHosen "MdAnowarHosen (1 commits)")

### Embed Badge

![Health badge](/badges/mo7mud-hijri-date/health.svg)

```
[![Health](https://phpackages.com/badges/mo7mud-hijri-date/health.svg)](https://phpackages.com/packages/mo7mud-hijri-date)
```

###  Alternatives

[markwalet/nova-modal-response

A Laravel Nova asset for Modal responses on an action.

17878.9k](/packages/markwalet-nova-modal-response)[crumbls/layup

A visual page builder plugin for Filament 5 — Divi-style grid layouts with extensible widgets.

592.7k2](/packages/crumbls-layup)[team-nifty-gmbh/tall-datatables

Server-side rendered datatables for Laravel and Livewire

1320.9k4](/packages/team-nifty-gmbh-tall-datatables)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.4k](/packages/tomshaw-electricgrid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)