Arabicdatetime Laravel Package

Technical Evaluation

Architecture fit. This is a presentation-layer utility, not infrastructure. It sits at the very edge of the stack — formatting a Carbon instance into an Arabic-labelled, optionally Hijri, string. That is architecturally favourable for us: the blast radius of a defect or an abandoned dependency is confined to rendered output, not to persistence, auth, or business transactions. It is a Laravel-native package (service provider + facade, likely auto-discovered, likely with a publishable config), so it slots into the framework's conventions without ceremony. The caveat is that "fits the framework" is not the same as "fits our application" — if we ever need this in a non-Laravel worker, a CLI tool, or a queue consumer outside the framework container, a facade-bound formatter becomes friction.

Integration feasibility. Mechanically trivial: composer require, publish config, call the facade or Blade directive. The real feasibility question is dependency-graph compatibility, not API design. Last release 2021-06-22 means the illuminate/support and nesbot/carbon constraints were authored against the Laravel 8 / Carbon 2 era. Modern Laravel (10/11) and PHP 8.1+ may resolve only via --ignore-platform-reqs or a fork. Before committing, run composer why-not maherelgamil/arabicdatetime <version> against our actual lockfile to see the concrete conflict, not the theoretical one.

Technical risk. Ranked:

1. Calendar correctness (highest). Hijri conversion is not one algorithm — Umm al-Qura (used in Saudi Arabia, astronomical-table-based), tabular Islamic (arithmetic, drifts by ±1–2 days), and sighting-based observance all disagree. If any downstream logic depends on the Hijri date rather than merely displaying it, a one-day drift is a business defect, not a cosmetic one.
2. Abandonment. 41 stars, single maintainer, no release in ~3.5 years, low composite score (0.475) indicating thin adoption. Assume no upstream fixes; budget for fork-and-own.
3. Locale state leakage. Date libraries that set global Carbon locale or PHP setlocale can contaminate subsequent formatting in the same process — a real problem under Octane/Swoole and long-lived queue workers.
4. Fragility of Arabic rendering. If the implementation uses string substitution of English month/day names or a naive digit map, edge cases in pluralisation (Arabic dual/plural forms), Eastern Arabic numerals, and mixed RTL/LTR strings will surface as visual bugs that are hard to test automatically.
5. Supply chain / security. Low. No network I/O, no deserialisation, no raw SQL. Residual risk is maintainer-account compromise on an unmaintained package, mitigated by version pinning and a private mirror.

Key questions for the maintainer/team.

• Which Hijri algorithm and reference tables, and is there a documented golden-date test suite against Umm al-Qura?
• Supported Laravel/PHP/Carbon matrix — is Laravel 10/11 + PHP 8.2/8.3 supported, or must we fork?
• Does it mutate global Carbon locale or PHP setlocale, and does it restore prior state?
• Is the API a formatter (returns string) or does it also parse/convert? Can we get a date object rather than a pre-rendered string?
• Timezone semantics: does conversion happen before or after timezone adjustment? A Hijri date can roll over at a different instant than the Gregorian one.
• Configuration surface: digit system (٠١٢ vs 012), month naming style, and whether locale is per-call or global.
• Test coverage and CI status; are there open issues describing off-by-one date reports?
• Is the package's own dependency on an Arabic string library transitive — and is that dependency maintained?

Integration Approach

Stack fit. Treat this as a replaceable rendering adapter, not a foundation. Wrap it behind our own interface (e.g. ArabicDateFormatter::format(CarbonImmutable $d, string $style)) and let the package be one implementation. This costs a day and buys us the ability to swap to a maintained library, a first-party implementation, or an ICU/intl-based formatter without touching call sites. Laravel's container makes this cheap; not doing it is the expensive choice.

Migration path.

1. Spike on a branch. Add the package, resolve constraints honestly. If Composer refuses, evaluate a fork under our namespace with widened constraints — widening illuminate/support is usually a one-line change, but only if the API surface used is actually stable across Laravel versions.
2. Characterise behaviour before trusting it. Build a golden-date fixture: ~30 known Gregorian↔Hijri pairs spanning month boundaries, leap years, Ramadan/Eid boundaries, year-end, and a DST transition in Asia/Riyadh. Assert the package's output. This is the single highest-value hour of work in the whole integration.
3. Isolate. Implement our adapter; prohibit direct facade/Blade usage via code review or a static-analysis rule. Ban it outside the presentation layer entirely.
4. Prove state hygiene. Under our actual runtime (Octane or not), test that formatting an Arabic date does not change the locale of a subsequently formatted English date in the same process.
5. Ship narrow. Enable on a low-stakes surface first — admin UI or internal email templates — before any customer-facing or contractual document.

Compatibility. Confirm three axes explicitly: Laravel version, PHP version, Carbon major version. Carbon 2 → 3 is the likeliest breakage point, and Laravel 11 straddles it. Also verify the package's Blade directive (if present) hasn't been affected by Blade compilation changes, and that the config file publish/merge still works with our config caching (php artisan config:cache) — stale config merges are a classic Laravel package upgrade trap.

Sequencing. Pin an exact version (not a caret range) at install. Fork only if the compatibility spike fails — don't fork preemptively. Gate the feature behind a config flag so rollout is reversible without a deploy of new logic. Sequence: spike → golden-date fixtures → adapter → state-hygiene test → internal surface → external surface.

Operational Impact

Maintenance. Assume we own this. No releases since mid-2021 and a single maintainer means upstream is effectively dormant; the realistic steady state is a vendored fork under our namespace with a named internal owner. Ongoing cost is low but non-zero: periodic review when Laravel majors land, since that's when the constraint pins bite. Put it on the dependency-review list alongside other low-activity packages so it isn't rediscovered during an upgrade crunch.

Support. No commercial support, no SLA, small community — issues may go unanswered indefinitely. Internal support burden falls on whoever owns the adapter. Because the adapter boundary exists, "support" degrades gracefully: a broken package is a swap, not an incident.

Scaling. Runtime cost is negligible — string formatting on already-materialised dates. Do not call it inside tight loops over large collections if it re-parses per row; format once at the serialisation boundary. The genuine scaling concern is not CPU but state: long-lived workers and Octane processes reuse a global locale, so any package-level global mutation compounds over process lifetime. Test under concurrency, not just sequentially.

Failure modes to design for.

• Silent off-by-one on Hijri dates at month boundaries — worst failure because it looks correct. Catch with golden fixtures and, if the date is business-relevant, a second independent check.
• Locale contamination — English UI strings emerging in Arabic after an Arabic render, or vice versa, in Octane/queue contexts. Mitigate by saving and restoring locale around every call in the adapter.
• Exception on unparseable or out-of-range input (very old/future dates, non-Gregorian inputs). The adapter should catch, log, and fall back to the Gregorian string rather than 500 the page.
• Partial translation — some months or days returning English because a mapping table is incomplete. Snapshot-test the full 12-month and 7-day surface.
• RTL rendering artefacts when Arabic numerals, Latin digits, or punctuation mix in one string. This is a CSS/bidi concern the package cannot solve; assign it to frontend.
• Config-cache staleness after deploy — new config keys silently ignored.

Ramp-up. Low for a competent Laravel developer — an afternoon to integrate, a day to do it properly with fixtures and the adapter. The non-obvious cost is domain literacy: the team needs enough grounding in Hijri calendar variants to know when a one-day discrepancy is a bug versus an expected sectarian/regional difference. If the Hijri date ever feeds a contract, invoice, payroll, or religious-timing feature, that domain review is mandatory and should be treated as a product decision, not an engineering one.