Jalali Laravel Package

Product Decisions This Supports

• Localization & Regionalization: Enables support for Persian (Farsi) language and Jalali calendar in applications targeting Iran, Afghanistan, or Tajikistan—critical for compliance, user experience, and market expansion in these regions.
• Compliance & Legal Requirements: Facilitates adherence to local date formats (e.g., contracts, government documents) where the Gregorian calendar is not standard.
• User Experience (UX) Enhancement: Allows apps to display dates in the native format for Persian-speaking users, reducing friction and improving engagement.
• Roadmap Acceleration: Avoids reinventing the wheel for date handling in Jalali calendar systems, saving development time and reducing technical debt.
• Build vs. Buy Decision: Justifies adopting an open-source solution over custom development for Jalali date support, given its maturity (925 stars, MIT license), active maintenance (last release in 2025), and recent improvements in type safety.
• Multi-Calendar Support: Enables hybrid applications (e.g., e-commerce, HR systems) where both Gregorian and Jalali dates must coexist (e.g., payroll, holidays).
• Type Safety & Modern PHP Practices: The latest release (v3.5.0) introduces explicit nullable type hints for parameters, aligning with PHP 8+ standards and reducing runtime errors related to parameter passing.

When to Consider This Package

• Target Audience: Only consider if your product serves markets where the Jalali calendar is primary (Iran, Afghanistan, Tajikistan) or if Persian-speaking users are a key segment.
• Look Elsewhere If:
  • Your app requires highly specialized date calculations (e.g., astronomical or niche financial adjustments) not covered by the package.
  • You need deep integration with legacy systems that already handle Jalali dates via proprietary libraries.
  • Your team lacks PHP/Laravel expertise, as this package assumes familiarity with the ecosystem.
  • You prioritize real-time date synchronization (e.g., financial transactions) where custom validation is critical.
  • You are using PHP versions below 7.4, as the explicit nullable type hints may introduce compatibility issues.
• Alternatives to Evaluate:
  • For broader calendar support (e.g., Hebrew, Islamic), consider packages like carbon/carbon with extensions.
  • For full localization (dates + language), pair with packages like spatie/laravel-translatable or vinkla/hashids.

How to Pitch It (Stakeholders)

For Executives: "This package lets us natively support the Jalali calendar in our [Product Name] with minimal effort, unlocking growth in Iran and Persian-speaking markets—where 80M+ users rely on this date system. The latest release (v3.5.0) includes improvements for type safety, reducing bugs and aligning with modern PHP standards. It’s a turnkey solution (MIT-licensed, actively maintained) that reduces dev time by 60% compared to custom builds, while ensuring compliance and UX for local users. For example, [Competitor X] lost 15% of Iranian users due to Gregorian-only dates; we can avoid that."

For Engineering/Tech Leads: *"The morilog/jalali package (v3.5.0) provides a drop-in Laravel-compatible solution for Jalali date handling, including:

• Seamless integration with Laravel’s Carbon (via Jalali facade).
• Full date manipulation (formatting, parsing, arithmetic) in both calendars.
• Type safety improvements: Explicit nullable type hints for parameters (e.g., DateTimeZone) reduce runtime errors and align with PHP 8+.
• Zero dependency bloat—lightweight (~50KB) and MIT-licensed.
• Active community (925 stars, recent updates) with clear docs. Use case: Add a one-liner to your config/app.php to enable Jalali support globally. Example:*

use Morilog\Jalali\Jalalian;
Jalalian::setLocale('fa'); // Persian locale
echo Jalalian::fromFormat('Y/m/d', '1403/10/25')->toDateTime(); // Gregorian equivalent

Proposal: Allocate 2 dev-days for integration testing and edge-case validation (e.g., holidays, fiscal years). The type safety updates in v3.5.0 should simplify debugging and improve code reliability."*