Filament Ummulqura Date Picker Laravel Package

Getting Started

• Install: composer require asimnet/filament-ummulqura-date-picker:^1.2. Since v1.2.2 the package's own composer.json declares https://repo.schemava.dev/r/public (Packistry) as a composer-type repository so the backend dependency asimnet/ummulqura-calendar:^1.1 resolves. Packagist stays enabled for filament/forms, spatie/laravel-package-tools, and dev tooling — don't disable it.
• Authenticate the private repo first. repo.schemava.dev is a private Composer repo; a bare composer require on a clean machine will fail with a 404/auth error before you ever see the package. Ask the maintainer for a token and set it once:

  composer config --global http-basic.repo.schemava.dev <token> <token>
  # or, for CI:
  export COMPOSER_AUTH='{"http-basic":{"repo.schemava.dev":{"username":"token","password":"<token>"}}}'
  

• Sanity check the resolution before debugging your own code: composer show asimnet/ummulqura-calendar should report 1.1.0 and composer update -vvv should show it being served by repo.schemava.dev, not Packagist.
• Where to look first: the README for the field class + registration snippet, then src/ for the Filament field class and the tests/ directory (13 tests as of this release) — the tests are the most reliable usage documentation for the conversion and formatting API. Check composer.json for the supported Filament major version before assuming a v3 example works on v4.
• First use case: drop the Hijri picker into a resource form, keep the underlying column Gregorian ($table->date('hijri_date') or similar), and let the package/backing calendar handle conversion. Add the field, submit, and verify the stored value round-trips through the display format before wiring it into filters or tables.

Implementation Patterns

• Store Gregorian, present Hijri. Keep the database column a plain date/datetime and convert at the edges (form field display, table column, exports). Storing Hijri strings makes ordering, whereBetween, and timezone handling painful and locks you to one conversion library.
• Conversion belongs to asimnet/ummulqura-calendar, not the frontend. When you need a value outside the form field — table columns, PDF exports, API resources, scheduled reports — call the backend calendar's conversion helpers directly rather than re-implementing Umm al-Qura arithmetic or trusting JS.
• Formatting in tables/infolists:

  TextColumn::make('starts_at')
      ->formatStateUsing(fn ($state) => $calendar->toHijri($state)->format('Y-m-d'))
  

  Keep the raw Gregorian value as the sortable/searchable state.
• Validation across the Hijri/Gregorian boundary. Rules like after_or_equal run against whatever the field dehydrates. Either dehydrate to Gregorian via ->dehydrateStateUsing(...) and validate the Gregorian value, or express the comparison in Hijri. Mixing the two silently passes/fails near month boundaries.
• Reuse the field everywhere Filament accepts form components — resource forms, relation managers, action modals, and custom Livewire forms — so formatting stays consistent instead of one screen using Hijri and another Gregorian.
• Test the conversion seams, not the widget chrome. Unit-test around 29/30-day months, year boundaries, and leap years; use Filament's Livewire form-testing helpers for the field itself. Mirror the conventions in the package's 13 tests so upgrades stay cheap.
• Pin ^1.2 and commit composer.lock. Don't float on * — the ^1.1 backend constraint is resolved transitively and a lockfile is your only guarantee that every environment gets the same conversion behaviour.

Gotchas and Tips

• The private repo is the new failure mode. v1.2.2 changed nothing in code or API (still asimnet/ummulqura-calendar:^1.1), so it's a safe patch — but any composer install/update on a machine without credentials now fails. Expect a wave of "it worked yesterday" tickets from CI runners, new hires, and Docker builds that previously had a warm vendor/ cache. Bake COMPOSER_AUTH into CI secrets and document it in onboarding.
• Don't set "packagist.org": false in an effort to "use the private repo only" — you'll lose filament/forms, spatie/laravel-package-tools, and all dev tooling.
• Repository ordering and mirrors matter. If your root composer.json declares a mirror, Satis, or a canonical repo that also carries asimnet/ummulqura-calendar, resolution can come from the wrong source with a different build. Verify with composer why asimnet/ummulqura-calendar and composer update -vvv after any infra change.
• Credential scope: prefer an org/repo-scoped token over a personal one, and use http-basic (not bearer) unless the maintainer says otherwise. Auth failures surface as generic 404s — check composer diagnose before assuming the package is gone.
• Conversion disagreements are a real risk. Umm al-Qura is a calculated calendar; results at month starts can differ from astronomical or other Hijri libraries. Never mix two Hijri implementations in one app, and don't hand-write offsets to "fix" a one-day discrepancy — that's a library/convention decision, not a bug to patch locally.
• Timezones: convert from a Carbon in the app timezone (or explicitly UTC) and be deliberate about it. A Hijri date derived from a UTC timestamp can be off by a day for users east/west of you — a classic off-by-one that only shows up in production near midnight.
• Debugging checklist: composer diagnose → composer show asimnet/ummulqura-calendar (expect 1.1.0) → composer update -vvv (confirm which repo served it) → re-run the package's tests → then look at your own formatting code. In that order.
• Extension points: publishable config/views (if offered) and the Filament field's fluent API are the supported customisation surface. If you need behaviour the field doesn't expose, wrap it in a custom form component rather than editing vendor/ — the private-repo workflow makes forks and patch files expensive to maintain across updates.