Jalali Laravel Package

Product Decisions This Supports

• Localization & Regional Compliance: Enables support for the Jalali (Persian) calendar in applications targeting markets like Iran, Afghanistan, or Tajikistan, ensuring compliance with local date/time standards (e.g., legal documents, scheduling, or user-facing interfaces).
• Carbon Compatibility: Leverages Laravel’s Carbon integration, reducing friction for teams already using Carbon for datetime handling. Avoids reinventing the wheel for Jalali-specific logic.
• Roadmap for Multilingual Products: Critical for scaling products into Persian-speaking regions, where Gregorian dates may be secondary or irrelevant (e.g., e-commerce, SaaS platforms, or government tools).
• Build vs. Buy: Buy—this package is lightweight (MIT-licensed), actively maintained (recent release), and eliminates the need to build custom Jalali datetime logic from scratch.
• Use Cases:
  • User Interfaces: Display dates in Jalali format while storing Gregorian internally (e.g., 1403/01/01 alongside 2024-03-21).
  • Data Migration: Convert legacy Jalali dates in databases to Gregorian (or vice versa) without manual scripts.
  • APIs: Standardize date formats for clients in Jalali-using regions (e.g., created_at_jalali alongside created_at).
  • Scheduling: Calendar apps or reminders where Jalali dates are primary (e.g., Islamic holidays, local events).

When to Consider This Package

• Adopt if:
  • Your product serves Persian-speaking markets (Iran, Afghanistan, Tajikistan) and requires Jalali date support.
  • You’re using Laravel/Carbon and want seamless integration without breaking existing datetime logic.
  • You need bidirectional conversion (Gregorian ↔ Jalali) with minimal code (e.g., Carbon::parse('1403-01-01')->toDateTimeString()).
  • Your team lacks expertise in custom datetime libraries and prefers a battle-tested solution.
• Look elsewhere if:
  • Your app only needs Gregorian dates (no Jalali requirement).
  • You require advanced Jalali-specific features (e.g., Hijri calendar support) not covered here (consider proengsoft/laravel-jalali).
  • You’re in a high-performance context (this package adds ~50KB; benchmark if critical).
  • Your team prefers not to depend on external packages (though MIT license mitigates risk).

How to Pitch It (Stakeholders)

For Executives: *"This package lets us enter Persian-speaking markets without building custom date logic. For ~50KB and a one-line composer install, we get:

• Compliance: Meet local date standards (e.g., Iranian legal systems use Jalali).
• User Experience: Show dates in the user’s preferred format (e.g., 1403/01/01 for Iranian users).
• Efficiency: Reuses our existing Carbon infrastructure, saving dev time. Cost: Near-zero. Risk: Minimal (MIT license, active maintenance). ROI: Enables revenue in untapped regions with minimal effort."*

For Engineering: *"This is a drop-in Carbon extension for Jalali dates. Key benefits:

• Zero refactoring: Works with existing Carbon methods (e.g., parse(), diff(), format()).
• Lightweight: ~50KB, no heavy dependencies.
• Well-documented: English docs + GitHub examples.
• Maintained: Last release in April 2024; issues are responsive. Tradeoff: Limited to Jalali (no Hijri/other calendars). If we need more, we can scope future work. Proposal: Add to composer.json and test in staging. Impact: Enables Jalali support in 1–2 dev days."*