Laravel Hijrian Laravel Package

Technical Evaluation

Architecture fit. mohamedsabil83/laravel-hijrian is a small, single-purpose calendar-conversion utility: it converts Gregorian↔Hijri dates and exposes the result through Laravel idioms (Blade directive, validation rule, locale strings, facade). It is a presentation/formatting concern that sits on top of Laravel's date and i18n surface — it does not replace Carbon and does not become a system of record. Architectural footprint is therefore minimal: one service provider, one config file, one facade alias. That is a good fit for a TPM to greenlight because the blast radius of adoption is small and the exit cost is low.

Release verdict (v4.3.0). This is a maintenance release, not a feature release. The only user-facing change is widened framework support (Laravel 12 & 13). Everything else is Dependabot noise: orchestra/testbench (dev-only) plus GitHub Actions bumps (actions/checkout, ramsey/composer-install, dependabot/fetch-metadata, laravel-pint-action, git-auto-commit-action). No new features, no deprecations announced, no explicit breaking-change section. Treat it as "unblocks the Laravel 12 upgrade," not as "new capability to plan around."

Technical risk. Low-to-moderate.

• Correctness risk is the real one. Date conversion has nasty edge cases: Hijri month lengths, leap-year handling, month boundaries, and timezone/DST truncation. Different Hijri variants (Umm al-Qura vs. tabular Islamic) can differ by a day, which is business-visible in payroll, invoicing, contract dates, and Ramadan scheduling.
• "Laravel 13" support is unverified. Laravel 13 is not a generally available major as of normal release cadence; this may be forward-looking, a typo, or a CI matrix entry against a dev branch. Verify the actual illuminate/support constraint in composer.json before relying on it in a roadmap.
• Maintainer concentration. Single-maintainer package; release history is largely automated dependency commits. Cadence is driven by CI hygiene, not roadmap. This is the primary long-term risk.
• Test-suite signal. The testbench major bump to ^9.5.2 implies the suite tracks the current framework, but the release notes tell us nothing about coverage of the conversion logic itself.

Key questions.

1. Which Hijri algorithm is implemented (Umm al-Qura, tabular, or configurable), and does it match what our regulator/auditor expects?
2. What is the exact illuminate/support and PHP version constraint in composer.json — can it coexist with our current Laravel version during the transition window?
3. Is there an upgrade guide, deprecation policy, or semver commitment?
4. What is the test coverage on the conversion class, and are boundary cases (month ends, leap years, timezones) tested?
5. Are there other date/i18n packages in our stack (Carbon localization plugins, other Hijri libraries) whose facades or helpers could collide?
6. Is there a second maintainer or organizational backer?

Integration Approach

Stack fit. Targets Laravel 10/11/12 (13 claimed) applications with Arabic-locale or GCC/KSA market requirements: invoice and statement rendering, HR/payroll documents, contracts, and any regulatory output that must show Hijri alongside Gregorian. Fits wherever a Blade template or Eloquent accessor formats a date.

Migration path. Add as ^4.3.0. The 4.2.0→4.3.0 delta is additive (framework constraints widened, dev dependencies advanced), so there is no code-migration work expected on our side. If we are mid-flight on a Laravel 12 upgrade, this release is the dependency that unblocks it — land the package upgrade with the framework upgrade, not before it.

Compatibility checks.

• Confirm the illuminate/support constraint overlaps both our current and target Laravel versions so a single lockfile can serve the transition.
• Confirm the PHP floor against our runtime image.
• Confirm package auto-discovery registers the facade cleanly, and that config:cache doesn't break in any environment where discovery is disabled.
• Confirm translation files ship for the locales we actually render (ar, ar_SA), including any new keys.

Sequencing.

1. Spike branch: install on Laravel 12, run our suite.
2. Validate output against a known-good external reference for ~50 sampled dates deliberately chosen across month ends, leap years, and timezone/DST boundaries.
3. Add golden-file regression tests in our repo so upstream algorithm drift or a silent fork shows up as a failing test rather than a misprinted document.
4. Roll to staging, exercise the highest-risk surface first (PDF invoice/contract rendering).
5. Broaden to remaining surfaces only after the golden tests are green in CI.

Operational Impact

Maintenance. Near-zero runtime maintenance; pure computation, no I/O, no external services, no schema. The governance burden is on us: pin exact versions, keep Dependabot/Renovate alerting on, and review upstream repo health quarterly (commits, issue responsiveness, release cadence, maintainer activity).

Support. Single-maintainer concentration is the dominant operational risk. It is substantially mitigated by the fact that the package is thin — the conversion logic is a few hundred lines of forkable PHP. Document a fork plan and confirm the license permits it (MIT-style, verify). "Vendor exit cost" is genuinely low, which is what makes adoption defensible.

Scaling. A non-issue. Conversion is microseconds of CPU with no network or cache dependency. The only scaling consideration is volume: if we format thousands of dates per request (large report exports), cache the rendered strings or chunk the output rather than converting in a loop per row.

Failure modes.

• Silent off-by-one Hijri date from algorithm variant, timezone truncation, or month-boundary handling — wrong but plausible-looking output on a legal or financial document. Highest-severity failure mode; mitigated only by golden-file regression tests.
• Dependency constraint conflict blocking a future Laravel major, forcing a version bump on our schedule rather than the maintainer's.
• Facade/translation not registered after config:cache in a non-auto-discovery or multi-tenant setup.
• Abandonment — package eventually incompatible with a future Laravel major with no upstream fix, triggering the fork.

Ramp-up. Low for any Laravel developer: an afternoon to integrate and ship. The real ramp-up cost is domain knowledge, not code. The team must understand the difference between Umm al-Qura and tabular Islamic calendars and know which one our compliance/finance stakeholders expect. Budget a short pairing session with the owner of the invoice/payroll output before the first production release — that conversation prevents the one failure mode that actually matters here.