Filament Jalali Laravel Package

Technical Evaluation

Baseline assessment — no prior evaluation data was supplied, so this is established from the v6.0.0 release notes plus the package's known role as a Jalali (Solar Hijri) date adapter for Filament form and table components.

Architecture fit

• The package is a presentation/localization layer over Filament's date fields, filters, and columns. It should not be treated as the application's canonical date library; persistence should remain Gregorian/UTC with Jalali conversion confined to the admin UI boundary.
• Fit is conditional on market need: it is only justified if the product serves Persian (fa_IR) users or Iranian regulatory/business contexts. Otherwise it is unnecessary surface area.
• It integrates via standard Laravel service-provider registration and Filament plugin/field conventions, so it does not impose structural constraints on our domain model.

Integration feasibility

• High, but only in lockstep with the framework: v6.0.0 is fundamentally a compatibility release ("Add Laravel 13 and Filament 5 support"), not a feature release. The paired change is a test refactor to use Jalali date test configuration, which suggests internal test plumbing rather than new public API.
• The major version bump implies a raised dependency floor. That makes this an upgrade-orchestration problem rather than a drop-in patch.

Technical risk

• Medium overall. Risk is concentrated in four places:
  1. Dependency pinning — the package's composer.json constraints gate, or are gated by, our Filament and Laravel versions. A major bump here forces a coordinated platform upgrade.
  2. Calendar correctness — leap-year handling, 30- vs. 31-day months, Esfand 30, and Asia/Tehran timezone/DST behavior are the historical failure surface for Jalali libraries. The release notes give no evidence of expanded boundary coverage; the test change is a configuration refactor, not necessarily new assertions.
  3. Storage semantics — low risk if conversion is render/parse only; high risk if any path writes converted values. This must be verified, not assumed.
  4. Maintainer concentration — community package, single named contributor across both changes. Bus factor is 1.

Key questions

• What are the exact require constraints for laravel/framework, filament/filament, livewire/livewire, and PHP in v6.0.0?
• Does v6 change any public API (field class names, method signatures, config keys), or only constraints and tests?
• Is Filament 5 support validated against 5.x stable, or is it an "allow install" constraint?
• Does the package still store Gregorian/UTC and convert only at the UI layer?
• What test coverage exists for leap years, Esfand 30, and timezone round-trips? Are fixtures published in the repo?
• What is the concrete diff and effort from v5.x — are there breaking changes for existing field definitions?
• Are companion concerns (RTL layout, Persian numerals, translations) in scope or handled separately?
• License terms, release cadence, and open security advisories.

Integration Approach

Stack fit

• Laravel + Filament admin panel with Persian-facing operators. Scope it deliberately: admin form/table/filter date handling only. Do not let it leak into APIs, exports, reporting SQL, or scheduled-job logic, where a second date convention would create ambiguity.

Migration path

• Because v6 requires Laravel 13 / Filament 5, treat this as a platform upgrade program, not a package bump. Two viable orderings:
  • Preferred (isolate failure domains): upgrade Laravel 12 → 13 and Filament 4 → 5 first, holding the Jalali package at v5 or temporarily removing it and gating those fields, then reintroduce v6.
  • Fallback (if the package is load-bearing): upgrade framework, Filament, and the package together in a single branch, accepting a larger but atomic blast radius.
• Either way, the rollback unit is composer.lock plus any published assets — confirm no migrations or data rewrites are introduced before committing.

Compatibility

• Verify PHP floor and Livewire version, which usually move with a Filament major.
• Audit third-party Filament plugins that override or decorate date fields; field-type collisions are the most likely breakage, not the Jalali package itself.
• Confirm whether the datepicker's client assets are bundled or require vendor:publish, and whether the publish tag changed.

Sequencing

1. Inventory every Jalali-dependent field, filter, widget, and export.
2. Build a compatibility matrix (PHP / Laravel / Filament / Livewire / package) and validate in a branch.
3. Assemble a golden-file regression set of known Jalali↔Gregorian pairs, including leap-year and Esfand 30 cases.
4. Upgrade staging; run the regression set plus an admin smoke pass.
5. Pilot with internal Persian-speaking users before general release.
6. Production rollout behind a config toggle where feasible; document the revert procedure.

Operational Impact

Maintenance

• Small code footprint, but a single-maintainer dependency. Expect a recurring upgrade tax: this package's majors track Filament majors, so every Filament upgrade becomes a two-dependency negotiation. Budget for a fork-or-patch contingency and keep the wrapper thin so replacement stays cheap.

Support

• No vendor SLA. Ownership must be explicitly assigned to the team that owns the admin panel — not left implicit. Record the calendar and storage semantics in an internal ADR so operational knowledge does not live solely upstream.

Scaling

• Negligible runtime cost: conversion is request-time formatting with no extra queries or storage. Watch only for client-side asset weight and any per-row conversion in large table exports or report generation, where it can become linear overhead.

Failure modes

• Silent off-by-one-day errors at month and year boundaries — no exception, just wrong dates in the UI.
• Esfand 30 mishandled in non-leap years.
• Timezone drift between Asia/Tehran display and UTC storage across midnight boundaries.
• Datepicker assets not republished after upgrade, producing a broken control with no server-side error.
• A Filament minor release breaking the field integration before upstream catches up.
• Upstream going dormant while Filament advances, stranding us on an old platform.
• Mitigations: round-trip conversion unit tests, the golden-file fixture set, and a mandatory date-field smoke test item in the Filament upgrade checklist.

Ramp-up

• Low for developers already fluent in Filament (hours to first productive use). Moderate for the team's grasp of Jalali edge cases, which is the actual risk driver. Allocate roughly 1–2 days for upgrade validation in this cycle, plus a short internal write-up and committed test fixtures.