Nova Persian Datepicker Laravel Package

Technical Evaluation

Architecture fit. The package is a Laravel Nova field extension — it hooks into Nova's Field contract and ships a Vue component that swaps the native date picker for a Jalali (Shamsi) calendar. That is the correct and only sensible architecture for this problem in Nova; there is no competing integration pattern. The design pattern is well-trodden (Nova's nova:field scaffolding), so anyone who has built or consumed a Nova field will recognize the shape immediately. The package does not touch application domain logic, Eloquent models, or API layers, which keeps blast radius small.

Integration feasibility. Mechanically trivial: composer require, register or rely on package discovery, then add the field to a Nova resource. The real feasibility question is not "can we install it" but "will it survive Nova's release cadence." Nova ships major versions roughly annually with meaningful breaking changes to the field API and frontend stack; a package with 20 stars and 0 dependents has almost certainly not been hardened against Nova 5-era changes. Expect to verify version constraints in composer.json before committing. Budget an afternoon for a throwaway spike rather than trusting the README.

Technical risk. Ranked:

1. Silent data corruption via calendar mismatch — the highest-severity risk. The field must persist Gregorian ISO dates to the database while rendering Jalali to the user. If the round-trip is asymmetric (e.g., stores the Jalali string, or misinterprets a formatted date on hydration), you get plausible-looking but wrong dates that pass visual inspection and fail in reports. This must be explicitly tested, not assumed.
2. Abandonment / bus factor of one. 0 dependents means no downstream cohort is exercising this against new Nova releases. When Nova 6 lands, nobody will have filed the breaking-change issue.
3. Third-party JS dependency drift. The Vue datepicker underneath is unlikely to be pinned aggressively; a transitive upgrade can break rendering without any change in your code.
4. Timezone handling. Nova fields default to app timezone; Persian users in Asia/Tehran need consistent handling. Iran abolished DST in 2022, which removes the worst historical edge cases, but boundary-of-day behavior still needs a test.

Severity is moderate because the failure surface is confined to an admin UI, not a public API — but "confined to admin" is cold comfort when the admin is where orders, subscriptions, and compliance dates get entered.

Key questions.

• Which Nova major versions are supported, and when was the constraint last bumped?
• Does it store Gregorian in the DB and only render Jalali, or does it persist a Jalali string?
• How does it behave when editing a record created with Nova's native Date field — does existing data render correctly?
• Is there a test suite? Any CI? Last commit date?
• Does it integrate with Nova filters, lenses, and DateTime variants, or only the base Date field?
• What is the fallback if it breaks — is the in-house reimplementation effort estimated (likely 1–3 dev-days)?

Integration Approach

Stack fit. Clean. Laravel + Nova shops add fields via Composer and a one-line resource change; nothing else in the stack is implicated. No database migrations, no config publishing required in the common case, no service provider conflicts expected. It slots into the existing Nova ecosystem orthogonally — it neither depends on nor constrains the rest of your application.

Migration path. The migration is conceptual, not schema-level: you are changing the presentation layer of a date column, not its storage. Steps:

1. Confirm how existing date columns are stored (almost certainly Gregorian DATE/DATETIME). No backfill should be necessary — but verify by opening a known record and confirming the displayed Jalali date maps to the stored Gregorian value.
2. Replace Date::make('...') with the Persian field on a single resource in a staging environment.
3. Write a record through the field, read it back through raw SQL, and assert the stored value is Gregorian and correct.
4. Only then roll out resource by resource.

If any resource stores dates as Jalali strings (legacy homegrown tooling), stop and backfill before proceeding.

Compatibility. Three axes to check and pin: Nova major version, PHP version (Nova's own floor moves), and the underlying JS/Vue datepicker. Pin the package version explicitly in composer.json — do not float on ^1.0.

Sequencing.

1. Spike on a disposable Nova instance (half day): install, render, write, read back via SQL.
2. Confirm Nova version support and read the source of the Vue component — with 20 stars, reading ~200 lines of code is cheaper than trusting the docs.
3. Decide build-vs-buy: if the spike reveals staleness, forking and vendoring the package (it is MIT, so this is licensed and legal) is often cheaper than finding an alternative.
4. Roll to one internal resource, then to customer-facing resources.
5. Document the fork/pin decision in the repo's dependency register.

Operational Impact

Maintenance. This is the dominant cost and it is not zero. A single-maintainer package with no dependents means you are effectively the maintainer of record for your organization's copy. Plan for:

• A review at every Nova upgrade (annual minimum), budgeted as a half-day.
• A vendored fork or a private Composer VCS entry so you can patch without waiting on upstream.
• A named owner on the team — "whoever touched it last" is not an owner.

The saving grace: the codebase is small and the domain problem is well-bounded, so the fork is a low-friction fallback rather than a hostage situation.

Support. Community-only, best-effort, no SLA, and a maintainer whose attention cannot be assumed. Escalation path is: patch your fork → reimplement in-house (1–3 days) → swap packages. Any of these is viable; none is free. Do not place this on a path where an outage blocks revenue-critical admin workflows without a documented workaround.

Scaling. Effectively a non-issue. This is a browser-rendered field component; it imposes no server load, no query overhead, and no concurrency concerns. Rendering cost is one small JS bundle per admin page. There is no scaling dimension on which this package can become a bottleneck. The scaling risk is entirely organizational — how many resources adopt it and whether the fork is kept current.

Failure modes. In descending order of impact:

• Silent date corruption. Field stores the wrong calendar representation; data looks right in the UI, is wrong in the DB. Detected weeks later in reporting or billing. Worst case. Mitigate with a write-then-verify-SQL test in staging and a one-off audit query after rollout.
• Nova upgrade breakage. Field throws or renders blank after a Nova major bump. Loud, immediate, easy to diagnose — the good kind of failure.
• JS dependency regression. Picker fails to open, or opens with an empty calendar. Loud, cosmetic, blocking for data entry but not corrupting.
• Timezone drift at day boundaries. Off-by-one-day on records entered near midnight. Subtle and annoying; mitigate with a timezone assertion in the spike.
• Maintainer disappearance. Not an event, a slow decay. Manifests as the Nova-upgrade breakage above, with the added cost of having to fork under time pressure. Pre-empt by forking pre-emptively if the package passes the spike.

Ramp-up. Low for any Laravel developer: 1–2 hours to install, wire, and understand the field. The genuine learning curve is domain knowledge — Jalali calendar mechanics, the Gregorian/Jalali boundary, and why "just format the date" is the wrong instinct here. That knowledge should live with one or two people and be written down, because the failure mode is a well-meaning developer "fixing" the formatting and quietly breaking persistence. Onboarding cost is small; the cost of an under-informed change is not.