Calendar Laravel Package

Product Decisions This Supports

• Market expansion into MENA, Gulf, and Muslim-majority SEA markets: enables Hijri (Islamic) date display alongside Gregorian in onboarding, profiles, receipts, and notifications — a table-stakes localization requirement for these segments.
• Seasonal feature roadmap: powers Ramadan/Eid modes, holiday-aware content calendars, campaign scheduling, and "days until Ramadan" countdowns without hand-maintained date tables that rot every year.
• Financial and contractual date handling: Hijri-parallel dates on invoices, statements, and HR/leave records where local regulation or customer expectation requires dual dating (e.g., Gulf payroll, Islamic finance disclosures).
• Scheduling and booking logic: converts user-entered Hijri dates into Gregorian for storage and recurrence rules, letting you keep a single canonical timestamp while accepting local-date input.
• Build vs. buy: the underlying arithmetic (tabular vs. Umm al-Qura variants) is deceptively fiddly and easy to get subtly wrong. This package lets you buy a narrow, single-purpose implementation instead of owning calendar math — the decision is adopt-with-a-wrapper, not invent.
• Content and editorial planning: a reliable conversion primitive lets content, marketing, and support tooling label events in both calendars consistently.

When to Consider This Package

Consider it when:

• You are on PHP/Laravel and need straightforward bidirectional Gregorian↔Hijri conversion plus display formatting, with a dependency that does one thing.
• You need a lightweight, framework-agnostic primitive rather than a full calendar/events engine — you want to compose it into your own domain model.
• You can isolate it behind an internal interface (e.g., a CalendarConverter contract), so the vendor choice is reversible and swappable later.
• You are willing to own the QA: snapshot tests against authoritative sources and spot-checks for the specific calendar variant your market uses.

Look elsewhere when:

• You need a specific religious authority's calendar. Hijri conversion is not globally uniform (Umm al-Qura, tabular, Diyanet, local moon-sighting committees can differ by a day). If your product's credibility depends on matching a national authority, this library alone will not guarantee it — you need a configurable or region-aware source.
• You need prayer times, Qibla, or moon-phase logic — those are separate concerns; do not assume this covers them.
• You need a broad, actively maintained calendar abstraction (recurrence, time zones, locale-aware formatting at scale). PHP's Intl/ICU already exposes Islamic calendars and may be one less dependency.
• Adoption and maintenance signals are thin. This repo shows no dependents and negligible community traction — a real bus-factor and abandonment risk for anything customer-facing. Treat it as evaluate and vendor, not standardize on.
• You need an SLA or vendor accountability. Open-source, single-maintainer libraries give you none; if the conversion is on a revenue or compliance path, plan to fork and maintain internally.

Adoption recommendation: timeboxed spike on a non-critical surface (e.g., date display on a localized profile page), behind an abstraction, with a test suite pinning known-good conversions before any broader rollout.

How to Pitch It (Stakeholders)

To executives: This is a small, free building block that unblocks date display and date entry for our Islamic-calendar markets — one of the cheapest ways to make the product feel native in MENA and SEA rather than translated. The cost is a few days of integration and validation, not a quarter of engineering. The risk is maintenance: it is a minor open-source project with almost no community footprint, so we should not make it a strategic dependency. Recommended path is a contained pilot with an internal abstraction layer, so we can swap it out or fork it without touching product code. Upside: faster entry into high-growth markets and fewer manual, error-prone date tables in our codebase.

To engineering: It is a focused conversion utility, not a framework. Wrap it behind our own interface, pin known-good conversion fixtures in tests, and document which Hijri variant we are targeting per market. Do not let it leak into domain models or templates directly. If ext-intl already covers our needs, that is a viable zero-dependency alternative — compare before committing.

Ask: approve a one-sprint evaluation and integration spike, with a go/no-go based on conversion accuracy against an authoritative reference for our top two markets.