Jalali Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package is a lightweight, domain-specific solution for handling Jalali (Persian) calendar conversions and operations in PHP/Laravel. It directly addresses regional/localization needs (e.g., Iran, Afghanistan) where the Gregorian calendar is not the standard.
• Extensibility: The package extends PHP’s native DateTime and is Carbon-compatible, enabling seamless integration with Laravel’s built-in date/time utilities (e.g., Carbon, CarbonImmutable). This reduces friction in adoption.
• Isolation: The package operates at the data layer (conversion/formatting) without modifying core Laravel logic, minimizing architectural risk.

Integration Feasibility

• Low Coupling: The package provides helper functions and Jalali class wrappers, requiring minimal changes to existing date/time logic. Example:

  use Jalali\Jalalian\Jalalian;
  $jalaliDate = Jalalian::fromFormat('Y-m-d', '1399/10/10'); // Convert to Jalali
  $gregorianDate = $jalaliDate->toCarbon(); // Convert back to Gregorian
  

• Database Compatibility: Requires no schema changes if Jalali dates are stored as strings (e.g., YYYY/MM/DD). For numeric storage (e.g., MySQL DATE), additional validation logic may be needed.
• Testing Overhead: Unit tests for date conversions (e.g., edge cases like leap years) should be prioritized due to the mathematical complexity of Jalali calendar calculations.

Technical Risk

• Carbon Dependency: While the package claims Carbon compatibility, version conflicts could arise if the project uses a different Carbon version. Risk mitigation:
  • Pin carbon/carbon to a stable version (e.g., ^2.65) in composer.json.
  • Test with CarbonImmutable if the project relies on immutable dates.
• Performance: Jalali-to-Gregorian conversions involve complex algorithms. Benchmark critical paths (e.g., bulk date processing) to ensure no latency spikes.
• Time Zone Handling: The package does not explicitly document timezone support. Verify if Jalali instances respect PHP’s default timezone or require manual adjustments.
• Deprecation Risk: The package has low activity (2 stars, infrequent releases). Monitor for upstream changes or forks (e.g., mheydari/jalali).

Key Questions

1. Regional Requirements:
   • Are Jalali dates required for UI display only (e.g., user-facing dates) or business logic (e.g., deadlines, scheduling)?
   • Does the project need bidirectional conversion (Jalali ↔ Gregorian) or one-way?
2. Data Storage:
   • How are dates currently stored (e.g., Gregorian DATE in DB, user input format)? Will migration be needed?
3. Carbon vs. Native DateTime:
   • Does the project use Carbon extensively? If not, test Jalali with PHP’s native DateTime for consistency.
4. Localization:
   • Are there additional localization needs (e.g., Persian month names, holidays) beyond basic conversion?
5. Fallback Strategy:
   • What happens if the package fails (e.g., due to a bug in Jalali calculations)? Is a graceful fallback (e.g., Gregorian) acceptable?

Integration Approach

Stack Fit

• Laravel Ecosystem: The package is PHP 8.0+ compatible and integrates with Laravel’s:
  • Carbon: For existing date logic (e.g., now(), parse()).
  • Eloquent: For model attributes/mutations (e.g., accessors, mutators).
  • Validation: For input sanitization (e.g., jalali|date rules).
  • Localization: For Persian month/day names (if extended).
• Non-Laravel PHP: Can be used in vanilla PHP projects, but loses Laravel-specific conveniences (e.g., service providers, facades).

Migration Path

1. Phase 1: Proof of Concept (PoC)

   • Install the package:

     composer require hekmatinasser/jalali
     

   • Test basic conversions in a sandbox environment:

     use Jalali\Jalalian\Jalalian;
     $jalali = Jalalian::fromFormat('Y/m/d', '1403/05/10'); // 10 May 1403 (Jalali)
     $gregorian = $jalali->toCarbon(); // Convert to Gregorian for storage/processing
     

   • Validate edge cases (e.g., 1399/12/30 → Gregorian 2021-03-20).

2. Phase 2: Core Integration

   • Service Provider: Register the package in config/app.php and create a facade (optional) for consistency:

     // app/Providers/JalaliServiceProvider.php
     public function register() {
         app()->singleton('jalali', function () {
             return new Jalalian();
         });
     }
     

   • Carbon Wrapper: Extend Laravel’s Carbon facade to include Jalali methods:

     // app/Extensions/CarbonExtension.php
     Carbon::macro('toJalali', function () {
         return Jalalian::fromCarbon($this);
     });
     

   • Database Layer: Add accessors/mutators to Eloquent models:

     // app/Models/Appointment.php
     protected $appends = ['jalali_date'];
     public function getJalaliDateAttribute() {
         return $this->date->toJalali()->format('Y/m/d');
     }
     

3. Phase 3: Full Adoption

   • Replace hardcoded Gregorian dates in business logic with Jalali-aware functions.
   • Update API responses and UI components to use Jalali dates where required.
   • Implement input validation for Jalali dates (e.g., using Laravel’s Rule objects).

Compatibility

• Laravel Versions: Tested with Laravel 8+ (PHP 8.0+). For older versions, check for Carbon compatibility.
• Dependencies:
  • Conflict Risk: Low if carbon/carbon is pinned.
  • PHP Extensions: None required.
• Database:
  • MySQL/PostgreSQL: Store dates as strings (e.g., VARCHAR) or use DATE with validation.
  • MongoDB: Store as ISO strings or convert on read/write.

Sequencing

1. Non-Critical Paths First: Start with read-only Jalali conversions (e.g., displaying dates to users).
2. Critical Paths Last: Avoid integrating Jalali dates into core business logic (e.g., payment deadlines) until thoroughly tested.
3. UI Layer: Update frontend templates last to minimize user-facing issues during migration.

Operational Impact

Maintenance

• Vendor Lock-in: Low risk due to MIT license and simple API. However, monitor for abandonware (last release: 2024-04-09).
• Dependency Updates: Pin carbon/carbon to avoid breaking changes. Consider forking if the package stagnates.
• Custom Logic: Extend the package (e.g., add Persian holidays) via composer patches or a custom wrapper class.

Support

• Documentation: The package has basic English docs, but assume users will need to:
  • Write internal runbooks for common use cases (e.g., "How to validate a Jalali date input").
  • Document edge cases (e.g., Jalali leap years affecting calculations).
• Debugging:
  • Time Zone Issues: Log timezone settings during conversions.
  • Date Mismatches: Add assertions to catch discrepancies between Jalali/Gregorian.
• Community: Limited support; rely on GitHub issues or create a private Slack channel for internal discussions.

Scaling

• Performance:
  • Single Conversions: Negligible overhead (microseconds).
  • Bulk Operations: Test with 10K+ records to ensure no memory leaks (Jalali calculations are CPU-bound).
  • Caching: Cache frequent conversions (e.g., current date) if latency is critical.
• Database:
  • Indexing: Ensure queries on Jalali-formatted strings are optimized (e.g., avoid LIKE for partial matches).
  • Storage: Prefer string storage for Jalali dates to avoid conversion overhead on reads/writes.
• Distributed Systems: No inherent scaling issues, but ensure timezone consistency across microservices.

Failure Modes