Filament Jalali Laravel Package

Product Decisions This Supports

• Market entry / localization strategy for Persian-speaking users. This package is the difference between an admin panel that feels native to Iranian users and one that forces them to mentally convert Shamsi dates to Gregorian. That is a real activation and support-cost lever for any product targeting Iran, Afghanistan, or Persian-speaking diaspora users.
• Build vs. buy on Jalali date handling. Solar Hijri conversion looks like a formatting problem and is not: leap-year rules, 29/30/31-day months, Iran's 2022 DST abolition, and timezone edge cases all bite. Buying a maintained Filament-native wrapper avoids a multi-week side quest that no one will staff properly.
• Framework commitment. Adopting this package is effectively a vote that Filament is your admin/back-office stack for a Persian-first product. That is a roadmap decision, not just a dependency decision — it raises the switching cost of ever leaving Filament.
• Scope calls on date UX. Whether you support date-only vs. datetime, range pickers, table column formatting, and date filters in the admin is now a cheap decision rather than an engineering negotiation. Persian date input can move from "phase 2, needs research" to "in scope."
• Reporting and document compliance. Official Iranian documents, invoices, and internal reports are commonly expected in Shamsi. Having this in the form layer means reports can be generated in the same calendar users typed in, without a parallel conversion pipeline.
• The upgrade target is now 3.1.0, not 3.0.0 — and that is a scheduling input, not just a version number. 3.0.0 was a major bump published with only a diff link as its changelog; 3.1.0 (published 2026-01-28) is a patch release whose substantive item is a fix for a calendar display defect ("مشکل در نمایش تقویم بعد از آپدیت" — calendar display problem after the update, issue #43). Read plainly: the 3.0.0 major shipped with a visible UI regression that took roughly a release cycle to land. Plan the upgrade as 2.2.0 → 3.1.0, skipping 3.0.0 entirely, and still treat it as a time-boxed spike (read the diff, confirm the supported Filament major) rather than a routine bump.

When to Consider This Package

Consider it when all of the following hold:

• You are building on Filament (this is Filament-specific — it is not a general Jalali library and will not help you in Blade, Inertia, or a non-Filament Livewire app).
• Your users expect to enter and read Shamsi dates in the admin UI, not just see them rendered.
• You need the unglamorous trio: form input, table column display, and date filtering — all in one consistent component.
• Your team has no in-house calendar-domain expertise and you would rather not acquire it.

Look elsewhere when:

• You are not on Filament. Use a general-purpose Jalali library (e.g. morilog/jalali or hekmatinasser/verta) and build your own bindings. Server-side-only conversion is a solved problem and does not need a UI package.
• You need the lunar Hijri (Islamic) calendar, or multiple calendars at once. This solves Jalali, not Hijri, and not a general calendar abstraction.
• Your canonical storage and display are Gregorian, with Shamsi only needed on one exported PDF. Convert at the edge; don't add a UI dependency for one document.
• You need rich scheduling/calendar views (agenda, resource booking, drag-and-drop). This is a date picker, not a calendar engine.
• You need a complete Persian/RTL localization suite. Pair with dedicated translation/RTL packages; don't expect this to cover it.
• Your procurement rules penalize small-maintainer dependencies. This is a narrow, single-maintainer ecosystem package with a small contributor base and no formal changelog discipline. If it lands on a revenue-critical path, plan an isolation layer.

Two signals to weigh either way:

• In favor: 3.1.0 landed promptly after the reported defect, with a docs improvement and a first-time contributor. That is a maintainer who is responsive and accepting help — the failure mode you actually fear (abandonment) is not what this looks like today.
• Against: a display-level regression surviving a major release is exactly the class of bug a thin dependency can push into your UI. That argues for pinning to an exact version and behind an internal wrapper, not for avoiding the package.

How to Pitch It (Stakeholders)

For executives: This is a small, cheap dependency that unlocks a credible Persian-language admin experience. For an Iranian-market product it removes a visible "this tool wasn't built for you" signal at the exact moment users do data entry. The upgrade story has clarified since the last review: the 3.0.0 major shipped with a calendar display bug that the maintainer fixed in 3.1.0 a short time later. Net cost is unchanged — a short, time-boxed upgrade spike — and the recommended path is to go straight to 3.1.0, not to evaluate 3.0.0. The residual risk is dependency hygiene, not the vendor disappearing.

For engineering: A thin Filament wrapper over an established Jalali conversion library, covering form fields, table columns, and filters. Pin 3.1.0. Do not adopt or ship 3.0.0: 3.1.0's only functional change is a fix for a calendar rendering defect reported after the 3.0.0 update, so 3.0.0 is a known-bad target. The rest of the 3.1.0 delta is CI (actions/checkout 6→7), a README rewrite, and a first-time contributor — no new API surface, no deprecations, no documented breaking changes. 3.0.0 itself remains undocumented beyond a compare/2.2.0...3.0.0 diff link, so the major-version risk is still unretired: read that diff before merging, and confirm which Filament major 3.x targets, since in this ecosystem a plugin major almost always tracks a Filament major and your Filament version may dictate your plugin version. Wrap usage behind a small internal formatter/field layer and add a smoke test that actually renders a Jalali date picker in the admin — the 3.0.0 regression was a display bug, which a compile-time-only check would have missed.