Iranian Date Picker Laravel Package

Technical Evaluation

Architecture fit. The package is a Filament form-field plugin: a custom Field class that renders a Persian (Jalali) date picker on the front end and reconciles values with the Gregorian dates Laravel stores. Architecturally it slots into Filament's forms() schema as a drop-in replacement for DatePicker, so it does not disturb the underlying Eloquent model, migration, or validation layers. That containment is the main reason to consider it: the integration surface is a single field type plus a service provider/plugin registration, not a cross-cutting concern.

Integration feasibility. Mechanically low-friction — composer require, register the plugin in the PanelProvider, swap field imports. The real feasibility question is version coupling. The last release is April 2023, which predates Filament 3's stable release and long predates Filament 4. A Filament plugin of that vintage typically pins filament/filament and illuminate/* constraints that will conflict with a current install, so "does it install" is likely to fail before "does it work." Expect either a composer constraint override, a community fork, or a manual patch to the plugin's composer.json and namespace/API usage. Budget for this as a fork-and-vendor exercise, not a clean install.

Technical risk.

• Staleness vs. Filament's release cadence. Filament ships breaking majors roughly annually. A 2023 plugin is likely one to two majors behind, and Filament's form/asset APIs changed materially across 2→3→4.
• Silent date corruption. The highest-severity risk is not a crash but a wrong date: Jalali↔Gregorian conversion, leap-year handling (the 33-year cycle), and timezone boundaries can all produce off-by-one-day errors that look fine in the UI and are only caught in production data.
• Asset pipeline. Persian date pickers usually bundle a JS library (persian-datepicker or similar) published via Filament::serving / asset registration. Filament's asset handling changed across majors, so the widget may render unstyled or non-functional even if PHP-side registration succeeds.
• Single maintainer, zero dependents. 24 stars and 0 dependents means effectively no field-tested usage; you are the first real adopter. There is no ecosystem signal that it works against any current stack.
• Opportunity signal (0.89) is misleading for TPM purposes. It reflects whitespace in the ecosystem — Filament + Iranian market is underserved — not package quality. The gap is real; this specific package is not proven to fill it.

Key questions to resolve before committing.

1. Which Filament major is the target, and does the package's composer.json constraint support it? (Read the constraint first; this is a 5-minute disqualifier.)
2. Does the field persist Gregorian to the database and only render Jalali, or does it store Jalali strings? The former is mandatory for portability.
3. How is conversion implemented server-side — a maintained library (e.g., morilog/jalali, Carbon Jalali) or hand-rolled? Hand-rolled conversion is a red flag.
4. Timezone contract: does it convert in the app timezone, UTC, or browser-local? Where are day-boundary dates (23:00–01:00 local) handled?
5. Is it date-only, or does it handle datetime and time components?
6. Are JS assets bundled, published, or CDN-loaded? Any Vite/npm dependency that could break on Filament upgrade?
7. Test coverage and CI status — is there any automated verification of conversion correctness?
8. Maintenance intent: is the maintainer responsive on issues, and is a fork acceptable to the organization?

Integration Approach

Stack fit. Only relevant if the target is a Laravel + Filament admin/panel application serving an Iranian or Persian-speaking user base that needs Jalali input. If the app is not Filament, this package has no value — use a standalone Jalali conversion library plus a plain JS datepicker instead. Fit is narrow and high-specificity: exactly the right shape for the gap, exactly the wrong shape for anything adjacent.

Migration path. Treat it as an isolated, replaceable dependency:

1. Add via Composer with an explicit version pin, and immediately fork to an internal namespace (acme/iranian-date-picker) so patches are not blocked on upstream.
2. Wrap the field in a thin internal factory (JalaliDate::make()) that returns the plugin field. Every form references the wrapper, never the vendor class directly — this makes a future swap to a different picker or a homegrown field a one-file change.
3. Keep database columns as date/datetime (Gregorian) with no schema change; verify by test that the stored value round-trips correctly.
4. Replace existing DatePicker usages incrementally, form by form, with visual QA in a Jalali locale.

Compatibility. Pin Filament to the version the plugin actually supports, or pin the plugin to a fork compatible with your Filament version — do not attempt to run both unconstrained. Check PHP version constraints too; a 2023 package may cap at PHP 8.1/8.2. Confirm laravel/framework constraint against the app's version. If the app is on Filament 3+, assume you are maintaining the fork.

Sequencing.

• Spike (1–2 days): install in a scratch Laravel+Filament app at the target versions, confirm the field renders, submits, and round-trips a known set of dates across leap years and DST-adjacent boundaries.
• Decision gate: if the spike requires more than a day of patching, switch to a maintained Jalali library plus a custom Filament field — you will write less code than you will spend reviving this one.
• Pilot: one non-critical admin form.
• Rollout: remaining forms, gated on conversion correctness tests.
• Contingency: internal fork published to a private registry is the default outcome, not the fallback.

Operational Impact

Maintenance. The dominant cost. No release since April 2023, one maintainer, no dependent ecosystem to surface regressions. Realistically the team owns this code: budget for a fork, a patch cadence aligned to Filament majors, and a named owner. The codebase is small enough to audit in an afternoon, which caps the cost — but it also means every Filament upgrade carries a "does the date picker still work" checklist item indefinitely.

Support. GitHub issues only, no SLA, no commercial backing. Acceptable for an internal admin tool; not acceptable for anything customer-facing with date-entry SLAs. Internal documentation of the patched delta is mandatory so the next engineer isn't reverse-engineering why the vendor package differs from upstream.

Scaling. Negligible runtime scaling concern — it is a client-side widget with a per-request conversion cost measured in microseconds. The scaling risk is organizational: every additional Filament panel multiplies the number of form fields depending on an unmaintained fork, and the blast radius of a Filament upgrade grows with it. RTL/localization requirements (Persian numerals, right-to-left layout, Iranian holidays) may need extension beyond what the package provides.

Failure modes.

• Highest severity — silent date corruption: off-by-one-day errors from conversion or timezone handling reaching persisted records. Mitigation: automated tests asserting specific known dates (leap years 1403, month boundaries, 23:30 local) round-trip to the correct Gregorian value before and after any upgrade.
• Upgrade breakage: composer conflict or a Filament major making the field inert or unstyled. Mitigation: pin Filament and treat plugin compatibility as a release-gate item.
• Asset regression: picker renders as a plain text input, users type free-form Jalali strings, validation misses. Mitigation: visual smoke test in CI or a pre-release QA checklist.
• Abandonment: repository archived or issues unanswered. Mitigation: fork already in place; no action needed beyond continuing to patch.
• Low visibility into regressions: zero dependents means no upstream bug reports. Mitigation: your own test suite is the only safety net.

Ramp-up. For a developer already fluent in Filament, the field API is a sub-hour ramp; the real learning is Jalali conversion semantics, timezone boundaries, and Persian date formatting conventions — call it 1–2 days to be confident, plus the fork-and-patch overhead if the spike lands on a Filament version mismatch. The 0.89 opportunity score is a genuine market signal (Filament + Iranian locale is underserved) but should be read as "build or fork something here," not "adopt this package as-is." Recommendation: proceed only with an internal fork and a conversion test suite in place; otherwise, implement a thin custom field over a maintained Jalali library and accept roughly the same effort with materially less maintenance risk.