Jalali Date Time Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require borsaco/jalali-date-time-bundle
   

   Register the bundle in AppKernel.php:

   new Borsaco\JalaliDateTimeBundle\JalaliDateTimeBundle(),
   

2. First Use Case: Inject the service into a controller or service:

   use Symfony\Component\DependencyInjection\ContainerInterface;
   
   public function __construct(ContainerInterface $container) {
       $this->jalaliDateTime = $container->get('jalali_date_time');
   }
   

   Format a Jalali date:

   $this->jalaliDateTime->date('l j F Y H:i'); // e.g., "شنبه ۱۴۰۰/۰۱/۰۱ ۱۲:۳۰"
   

Implementation Patterns

Core Workflows

1. Date Formatting:

   • Use jalali_date_time->date() with format strings (e.g., 'Y/m/d' for ۱۴۰۰/۰۱/۰۱).
   • Pass a Unix timestamp for custom dates:

     $this->jalaliDateTime->date('Y/m/d', strtotime('2023-01-01'));
     

2. Timezone Handling:

   • Specify timezones for conversions:

     $this->jalaliDateTime->date('l j F Y H:i T', false, false, false, 'Asia/Tehran');
     

3. Form Integration:

   • Use JalaliDateType in Symfony forms:

     $builder->add('birthday', JalaliDateType::class);
     

   • Pair with bootstrap-persian-datetimepicker for frontend UI.

4. Service Injection:

   • Prefer dependency injection over container access:

     public function __construct(JalaliDateTime $jalaliDateTime) {
         $this->jalaliDateTime = $jalaliDateTime;
     }
     

Common Use Cases

• API Responses: Convert Gregorian dates to Jalali for Persian-speaking users.
• Database Storage: Store Jalali dates as strings (e.g., Y/m/d) and convert on display.
• Validation: Validate Jalali-formatted dates in forms.

Gotchas and Tips

Pitfalls

1. Deprecated Kernel:

   • The bundle targets Symfony 2.x/3.x (last release 2020). For Symfony 5/6, check compatibility or fork the package.

2. Timezone Confusion:

   • Timezone arguments are optional but critical for accuracy. Defaults may not match expectations.

3. Form Type Limitations:

   • JalaliDateType lacks built-in validation. Extend it or use constraints:

     use Symfony\Component\Validator\Constraints\Date;
     $builder->add('date', JalaliDateType::class, [
         'constraints' => [new Date()]
     ]);
     

4. DatePicker Dependency:

   • Frontend integration requires bootstrap-persian-datetimepicker. Ensure JS/CSS assets are loaded.

Debugging Tips

• Verify Output: Compare Jalali dates with known values (e.g., ۱۴۰۰/۰۱/۰۱ = 2021-03-21).
• Check Timezone: Use date_default_timezone_get() to debug timezone issues.
• Log Errors: Wrap calls in try-catch for edge cases (e.g., invalid timestamps).

Extension Points

1. Custom Formats: Extend the service to add methods for common formats:

   public function jalaliShortDate($timestamp = null) {
       return $this->date('Y/m/d', $timestamp);
   }
   

2. Database Abstraction: Create a trait to handle Jalali ↔ Gregorian conversions in entities:

   trait JalaliDateTrait {
       public function getJalaliCreatedAt(): string {
           return $this->jalaliDateTime->date('Y/m/d', $this->createdAt->getTimestamp());
       }
   }
   

3. Event Listeners: Automate conversions in events (e.g., kernel.request):

   public function onKernelRequest(GetResponseEvent $event) {
       $request = $event->getRequest();
       if ($request->has('gregorian_date')) {
           $request->set('jalali_date', $this->jalaliDateTime->date('Y/m/d', $request->get('gregorian_date')));
       }
   }