fisharebest/ext-calendar
A pure-PHP implementation of PHP's calendar extension, providing cal_* functions and conversions between Julian day counts and Gregorian, Julian, Jewish, and French Republican calendars. Useful as a polyfill when ext-calendar is unavailable.
Architecture fit. The package is a pure-PHP, Composer-installable library with namespaced calendar classes and no framework coupling, so it slots into a Laravel application as a leaf dependency rather than an architectural component. Its primary architectural value is replacing the removed ext/calendar extension on PHP 8+, which otherwise blocks modernization or forces a PECL build into deployment images. It is a conversion/math library, not a date-abstraction layer: it does not replace Carbon, timezone handling, or locale-aware formatting, so the architecture should treat it as a narrow adapter behind an application-owned interface.
Integration feasibility. Integration is technically straightforward: add the Composer requirement, wrap the relevant calendar classes in a service, and expose conversion methods to domain code. There is no service provider, configuration, migration, or queue integration required. A one-to-two-day spike should be sufficient to validate PHP version constraints, autoloading, and the exact API surface. The real gate is not technical effort but licensing and correctness validation.
Technical risk. Three risks dominate. First, GPL-3.0 is copyleft: distributing a proprietary Laravel application or container image that includes this dependency can trigger source-disclosure obligations for the combined work; SaaS use is generally lower risk but still requires legal review. Second, the project has low visible community adoption (31 stars, single-maintainer risk), so bus factor and long-term maintenance are concerns despite the code being small and forkable. Third, calendar correctness is deceptively hard: Hijri variants (Umm al-Qura vs. tabular), Jalali arithmetic vs. astronomical rules, Julian/Gregorian historical cutover, leap-year boundaries, and negative/BC years all need fixture-based verification. Performance is a minor risk: pure PHP is slower than the C extension, but conversions are cheap and cacheable for typical product workloads.
Key questions.
intl/ICU already satisfy the requirement for Islamic, Persian, Hebrew, and Gregorian calendars, leaving only the French Republican calendar as unique value?Stack fit. Fits Laravel 8+ on PHP 8.0+ via Composer 2, with no Illuminate dependencies. Bind an application-owned CalendarConverterInterface in a service provider and keep the vendor namespace out of controllers, models, and Blade templates. Use Carbon/DateTimeImmutable for Gregorian and timezone concerns, and delegate only non-Gregorian conversion and month metadata to this package.
Migration path. Inventory all uses of cal_* functions and any ad-hoc Hijri/Jalali logic. Because ext/calendar is absent on PHP 8, migration is likely already forced. Introduce the adapter first, then replace call sites incrementally behind a feature flag. Store canonical dates as Gregorian/UTC plus a calendar identifier and the original user-entered string; do not store only converted values. Run dual-comparison tests against known-good fixtures (ICU output, published conversion tables, or the PECL extension in an isolated sandbox) before cutover.
Compatibility. GPL-3.0 is the decisive compatibility constraint, not PHP or Laravel versioning. If the product is proprietary and distributed, either obtain legal approval, isolate the dependency behind a process/service boundary with careful analysis, or select a permissively licensed alternative such as ICU via intl. If the product is internal-only or GPL-compatible, proceed. Also confirm the package's declared PHP range against our supported matrix and pin the exact version in composer.json.
Sequencing.
Maintenance. Expect to own this dependency. Pin the version, commit the lockfile, and monitor upstream activity; given the small codebase, a private fork under GPL terms is a realistic contingency. Add regression fixtures to CI so PHP upgrades or dependency bumps cannot silently change conversion results. Budget periodic review of calendar-rule assumptions, especially for Hijri and Jalali.
Support. There is no vendor SLA; support is community/best-effort. Establish an internal owner for calendar semantics and a documented policy for invalid dates and variant selection. Escalation should route to the owning engineering team, not to the upstream maintainer.
Scaling. Conversions are CPU-bound and stateless, so the package scales horizontally with the application. Cache formatted calendar strings for repeated display, avoid converting large date ranges per request, and keep bulk historical processing in jobs. No external service, network call, or persistent state is introduced.
Failure modes. Watch for invalid day-of-month acceptance, leap-year and epoch-boundary errors, timezone/DST drift during conversion, silent fallback to Gregorian, inconsistent month-name localization, and unhandled behavior for BC or far-future years. Wrap conversions with validation and explicit exceptions, and log rejected inputs rather than coercing them. A dependency abandonment scenario is mitigated by forking, but only if tests exist.
Ramp-up. Developer ramp-up is low—the API is small and Composer-native—but domain ramp-up is moderate because calendar variant and edge-case decisions require specialist review. Allocate QA time for fixture creation and user-acceptance testing with native speakers or domain experts. The TPM should maintain a short decision record covering license posture, canonical calendar variants, storage format, and the accepted validation behavior.
How can I help you explore Laravel packages today?