Nova Persian Date Field Laravel Package

Product Decisions This Supports

• Persian-market sequencing: launch blocker or fast-follow? This package answers one narrow question concretely — can an in-region operator enter a date in the calendar they actually think in, without us building calendar infrastructure? Treat it as one input to the roadmap call, not the call itself. Localization is broader than a date field, and a date field is not a market-entry strategy.

• Build vs. buy vs. defer on calendar UX. Jalali↔Gregorian conversion, the 33-year leap cycle, and Nova's field lifecycle are individually small and collectively fiddly. The realistic options are: adopt this package as-is, fork it and own roughly 200 lines of PHP field plus a Vue component, or wrap a mature JS datepicker (persian-datepicker, react-multi-date-picker) with server-side conversion via morilog/jalali or hekmatinasser/verta. This is the cheapest option and the least owned — the decision is which risk you'd rather carry, not which option is "correct."

• Admin/back-office UX for date-critical workflows. Order and delivery dates, billing and subscription cycles, fiscal periods (Farvardin 1 start), scheduled campaigns, report date-range filters. Anywhere an in-region operator types or reads a date, this is the last mile of an otherwise-shipped feature — and the place where mis-entry becomes a support ticket or a billing correction.

• Storage policy: render local, store Gregorian. The PM-level decision this package must be measured against is that canonical dates stay UTC/Gregorian, indexed and queryable, with Jalali as presentation only. If the field writes Jalali strings to the database, it is not a UX convenience — it is a data-model change with downstream reporting, sorting, and index consequences. Decide that before adoption, not in QA.

• The "do nothing" baseline. Persian labels over a Gregorian picker is a cheaper interim that may satisfy non-Iran-based staff and customers. Deciding this package is not needed yet is a legitimate and often correct roadmap outcome — particularly if Persian-speaking operators are a small minority of admin users.

• Where it earns its keep: internal ops back offices staffed in-region; B2B SaaS sold into Iran-region customers; finance and reporting surfaces where local-calendar accuracy is a trust issue; any workflow where a wrong date is plausible-looking and expensive to catch after the fact.

When to Consider This Package

Adopt when:

• You already run Laravel Nova. Outside Nova this package is inert — it has no meaning for Filament, Blade, Inertia, or API surfaces.
• Persian-speaking operators touch dates daily, and a mis-entered date carries real cost: billing errors, missed delivery windows, fiscal-period mistakes, compliance reporting.
• Your need is narrow: display and input in the admin, with Gregorian/UTC underneath. This is a field, not a localization program.
• You have verified compatibility rather than assumed it — Nova major (4 vs. 5), Laravel, PHP. Nova 4 is Vue 2-based; Nova 5 moved to Vue 3/Inertia and field components do not port automatically. "It installed" is not "it works."
• You accept the risk profile and have a plan for it: 5 stars, 0 dependents, a single maintainer, last release December 2024. Acceptable for internal tooling where you fork on day one. Thin for a revenue-critical, multi-tenant surface with no named owner.
• You or your team are willing to own it: pin the version, wrap it in an internal field class, add your own round-trip and timezone tests.

Look elsewhere when:

• You are not on Nova — use Filament's community Jalali plugins, or a Blade/Inertia form plus a mature JS Jalali datepicker.
• You need Jalali logic server-side: date math, report bucketing, cron schedules, fiscal-period rollups. This is a presentation-layer field; pair it with a PHP conversion library regardless.
• You need vendor support, an SLA, or an upgrade guarantee. There is no vendor here — there is a maintainer.
• You need broader Persian localization: RTL layout, translated validation messages, Persian numeral formatting, locale-aware sorting. This solves one slice, not the locale.
• A Nova major upgrade is imminent and untested against this field, or upstream has gone quiet since the December 2024 release.
• The date surface is customer-facing rather than internal admin — the blast radius of a silently wrong date is much larger than the star count justifies.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost enabler for serving Persian-speaking markets — not a strategic bet, and it should be funded as such. It removes a concrete usability blocker in our admin back office: staff entering dates in a calendar they don't use, which is a reliable source of data-entry errors and support tickets. Building the equivalent — Jalali picker, conversion, Nova integration — is roughly a week of engineering plus permanent correctness risk in calendar edge cases. Adoption is about a day of integration. The failure mode is contained because it is an isolated UI field: as long as we hold the discipline that Gregorian/UTC stays the storage of record and Jalali is display-only, we can swap or remove it without touching a single stored record. Recommendation: adopt tactically for the in-region back office, fork it so we own the code, and revisit the investment if and when the Persian market becomes material to revenue.

To engineering: Single-purpose Nova field, drop-in, small surface area — a PHP Field subclass plus a pre-compiled Vue component. Three asks before merge. (1) Confirm the storage contract: it must write Gregorian to a datetime column and convert at render; if it writes Jalali strings, stop and either wrap it or reject it, because that turns every date-range query into a string scan. (2) Verify the conversion and timezone story: confirm which library (if any) does the Jalali math, and pin down the timezone contract — Iran abolished DST in 2022, so historical offsets differ from current rules, and that is exactly where off-by-one-day bugs hide. (3) Wrap and pin: land an internal App\Nova\Fields\JalaliDateTime extending or composing the vendor class, so there is one swap point for a fork or replacement, and add our own round-trip and timezone tests so a Nova upgrade fails loudly rather than silently. Budget a one-to-two-day correctness spike first — leap days, the 1403/1404 boundary, DST transitions, null handling, and sorting/filtering behavior — pilot on a single low-traffic Resource, then roll out. Assume we own maintenance: a few days per Nova major upgrade plus ad-hoc patches, and document the storage/timezone contract internally because that knowledge does not exist anywhere upstream.