Laravel Hijrian Laravel Package

Product Decisions This Supports

• Regional/MENA feature work. Any user-facing surface that must render dates for Gulf and broader Muslim-majority markets — account statements, invoices, contracts, booking confirmations, payroll and HR records, school/academic calendars, Islamic finance and Zakat-related flows — depends on reliable Gregorian ↔ Hijri conversion. This package is the enabling dependency for that entire feature class in a Laravel codebase.
• Seasonal and religious-calendar features. Ramadan operating hours, Eid campaigns, Hajj travel windows, Hijri-year subscription renewals, and dated promotions all require Hijri arithmetic (month lengths, leap years, year boundaries). Owning this package lets those features be scoped as product work rather than research work.
• Dual-calendar display as a product decision. Whether to show Hijri-only, Gregorian-only, or both is a market-positioning choice. A small, well-scoped converter makes "show both" cheap, so the decision can be driven by user research rather than engineering cost.
• Roadmap sequencing for the framework upgrade. v4.3.0's headline item — Laravel 12 and 13 support — is the decision-relevant change. It means the dual-calendar capability is no longer a blocker on our Laravel upgrade path. If we had MENA features shipped on an older Laravel, this release removes the "upgrade the framework or fork the package" fork in the road.
• Build vs. buy. Calendar conversion looks like arithmetic and behaves like a specification problem: which Hijri variant (Umm al-Qura vs. tabular/arithmetic), how leap years are counted, how month starts are determined, and how locales format output. Getting this subtly wrong produces off-by-one-day defects that are visible to every user and expensive to diagnose. Consuming a maintained package is the correct default; building is only justified if we need an authority-specific or astronomically computed calendar.
• Vendor and dependency risk review. This release is overwhelmingly Dependabot churn on CI actions and test tooling. That is a positive signal about maintenance hygiene and a reminder that this is a single-maintainer, low-bus-factor dependency — a fact that should shape how we wrap it, not whether we use it.

When to Consider This Package

Adopt when:

• The application is Laravel (or Laravel-adjacent PHP) and needs Hijri dates anywhere in the product — even in one place, since ad-hoc conversion code is where the off-by-one-day bugs live.
• You need standard Hijri conversion and formatting with locale-aware output, and your requirements align with the calendar convention the package implements.
• You want a dependency-light solution: this is a small package with no heavy transitive footprint, which matters for teams with strict dependency policies.
• Framework compatibility lines up: v4.3.0 explicitly targets Laravel 12 and 13, and its test matrix has been moved forward accordingly. If you are on an older Laravel, check the prior 4.2.x line rather than assuming backwards compatibility.
• You are willing to wrap it behind your own thin service or adapter (see below), which is the right pattern for any single-maintainer dependency.

Look elsewhere when:

• You need a specific, authoritative calendar determination — e.g., a particular national moon-sighting authority, or an astronomically computed rather than tabular calendar. Conversion libraries encode one convention; if your regulator or customer requires another, a general-purpose package will quietly disagree with them.
• You need broad calendar-system coverage beyond Hijri (Hebrew, Persian, Coptic, fiscal calendars). Reach for a dedicated multi-calendar library rather than stacking single-purpose packages.
• You need calendar-aware recurrence and scheduling (e.g., "every Hijri month," "the last Friday of Ramadan") rather than date conversion and formatting. That is a scheduling-domain problem and deserves a scheduler, not a formatter.
• You require commercial support, an SLA, or a security-review artifact from the maintainer. This is a community package; that is a procurement decision, not a code-quality one.
• Your stack is not Laravel, or you are consolidating date logic into a service in another language. The conversion logic is small enough to reimplement behind a documented interface in that case — but document the convention you chose.

Adoption guidance:

• Pin the version. This is a minor release with no API changes, so upgrading from 4.2.x is low risk, but pinning protects you from a future major bump moving calendar behavior.
• Wrap it: expose toHijri(), toGregorian(), and formatting through an internal adapter with your own tests asserting known reference dates. That gives you a swap path if the package stalls or a convention mismatch appears, and it makes the calendar convention an explicit, reviewable product decision rather than an implicit library default.

How to Pitch It (Stakeholders)

For executives. This is a small, low-cost open-source dependency that unlocks date handling for Gulf and broader MENA markets — the difference between a product that shows a user in Riyadh a date they recognize and one that doesn't. The v4.3.0 release is significant for one reason: it adds support for Laravel 12 and 13, which means this capability will not hold up our platform upgrade and we will not need to maintain a private fork. The release itself contains no new user-facing features and no breaking changes; the remainder is routine automated dependency upkeep. Risk profile is low but not zero — it is maintained by a single developer, so we will pin the version and isolate it behind a thin internal interface, which costs little and lets us replace it cleanly if needed.

For engineering. v4.3.0 is a compatibility and maintenance release. The substantive change is expanded framework support (Laravel 12/13) alongside a test-matrix bump (orchestra/testbench now on the 9.x line, with an intermediate step to ^8.22.1). Everything else is Dependabot churn on GitHub Actions and tooling: laravel-pint-action, dependabot/fetch-metadata, stefanzweifel/git-auto-commit-action, actions/checkout, and ramsey/composer-install. No source-level API changes, no deprecations, no migration steps are indicated by the notes — treat it as a safe minor bump, but verify against our CI since the framework-support widening is the only place behavior could differ. Recommended integration pattern: do not call the package directly from controllers, models, or Blade templates. Put it behind an application-level HijriDate service (or a Carbon-like decorator) with a small contract, and add regression tests pinned to known Gregorian/Hijri reference pairs — including at least one leap-year and one year-boundary case. That isolates the single-maintainer risk, makes the calendar convention we use an explicit decision on record, and means a future major version or an abandoned package is a one-file change rather than a codebase-wide refactor.