Filament Nepali Datetime Laravel Package

Getting Started

Install the package through Composer:

composer require rohanadhikari/filament-nepali-datetime

There is no service provider registration to worry about on modern Filament — it ships as a Filament plugin-style package. If a config file is publishable, run php artisan vendor:publish --tag="filament-nepali-datetime-config" and check config/filament-nepali-datetime.php for date-format / locale defaults.

v2.1.0 adds time selection. The headline of this release is a timepicker (PR #13), which means the package is no longer date-only — you can now capture a BS date and a time-of-day in one field. This is a brand-new surface, so read the source for the exact opt-in API (whether time is enabled by a fluent flag on the picker, a separate NepaliDateTimePicker vs NepaliDatePicker class, or a config default) before wiring it in. If you only need dates, stick with the date-only component and avoid the new code path entirely.

Start by looking at the package's src/ directory in vendor/rohanadhikari/filament-nepali-datetime — it is small enough to read end-to-end in a few minutes, and you will need to. The key classes are the wrapped components: the date/date-time picker form field, a NepaliDateColumn (table column), and a NepaliDateEntry (infolist entry). These mirror the Filament DatePicker / DateTimePicker / TextColumn / TextEntry APIs, so anything you already know about those components transfers.

Your first use case is almost always a single date field on a create form:

NepaliDateTimePicker::make('published_at')
    ->label('Published (BS)');

If you need time-of-day, enable it via whatever the v2.1.0 timepicker API exposes and confirm in the source whether it emits seconds or minute precision, and whether it is 12/24-hour.

Before wiring this into a model, decide where the Bikram Sambat (BS) value lives. The safe assumption with this package is that it converts at the UI boundary and stores a Gregorian (AD) timestamp in the database column — verify this by reading the component's dehydrateStateUsing / mutateDehydratedState logic in the source. With v2.1.0 the question gains a second half: how is the time portion stored — combined into the same AD datetime, or as a separate string? If it does not convert the way you expect, you will need to handle conversion yourself, and that decision shapes everything below.

Implementation Patterns

Store AD, display BS. The cleanest integration keeps your database in Gregorian dates (so Carbon, whereBetween, sorting, and reporting all behave normally) and only converts in the Filament layer. Use the package's picker for input and its column/entry for output, and keep model casts as standard datetime/date. If you ever need raw conversion outside Filament, pair this package with a dedicated BS↔AD converter (e.g. nepali-date-converter) rather than reimplementing the calendar table.

Date-only vs date-time fields. Now that time is available, be deliberate per column. A birth_date or contract date should stay on the date-only picker so you don't accidentally store a meaningless 00:00:00 or, worse, a now()-derived time. Use the time-enabled picker for appointment slots, shift start/end, and event timestamps — anything where the time is part of the business fact.

Time is not a calendar concern. The BS↔AD conversion applies only to the date portion. The clock time the user selects is the same wall-clock time in AD. Keep that mental model: date gets converted, time passes through. If the package hands you a Carbon instance, check whether it applied the time after conversion (correct) or reconstructed the object and dropped it (a bug worth a test).

Table columns. Swap the display component only:

NepaliDateColumn::make('published_at')
    ->label('Published (BS)')
    ->sortable(); // sorts on the underlying AD column — verify

Because sorting/filtering still hits the AD database value, BS display and chronological ordering stay consistent. This is the main reason to prefer display-layer conversion over storing BS strings. After upgrading, check whether the column gained a ->dateTime() / time-format toggle so table output matches the new form input.

Infolists and read-only views. NepaliDateEntry is a drop-in for TextEntry in view schemas. Use it anywhere an admin reviews a record — order details, appointment timestamps, contract dates.

Mixed forms (AD + BS). A common workflow in Nepali-facing apps is capturing a date in BS but also recording the AD equivalent for exports. Keep the picker bound to the AD column and, if the package exposes a conversion helper, compute the BS string in a ->afterStateUpdated() callback for a secondary read-only field. Avoid two editable fields for the same value — they will drift.

Filters and date ranges. If the package ships a filter component, prefer it over a raw Filter::make()->form([DatePicker::make(...)]). If it does not, leave filtering on Gregorian DatePicker and accept that admins filter in AD but read in BS — document this for users, or wrap the query with ->query(fn ($query, $data) => ...) converting the BS range to AD before it hits the database. Note the timepicker release does not add a filter component, so time-range filtering is still yours to build.

Testing. Write feature tests against the AD value. A Livewire ->fillForm(['published_at' => '2026-07-15 14:30']) will bypass the picker's display logic and set the underlying state directly, so tests stay simple. Add one browser/Dusk-style test if you need to prove the BS rendering itself, and one more specifically for the timepicker — it is the newest code in the package and the least battle-tested. Assert both the converted date and the preserved time.

Consistency across the panel. Because this is a thin wrapper, adopt a convention: every user-facing date in a Filament panel uses the Nepali components; every database read/write uses Carbon. Decide once whether times render 12- or 24-hour and stick to it. Enforce it in code review, since there is no global switch.

Gotchas and Tips

This is a 5-star, zero-dependent package. Treat it as a starting point you own, not infrastructure you can rely on upstream. Read the source, pin the version in composer.json (e.g. "^2.1" only if you want the new timepicker), and be prepared to fork. Watch its Filament major-version constraint — Filament 3 vs 4 moved a lot of namespaces, and a wrapper that lags on the core version will break on upgrade. Check composer.json for the filament/filament constraint before adopting. A feature release that adds UI surface (like v2.1.0's timepicker) is exactly the kind of change that later needs core-version fixes, so pin rather than float.

Verify the storage contract first. The single most important thing to confirm is whether the component converts BS→AD on save or stores what the user typed. If it stores the BS value verbatim into a datetime column, your ->sortable(), ->whereBetween(), and Carbon casts will be subtly wrong. Test with a known date (e.g. 2000-01-01 BS = 1943-04-14 AD) before trusting the column. With v2.1.0, repeat the test with a time: confirm the stored value is AD-date + your-time, not AD-date + 00:00:00.

Timezones are a second conversion layer. BS↔AD is a calendar conversion; timezone handling is separate — and time selection makes it far more visible. If the component converts to a Carbon instance, ensure it lands in config('app.timezone') and not the user's browser locale. Nepal is UTC+05:45, a non-hour offset, so any truncation to the hour silently loses 45 minutes. Double-check dates that cross midnight and any server running in UTC.

Precision and column type. A date-only picker on a datetime column, or a time-enabled picker on a date column, will quietly lose data. Match the migration to the component. If the timepicker emits seconds, confirm that's what you want stored; if it emits minutes, don't write now() in a callback and expect clean values.

Leap months and year boundaries. The Bikram Sambat calendar has irregular month lengths and an extra month in some years. Do not hand-roll ranges like "this BS month" with addMonth(); use whatever month-length data the package or your converter exposes. Test specifically around BS new year (mid-April) and known leap-month years.

Nullable and default states. ->nullable() and ->default(now()) pass through to the wrapped component, but confirm default rendering — a now() default will be formatted as BS on first load, and with the timepicker enabled it will now also pre-fill a time the user may not intend. If the conversion runs before the field hydrates you may get an empty or double-converted value.

Locale and display format. Nepali numerals (Devanagari digits) versus Latin digits is a display choice, not a storage one. If the package exposes a format string or locale toggle, set it once in a panel service provider or config rather than per-field, so tables and forms match. After upgrading, verify time formatting (12/24-hour, AM/PM in Devanagari vs Latin) is covered by the same config.

Fallback plan. If the package stalls, the wrapper is thin enough to replace: keep your own NepaliDatePicker / NepaliDateTimePicker form component that wraps Filament's DatePicker/DateTimePicker with a formatStateUsing/dehydrateStateUsing pair calling a BS converter, and let Filament's built-in timepicker handle the clock. That is roughly what this package does, and owning it removes the version-compatibility risk entirely.