ariaieboy/filament-jalali
Bring Jalali (Persian) calendar support to Filament forms and tables. This plugin provides Jalali date, datetime, and time pickers, plus formatted table columns, so Laravel/PHP admin panels can handle Persian dates without custom conversion code. Easy to install and configure for Persian-language ap...
Architecture fit. ariaieboy/filament-jalali is an additive presentation-layer package for Filament panels: it supplies Jalali (Shamsi) date picker fields, table columns, and formatting helpers. Architecturally it is a leaf dependency with a small blast radius provided the team keeps Gregorian storage in the database and treats Jalali purely as a display/input concern. It fits Laravel + Filament monoliths and modular monoliths serving Persian-speaking users. The one real coupling is to Filament's major version — this package effectively inherits Filament's upgrade cadence.
Integration feasibility. Low effort for greenfield: composer require, publish assets/config if prompted, swap DatePicker/TextColumn for the Jalali variants in resources. Realistic estimate is days for a new panel, 1–3 weeks for an existing panel with hand-rolled date handling scattered across resources, exporters, and validation rules. Upgrade target is now 3.1.0, not 3.0.0 — see risk below.
Technical risk. Still elevated and still unquantified for the 3.0.0 baseline, but the 3.1.0 release materially changes the picture in one important way: it includes a fix for a calendar display regression introduced by the 3.0.0 update (upstream issue #43, fixed by the maintainer in PR #44). That confirms the major bump did break rendering for at least some users — i.e. the risk was real, not theoretical. The 3.1.0 notes themselves are low-signal: a Dependabot CI bump (actions/checkout 6→7, no runtime impact), a README/docs PR from a new contributor (no runtime impact), and the display fix described only by its Persian PR title. No changelog entry discloses what rendering path broke, whether any persisted or serialized value was affected, or whether 3.0.0 had a data-corrupting window.
Secondary risks unchanged: silent changes to storage format or JSON serialization, a bump in the underlying conversion library (Verta/Morilog-class), and PHP/Filament version-floor changes that force a platform upgrade rather than a package bump. New minor risk: the fix shipped as a minor (3.1.0) rather than a patch, and 3.0.0 shipped as a major with no changelog body — semver is being applied loosely here, so a floating constraint like ^3.0 will pull the fix and any future surprise minors automatically.
Key questions.
Stack fit. Targets Laravel 10–12 with Filament v3/v4 (to be confirmed against the actual composer.json). It should coexist with other Filament plugins; the practical check is composer why-not against every other Filament plugin in the project before committing.
Migration path. Do not upgrade in place blind. Keep 2.2.0 pinned on the current branch, create a spike branch targeting 3.1.0 (skip 3.0.0 entirely — there is no reason to adopt a version with a known, since-fixed rendering regression), and read the GitHub compare diff for both 2.2.0...3.0.0 and 3.0.0...3.1.0 directly — neither release note is sufficient as a change record. If 3.x requires a Filament major we have not adopted, this becomes a coordinated platform upgrade, not a dependency bump, and should be scoped and scheduled as such.
Compatibility. Verify four things explicitly: PHP version floor, Filament constraint, conversion-library constraint, and whether any config keys or publishable assets were renamed — note that 3.1.0's fix landed in the rendering/asset path, which is exactly where published-asset drift bites. Add a fifth check given #43: confirm the published assets/CSS/JS in our build match 3.1.0's expected set, not a stale 2.2.0 publish.
Sequencing.
Maintenance. Still a single-maintainer open-source package with a bus factor of one, but 3.1.0 is a modest positive signal: an issue was reported and the maintainer shipped a fix within a minor release, and the project picked up a second (docs) contributor. Read this as "maintainer is responsive," not as "changelog discipline fixed" — the 3.1.0 body is still PR titles with no technical detail. Continue pinning exact versions (3.1.0, not ^3.0), keeping a fork-ready posture, and budgeting for occasional vendoring or a local patch layer.
Support. GitHub issues only, no SLA, no commercial backing. Name an internal owner for this dependency — someone accountable for tracking upstream releases and re-reading diffs, because release notes cannot be relied on. Note that the meaningful bug report here (#43) is in Persian; whoever owns the watch should be able to read it or have it translated, otherwise regressions will surface as internal bug tickets instead of upstream ones.
Scaling. Runtime cost is negligible; calendar conversion is arithmetic, not I/O. The two things that matter at scale are (a) formatting dates in table columns across large result sets, which can introduce per-row overhead if conversion happens in PHP rather than the query, and (b) client-side picker payload for dense admin tables.
Failure modes. The dominant one remains off-by-one-day errors at month and year boundaries from incorrect leap-year handling in the Jalali cycle. Second, now confirmed-in-the-field: broken calendar widget rendering after a major upgrade (upstream #43) — the picker displays incorrectly while the rest of the app looks healthy, which is exactly the sort of bug that reaches production because it fails no assertions. Next, timezone drift when dates are stored in UTC and rendered as Tehran-local, particularly around midnight; note that Iran abolished daylight saving in 2022, so any conversion logic relying on historical DST rules should be re-validated. Other modes: silent display-only conversion creating mismatches between UI and exported reports, asset-publish failures after a major bump, RTL layout regressions, and validation rules accepting Jalali-shaped input while the underlying model expects Gregorian.
Ramp-up. Low for engineers already fluent in Filament — the field and column APIs are idiomatic. Moderate for anyone reasoning about dual-calendar data, because the storage-versus-display contract is implicit in the code and needs to be written down. Document that contract (store Gregorian/UTC, present Jalali) as part of this upgrade; it is the cheapest mitigation for most of the failure modes above. Add one concrete QA step to the ramp-up doc: any dependency bump touching this package requires someone to actually open a date picker and a date column and eyeball them.
How can I help you explore Laravel packages today?