Verta Laravel Package

Getting Started

Install via Composer:

composer require hekmatinasser/verta

First Use Case: Replace Gregorian dates in your app with Jalali equivalents.

// Get current Jalali date
$jalaliDate = verta(); // Returns "1401-05-24 00:00:00"

// Convert Gregorian Carbon instance to Jalali
$gregorianDate = now();
$jalaliDate = $gregorianDate->toJalali(); // Returns "1401-05-24 00:00:00"

// Parse Jalali string into Verta instance
$vertaInstance = Verta::parse('1401-05-24 14:12:32');

Where to Look First:

• Documentation for method references.
• verta() helper for quick instantiation.
• toJalali()/toCarbon() for bidirectional conversions.

Implementation Patterns

Core Workflows

1. Date Conversion Pipeline:

   // API Request → Gregorian → Jalali → Store/Display
   $gregorianInput = request('date');
   $jalaliDate = verta($gregorianInput)->formatJalaliDatetime();
   

2. Validation Integration:

   // Form validation rule
   $request->validate([
       'birthday' => 'required|jdate_before_equal:today',
   ]);
   

3. Localization-Aware Display:

   // Set locale and format
   Verta::setLocale('fa');
   $formattedDate = verta()->formatWord('l dS F'); // "دوشنبه بیست و چهارم مرداد"
   

Integration Tips

• Eloquent Models: Use accessors/mutators for Jalali date fields:

  public function getJalaliDateAttribute()
  {
      return verta($this->attributes['created_at'])->formatJalaliDatetime();
  }
  

• Carbon Compatibility: Leverage existing Carbon methods with Jalali awareness:

  $jalaliDate = verta()->addDays(7)->subHours(2); // Works like Carbon
  

• Blade Directives: Create a custom Blade directive for consistent formatting:

  Blade::directive('jalali', function ($expression) {
      return "<?php echo verta({$expression})->formatJalaliDatetime(); ?>";
  });
  

  Usage: @jalali($post->created_at)

• Testing: Mock verta() in tests using the Verta facade:

  Verta::shouldReceive('parse')->andReturn(Verta::create('1401-01-01'));
  

Common Patterns by Use Case

Gotchas and Tips

Pitfalls

1. Timezone Mismatches:

   • Jalali dates are timezone-agnostic by default. Ensure your app’s timezone (e.g., Asia/Tehran) is set in config/app.php if time-sensitive operations are involved.
   • Fix: Explicitly set timezone when parsing:

     verta('2024-01-05', 'Asia/Tehran');
     

2. Leap Year Edge Cases:

   • Jalali leap years (e.g., ۱۳۹۶/۱۴۰۴) can cause off-by-one errors in calculations.
   • Fix: Use Verta::isLeapYear() to validate or adjust logic:

     if (Verta::isLeapYear($year)) { /* Handle leap year logic */ }
     

3. Carbon Version Conflicts:

   • Verta requires Carbon 2.x+. Conflicts may arise if your app pins an older version.
   • Fix: Update composer.json:

     "require": {
         "carbon/carbon": "^2.60"
     }
     

4. Database Storage:

   • Storing Jalali dates directly in databases can cause sorting issues (Jalali 1401-01-01 ≠ Gregorian 2022-03-21).
   • Fix: Store Gregorian dates and convert on display:

     // Migration
     $table->dateTime('created_at');
     
     // Model
     public function getJalaliCreatedAtAttribute()
     {
         return verta($this->created_at)->formatJalaliDatetime();
     }
     

5. Localization Quirks:

   • Some locales (e.g., Arabic) may not be fully supported. Fallback to en if needed:

     Verta::setLocale('ar'); // May throw if unsupported
     

Debugging Tips

• Validate Parsing:

  verta('invalid-date')->isValid(); // Returns false
  

• Inspect Internals:

  $date = verta();
  dump($date->year, $date->month, $date->day); // Debug components
  

• Compare with Carbon:

  $carbon = now();
  $jalali = verta();
  dump($carbon->diffInDays($jalali->toCarbon())); // Should be ~0 for same date
  

Extension Points

1. Custom Formatters: Extend the formatter by creating a new class:

   use Verta\Verta;
   
   class CustomFormatter {
       public static function fiscalYear(Verta $date)
       {
           return $date->year + 1300; // Example: Fiscal year logic
       }
   }
   

2. Validation Rules: Add custom rules to AppServiceProvider:

   use Illuminate\Support\Facades\Validator;
   
   Validator::extend('jdate_after_today', function ($attribute, $value, $parameters) {
       return verta($value)->gte(verta());
   });
   

3. Carbon Extensions: Add Jalali methods to Carbon globally:

   Carbon::macro('toJalali', function () {
       return verta($this)->formatJalaliDatetime();
   });
   

4. Localization Overrides: Override month/day names in config/verta.php:

   'locales' => [
       'fa' => [
           'months' => ['فروردین', 'اردیبهشت', /* ... */],
           'days' => ['شنبه', 'یک‌شنبه', /* ... */],
       ],
   ],
   

Performance Considerations

• Avoid Redundant Parsing: Cache parsed dates if used repeatedly:

  $cachedDate = verta($user->birthday);
  

• Batch Operations: For bulk date conversions, use array methods:

  $dates = collect($orders)->map(fn ($order) => verta($order->created_at));
  

• Benchmark Leap Year Logic: If processing many dates, pre-check leap years:

  $isLeap = Verta::isLeapYear($year); // Cache result
  

Configuration Quirks

• Default Locale: Set globally in config/verta.php:

  'default_locale' => 'fa',
  

• Carbon Integration: Disable if not needed to reduce overhead:

  'carbon_integration' => false,
  

• Strict Mode: Enable to throw exceptions on invalid dates:

  'strict' => true, // Throws \InvalidArgumentException on invalid input