Laravel Hijrian Laravel Package

Getting Started

• Install with composer require mohamedsabil83/laravel-hijrian. v4.3.0 adds Laravel 12 & 13 support; if you're still on Laravel 10/11, pin to an earlier 4.x that matches your framework version rather than assuming the newest tag is safe.
• The service provider is auto-discovered. Look first at:
  1. config/hijrian.php (publish with php artisan vendor:publish --tag=hijrian-config — check the README for the exact tag), which controls locale/month-name output.
  2. The Hijrian facade / service class, which is the main entry point.
  3. The translations directory, if you need Arabic, English, or custom month names.
• Minimal first use case: convert "today" for display in a view.

use Mohamedsabil83\Hijrian\Facades\Hijrian;

$hijri = Hijrian::toHijri(now());      // array/object with day, month, year, month name
$greg  = Hijrian::toGregorian('1446-09-01');

• Run a quick php artisan tinker round-trip (toHijri then toGregorian) before wiring it into anything. That single check tells you the return shape, the accepted input formats (string vs. Carbon vs. DateTimeInterface), and how month names are localized in your app's current locale.

Implementation Patterns

Store Gregorian, render Hijri. Keep timestamp/date columns as normal Gregorian values so querying, sorting, and indexing keep working. Convert only at the presentation or report boundary.

// app/Models/Post.php
protected function publishedHijri(): Attribute
{
    return Attribute::get(fn () => Hijrian::toHijri($this->published_at));
}

Blade rendering. Wrap conversion in a small helper or Blade directive/component so views never call the facade directly with raw strings:

{{ hijri($post->published_at) }}          {{-- e.g. "12 Rabi' al-Awwal 1446" --}}

Keep the formatting logic (month-name style, ordinal suffixes, "AH" suffix) in one presenter class, since the package returns structured data rather than a single pre-formatted string.

Localized month names. Month names follow the app locale through the package's translation files. Set app.locale per request (or via middleware) for multilingual sites, and add a custom translation file if you need a dialect or spelling variant. Clear config:cache after touching config/hijrian.php.

Date-picker / form input. For admin forms that accept a Hijri date, take three separate inputs (year, month, day) or a masked YYYY-MM-DD, validate them, then convert to Gregorian once before persisting. Round-tripping user input through the converter on every keystroke is a common source of off-by-one-day bugs.

Reporting and grouping. Hijri month boundaries don't align with Gregorian ones, so GROUP BY MONTH(created_at) won't work. Fetch the range in SQL using Gregorian boundaries you computed in PHP, then bucket rows in a collection:

$rows = Order::whereBetween('created_at', [$start, $end])->get()
    ->groupBy(fn ($o) => Hijrian::toHijri($o->created_at)['month']);

Testing. The package is deterministic for a given input, so freeze time with Carbon::setTestNow() and assert exact conversion output. Add one test that pins a known date pair (e.g. 1 Muharram 1446) so a dependency bump that silently changes the underlying calculation algorithm fails loudly.

Integration tip: expose the converter behind your own thin interface (HijriConverter) bound in a service provider. That keeps the third-party facade out of your domain code and makes it trivial to swap implementations or mock it in tests.

Gotchas and Tips

• Day boundary vs. sunset. Almost all PHP Hijri converters treat the Gregorian calendar date as the Hijri date; the Islamic day begins at Maghrib. Anything scheduled in the evening may display the "wrong" Hijri day to a user expecting sunset-based reckoning. Don't use this package for prayer times or fasting schedules — use a dedicated astronomical library.
• Arithmetic vs. sighting. Conversions follow a computed calendar (typically Umm al-Qura or tabular), which can differ by ±1 day from local moon-sighting authorities. If the business requires officially sighted dates, treat the package output as a display convenience and source the authoritative dates elsewhere.
• Timezone config matters. Conversion reads the date portion of the passed value. Pass a Carbon instance in the app's timezone (config('app.timezone')) rather than a UTC string, or dates near midnight shift a day.
• Return type, not a string. The converter returns structured components. Don't echo it directly and don't assume ->format() exists; build your display string from the day/month/year/month-name fields.
• Locale leakage. Month names come from translations; if the active locale has no Hijri translation, you'll silently get the fallback language. Assert month names in at least one non-default-locale test.
• Laravel 13 support is brand new. v4.3.0 is largely a compatibility + Dependabot release (testbench ^9.5.2, CI action bumps). The functional surface looks unchanged, so upgrading from 4.2.0 should be low risk — but run your own conversion assertions, since the underlying calculation dependency could have shifted without a changelog entry.
• Debugging conversions. dd(Hijrian::toHijri($date)) to inspect the full component array; if the result looks shifted, compare against a known reference date pair before suspecting your code.
• Extension points. Publish the config to override defaults, publish/override translations for custom month names, and wrap the facade in your own service if you need a different algorithm — extending the package's classes directly couples you to its internals across minor releases.