Filament Ummulqura Date Picker Laravel Package

Product Decisions This Supports

• MENA/Gulf market entry. A Hijri (Umm al-Qura) date picker is a table-stakes UI primitive for products sold into Saudi Arabia and the wider Gulf — government, HR/payroll, booking, fintech, and Hajj/Umrah-adjacent workflows. This package lets us ship that input as a Filament form field rather than scoping a custom build.
• Build vs. buy for calendar input. The functional scope is small and well-bounded (a form field that reads/writes Umm al-Qura dates). Buying is the default; a build sprint is only justified if we need conversion logic outside Filament or strict vendor independence.
• Roadmap sequencing. Because this is a form-field-level dependency, "Hijri date support" can be a low-effort line item inside an existing MENA epic instead of its own initiative — useful when arguing for a smaller slice of roadmap.
• Vendor/supply-chain risk acceptance. v1.2.2 changes nothing in the exposed API but adds a private Composer repository (https://repo.schemava.dev/r/public, Packistry) so the backend dependency asimnet/ummulqura-calendar resolves. That is a real product-adjacent decision: our builds now depend on a third-party private registry being reachable and our credentials being valid. This needs an explicit accept/decline, not a silent merge.
• Use cases to validate against: Hijri-only or dual-calendar input in admin panels, date-range filters on Hijri-native data, and any screen where Gregorian-only input causes data-entry errors for Gulf-based operators.

When to Consider This Package

Consider it when all of the following hold:

• You are building on Filament forms and want the field to fit the existing form API rather than hand-rolling one.
• You need Umm al-Qura specifically (Saudi official calendar), not generic Hijri approximation — the distinction matters for compliance-adjacent dates.
• You can provision Composer credentials for repo.schemava.dev in developer machines and CI, and your security policy permits pulling from a private third-party registry. As of v1.2.2 this is a hard prerequisite — a clean composer install/update will not resolve without it.
• You can tolerate a single-vendor dependency: the calendar conversion library is not on Packagist, so there is no public mirror, no public issue tracker for that layer, and no path to the conversion logic other than this maintainer.

Look elsewhere — or build — when:

• Private registries are restricted in your environment, or you run air-gapped/offline builds. The v1.2.2 change makes this a blocker rather than an inconvenience.
• You need conversion outside the UI layer (APIs, imports, reporting, ETL). In that case evaluate a plain PHP/intl-based approach — PHP's intl extension supports the islamic-umalqura calendar natively — and treat the picker as a thin front-end on top.
• You need long-term vendor independence or contractual SLAs on the dependency. Pin the version, or mirror the private package internally.
• You are not on Filament or your Filament version is outside the package's supported range — check the constraint before committing, since the value proposition collapses without the form-field integration.
• You only need one-way display (rendering a Hijri string), which does not justify a form-field dependency plus registry access.

Watch items for whoever owns adoption: confirm the asimnet/ummulqura-calendar license terms separately from this package's, record the private repo URL and credential-rotation owner in the runbook, and lock the version in composer.lock so an outage at the registry cannot silently break a deploy.

How to Pitch It (Stakeholders)

To executives: This is a small, cheap dependency that unblocks Hijri date entry in our admin surfaces — the kind of detail that decides whether a Gulf pilot feels native or half-localized. It removes a custom build from the MENA critical path and lets us sequence Hijri support inside an existing epic instead of funding a new one. The one thing that needs a decision above engineering: the latest release pulls its date-conversion library from a third-party private package registry, so we are adding a vendor our build pipeline depends on. That is an ops/security sign-off, not a feature risk — there are no API changes in this release.

To engineering: v1.2.2 is packaging-only — no code or API change, dependency constraint unchanged at ^1.1. The material change is that composer.json now declares a composer-type repository pointing at repo.schemava.dev (Packistry) to source asimnet/ummulqura-calendar; Packagist remains enabled for filament/forms, spatie/laravel-package-tools, and dev tooling. Upstream reports composer update resolving ummulqura-calendar 1.1.0 from that repo with 13/13 tests passing. Action items before we adopt: add registry auth to local setup docs and CI secrets, commit the lockfile, add a smoke check that fails loudly if the registry is unreachable, and note that this private dependency has no Packagist fallback — so mirror it internally if we intend to keep it long term.