Filament Jalali Laravel Package

Product Decisions This Supports

• Roadmap gating for Persian/Farsi (Jalali) market support: this package is the lowest-cost way to ship Solar Hijri date input, display, and filtering in Filament admin panels without hand-rolling calendar conversion logic. It directly enables an "Iran/Persian locale" milestone rather than requiring custom engineering.
• Build vs. buy: the alternative is writing and maintaining Jalali ⇄ Gregorian conversion, validation, picker UI, and column formatting in-house. That is undifferentiated work with high correctness risk (leap-year and month-length edge cases); buying via this OSS dependency is the clear default unless we have unusual calendar requirements (Hijri Qamari, multi-calendar per-user, fiscal calendars).
• Upgrade sequencing with Filament majors: v6.0.0 pins the package to Laravel 13 + Filament 5. This is a lockstep dependency — adopting Filament 5 forces this major, and staying on Filament 4 keeps us on v5.x. That makes this a scheduling input for any admin-panel framework upgrade, not an isolated library choice.
• Breaking-change triage: the major bump signals an API/behavior change tied to the Filament 5 upgrade path. PM action is to confirm whether any custom Filament resources, tests, or date-handling code touch this package's exposed API before committing to the Filament 5 roadmap item.
• Test-confidence signal (small but real): the release also refactors date tests to use real Filament table configuration instead of mocks. That slightly raises our confidence that table-level Jalali rendering is validated against actual framework behavior — worth noting when assessing quality of dependencies we inherit.

When to Consider This Package

Adopt when:

• The product needs an admin/back-office UI where Persian-speaking operators enter or read dates in Jalali, and the admin layer is Filament.
• The team is on (or moving to) Laravel 13 / Filament 5 — v6.0.0 is the compatible line; older stacks should stay on v5.1.0.
• You want date handling to remain a thin, replaceable dependency rather than core product logic; store Gregorian in the database, present Jalali at the UI edge.

Look elsewhere or proceed carefully when:

• Filament is not the UI layer. This is a Filament plugin; for Blade/Livewire/API-only surfaces, use a general Jalali library (e.g. a conversion/formatting package) instead.
• You are mid-migration off or onto a Filament major. Because this package versions in lockstep with Filament, a major bump here can be a migration blocker rather than a drop-in upgrade. Verify the full dependency set (Filament 5 ecosystem plugins) moves together.
• You need calendars beyond Jalali (Hijri Qamari, per-user calendar preference, dual-calendar display) or heavy timezone/fiscal-period logic — this plugin is scoped to Jalali presentation, not a calendar abstraction layer.
• Long-term maintenance is a hard requirement. It's a single-maintainer community package; if admin i18n is business-critical, budget for the option to vendor/fork the conversion layer, or keep the abstraction boundary thin enough to swap.
• You need a documented deprecation/migration path before upgrading. The v6.0.0 notes describe compatibility and test changes but not a migration guide; treat the major bump as "verify in a branch first," not "bump and ship."

How to Pitch It (Stakeholders)

For executives: Supporting Persian-speaking customers currently requires calendar work we'd otherwise build and maintain ourselves. This is a small, free, open-source plugin that plugs Jalali date handling into our existing Filament admin tooling. The new v6.0.0 release adds support for the next versions of our framework (Laravel 13 / Filament 5), which keeps our Persian-market option open without new headcount — but it's a major-version bump tied to a framework upgrade, so it becomes a work item inside that upgrade, not a standalone project. Risk is low and contained: it's a UI-layer dependency, and dates remain stored in the standard format so we can replace it later.

For engineering: v6.0.0 adds Laravel 13 and Filament 5 support and refactors Jalali date tests to exercise real Filament table configuration rather than test doubles. Because the package tracks Filament majors, v6 is only appropriate once we're on Filament 5; anything on Filament 4 should remain on v5.1.0. Before upgrading: audit custom resources, form/table schemas, and any tests that touch Jalali columns or pickers for behavioral changes, and confirm the rest of our Filament plugin set has Filament 5-compatible releases. Keep Jalali formatting confined to the presentation layer — persist UTC/Gregorian — so conversion logic never leaks into domain code and the dependency stays swappable. Recommend validating the upgrade in a branch with the admin i18n test suite before committing to the framework bump.