Filament Jalali Datetime Laravel Package

Product Decisions This Supports

• Localization roadmap for Persian (Farsi) markets: Confirms whether we can ship a first-class Jalali (Shamsi) date/time experience in Filament admin panels without building a custom field from scratch — form pickers, table columns, and filters that display and accept Jalali dates while persisting standard Gregorian timestamps.
• Build vs. buy for admin/back-office tooling: A narrow, single-purpose plugin. Buying (adopting) costs an afternoon of integration; building means owning calendar conversion, timezone edge cases, validation, and Filament asset/version compatibility — typically weeks of effort plus permanent maintenance.
• Data model safety: Because it keeps stored values Gregorian and only changes presentation/input, it does not force a schema or reporting-pipeline change. That makes it a reversible, low-blast-radius decision for finance, scheduling, and reporting surfaces.
• Feature gating: Enables region-specific admin UX (e.g., Iranian operations teams, Persian-language tenant portals) without forking the core admin panel or maintaining a separate localized build.
• Vendor/dependency posture: The 1.4.2 release only extends composer.json to declare PHP 8.4 support — a compatibility-maintenance signal, not a feature change. It supports the decision to keep the plugin on our upgrade path alongside Laravel/Filament upgrades rather than pinning the platform.
• Use cases: subscription/renewal dates, appointment and delivery scheduling, invoice and report date ranges, audit/activity timelines, and any admin filter where the operator thinks in Jalali dates but the database and analytics remain Gregorian.

When to Consider This Package

Adopt when:

• The product serves Persian-speaking users or an Iranian operations team, and dates are a first-class part of the admin workflow (not a single read-only field).
• The stack is Filament v3+ on a currently supported PHP version; 1.4.2 explicitly adds PHP 8.4, so it fits modern Laravel runtimes.
• You want Jalali display with Gregorian storage — i.e., no migration of existing date columns and no dual-writing.
• Your team has no in-house Jalali calendar expertise and the cost of a bespoke field exceeds the cost of a small third-party dependency.
• You can accept a single-maintainer community package with a correspondingly small support surface.

Look elsewhere (or build) when:

• The admin panel is not Filament — this is Filament-specific and offers no value outside that ecosystem.
• You need Hijri, Hebrew, Buddhist, or multi-calendar support in one abstraction; a general localization/Intl-based approach is a better fit.
• Persian dates must appear in customer-facing APIs, PDFs, exports, or public web surfaces — the plugin's scope is Filament UI, so you'd need a separate formatting layer regardless.
• Compliance or procurement rules require a vendor with an SLA, security review, or long-term support commitment.
• You already standardized on a broader Filament localization suite; overlapping packages create duplicate JS assets and conflicting field behavior.

Release-specific caution: PHP 8.4 support is a declaration in composer.json, not evidence of a broad CI matrix. Verify in our own staging environment before treating 8.4 as validated, and pin a version range rather than floating.

How to Pitch It (Stakeholders)

For executives: This is a small, free, open-source add-on that lets our admin interface show and accept Persian (Jalali) dates without changing how dates are stored or reported. It unlocks the Iranian/Persian-speaking segment of our roadmap at roughly the cost of one integration ticket instead of a multi-week build, and it is removable — if it doesn't work out, we revert the UI and lose no data. The trade-off is dependency on a single-maintainer package, which we mitigate by pinning versions and reviewing upgrades; the latest patch simply keeps it compatible with current PHP versions.

For engineering: ariaieboy/filament-jalali-datetime supplies a Filament form field, table column, and filter that render Jalali dates while reading and writing Gregorian values — so no schema migration, no changes to analytics or reporting pipelines, and no timezone-model surprises. 1.4.2 is a maintenance patch adding PHP 8.4 to composer.json; no API, behavior, or config changes, so it is a safe patch bump. Please: pin to ^1.4, confirm the 8.4 claim in CI rather than trusting the manifest, add a test asserting round-trip conversion (Jalali input → Gregorian storage) around any critical date field, and isolate the dependency behind our own form-component wrapper so a future swap to an Intl-based or multi-calendar solution is a contained change.

Recommendation: Adopt for Filament admin surfaces in Persian-market scope; upgrade to 1.4.2 as a routine patch; do not extend it to customer-facing or export/reporting date formatting without a separate, deliberate decision.