Ext Calendar Laravel Package

Product Decisions This Supports

• Multi-calendar date display and conversion as a product feature. Decides whether we can ship user-facing dates in Gregorian, Julian, Hijri (Arabic), Persian (Jalali), Hebrew, and French Republican calendars — a hard requirement for genealogy, heritage/cultural archives, religious observance products, historical research tools, and any product with MENA or Iranian user bases.
• Build vs. buy for calendar math. Calendar conversion is not a formatting problem: the Hebrew calendar needs molad/postponement rules, the Persian calendar needs astronomical/algorithmic epoch handling, and Julian↔Gregorian cutover dates are a classic source of off-by-ten-days bugs. This package lets us treat that as a dependency rather than a multi-sprint research project with a permanent correctness liability.
• Runtime dependency and hosting decisions. Because it is a pure-PHP alternative to ext/calendar, it removes a PHP extension from our deployment image, container, and shared-hosting requirements. That is a concrete infrastructure and support-ticket decision, not just a library choice.
• Coverage gaps in the platform. PHP's ext/calendar does not cover Hijri or Persian/Jalali at all, and its Jewish calendar implementation has documented accuracy issues. Adopting this package is effectively the decision to close those gaps rather than declare those markets out of scope.
• Feature roadmap inputs. Enables: native-calendar date entry alongside Gregorian storage; dual-calendar display ("12 Ramadan 1446 / 12 March 2025"); historical document transcription with original calendar preserved; anniversary and memorial recurrence rules; timeline views spanning calendar reform (e.g., 1582); locale-aware date formatting.
• Data model decisions. Reinforces the correct architectural position — store one canonical timestamp (UTC/Gregorian) plus an optional source-calendar annotation, and convert only at the presentation layer. This package is a conversion/formatting utility, not a storage format.
• Licensing and distribution strategy. GPL-3.0 is a copyleft license. This is the single largest product decision attached to this package and gates everything else (see below).

When to Consider This Package

Consider it when:

• The product must display or accept dates in Hijri, Persian/Jalali, Hebrew, Julian, or French Republican calendars — not merely localize Gregorian month names.
• We need historical date handling: Julian dates, pre-1582 records, genealogy-style "date as written in the source" fields.
• We control the deployment target and want to avoid requiring a PHP extension (ext/calendar) — helpful for shared hosting, serverless, or locked-down enterprise environments.
• License fit is acceptable. This is genuinely usable if the surrounding product is itself GPL-compatible open source (the package's provenance is the webtrees genealogy platform, which is GPL). For internal-only tooling that is never distributed, GPL obligations are typically not triggered — but that must be confirmed with legal, not assumed.
• Engineering wants a small, dependency-free, pure-PHP library with no framework coupling that drops cleanly into a Laravel service via Composer.

Look elsewhere or build in-house when:

• We ship proprietary or SaaS software and cannot accept copyleft. GPL-3.0 in a distributed proprietary product is a non-starter for most legal teams. Alternatives: MIT/BSD-licensed calendar libraries, a commercial license negotiated with the author, or an in-house implementation of only the two or three calendars we actually need.
• Maintenance risk is unacceptable. ~31 stars, a single maintainer, and an unresolved/unknown canonical repository link mean no vendor SLA, no security-response process, and real bus-factor exposure. Mitigate by vendoring/forking with an internal owner, or avoid for anything on a regulated or long-lifecycle path.
• Only Gregorian is needed. Then this is unnecessary surface area — use Carbon/PHP's DateTime and be done.
• We need time zones, durations, or business-day logic, which are out of scope; this is calendar conversion, not a date-time framework. Pair it with the existing stack rather than replacing it.
• We need sub-day precision, lunar-sighting-dependent Hijri (vs. tabular), or locale-specific religious authority calendars. Tabular/algorithmic output will not match announced observance dates; that is a policy/product requirement, not a library bug.

Adoption gate (minimum): license cleared by legal, an internal owner named, the version pinned and vendored or locked, a conformance test suite comparing conversions against authoritative reference tables, and a documented fallback if the upstream goes dark.

How to Pitch It (Stakeholders)

To executives: This is a small, focused library that unlocks a market segment we currently cannot serve — users who think in Hijri, Persian, Hebrew, or historical Julian dates. It replaces a fragile PHP extension with plain PHP, so it also simplifies deployment. The engineering cost is near zero (one Composer dependency); the real decision is legal: the license is GPL-3.0, so it fits our open-source and internal-tooling work cleanly but needs a legal sign-off — or a paid alternative — before it goes into a proprietary shipped product. Upside is a differentiating capability at trivial build cost; the risk is a low-activity single-maintainer project, which we contain by pinning the version and owning our own test coverage.

To engineering: Pure PHP, no framework coupling, installs via Composer and drops into a Laravel service behind a thin adapter. It covers Arabic (Hijri), French, Gregorian, Jewish, Julian, and Persian (Jalali) — the two we care about most, Hijri and Jalali, are exactly what ext/calendar cannot do, and it avoids the extension's known Jewish-calendar inaccuracies. Design constraint from us: store UTC/Gregorian only; use the library strictly at the input/display boundary, and keep the source calendar and original date string as separate fields. We will wrap it behind our own CalendarConverter interface so the dependency is swappable, pin the version, and ship a golden-file test suite against published conversion tables before any user-facing release. Do not let calendar logic leak into models, migrations, or query filters.