Calendar Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require sylius/calendar
   

   Add to composer.json if using a monorepo or custom package structure.

2. Basic Usage

   use Sylius\Component\Calendar\Calendar;
   use Sylius\Component\Calendar\DateTimeFactory;
   
   $dateTimeFactory = new DateTimeFactory();
   $calendar = new Calendar($dateTimeFactory);
   
   $dateTime = $calendar->createDateTime('2023-12-25 14:30:00');
   

3. First Use Case Parse and manipulate dates in a timezone-aware way:

   $dateTime = $calendar->createDateTime('2023-12-25 14:30:00', 'Europe/Paris');
   $dateTime->setTimezone(new \DateTimeZone('America/New_York'));
   

Implementation Patterns

Core Workflows

1. Timezone Handling

   • Always pass a timezone when creating DateTime objects to avoid ambiguity:

     $dateTime = $calendar->createDateTime('2023-12-25', 'UTC');
     

   • Use Calendar::convertTimezone() for conversions:

     $converted = $calendar->convertTimezone($dateTime, 'Europe/London');
     

2. Date Arithmetic

   • Leverage DateTimeFactory for safe operations:

     $nextWeek = $dateTimeFactory->addDays($dateTime, 7);
     $nextMonth = $dateTimeFactory->addMonths($dateTime, 1);
     

3. Validation

   • Validate date ranges or formats:

     $isValid = $calendar->isValidDateTime('2023-02-30'); // false
     

4. Integration with Laravel

   • Service Provider Binding:

     $this->app->singleton(Calendar::class, function ($app) {
         return new Calendar(new DateTimeFactory());
     });
     

   • Form Requests:

     use Sylius\Component\Calendar\Calendar;
     
     public function rules()
     {
         return [
             'event_date' => ['required', function ($attribute, $value, $fail) {
                 $calendar = app(Calendar::class);
                 if (!$calendar->isValidDateTime($value)) {
                     $fail('The date is invalid.');
                 }
             }],
         ];
     }
     

5. Localization

   • Format dates for user-facing output:

     $formatted = $calendar->formatDateTime($dateTime, 'Y-m-d H:i:s', 'en_US');
     

Gotchas and Tips

Pitfalls

1. Timezone Assumptions

   • Gotcha: Forgetting to specify a timezone when creating DateTime objects defaults to the system timezone, which can cause inconsistencies in multi-environment apps.
   • Fix: Always pass a timezone explicitly:

     $dateTime = $calendar->createDateTime('2023-12-25', 'UTC');
     

2. Date Arithmetic Edge Cases

   • Gotcha: Adding months to dates near month-end (e.g., 2023-01-31 + 1 month → 2023-02-28 or 2023-02-31 depending on implementation). Sylius/Calendar handles this by adjusting to the last valid day.
   • Tip: Use DateTimeFactory::addMonths() for predictable results:

     $nextMonth = $dateTimeFactory->addMonths($dateTime, 1);
     

3. Immutable Objects

   • Gotcha: DateTime objects returned by DateTimeFactory are immutable. Modifications (e.g., setTimezone()) return a new object.
   • Tip: Chain operations or store results:

     $converted = $dateTime->setTimezone(new \DateTimeZone('UTC'));
     

4. Performance

   • Gotcha: Heavy date arithmetic in loops can be slow. Cache results where possible.
   • Tip: Use DateTimeFactory methods for one-off operations; avoid instantiating Calendar repeatedly.

5. Laravel Carbon Compatibility

   • Gotcha: If your app uses Carbon, Sylius/Calendar’s DateTime is a wrapper around PHP’s DateTime. Convert between them carefully:

     $carbon = Carbon::instance($dateTime->getDateTime());
     $syliusDateTime = $calendar->createDateTime($carbon->toDateTimeString(), $carbon->getTimezone()->getName());
     

Extension Points

1. Custom DateTime Factories

   • Extend DateTimeFactory to add domain-specific logic:

     class BusinessDateTimeFactory extends DateTimeFactory
     {
         public function addBusinessDays(DateTimeInterface $dateTime, int $days): DateTimeInterface
         {
             // Custom logic for business days (e.g., skip weekends)
             return parent::addDays($dateTime, $days);
         }
     }
     

2. Validation Rules

   • Create reusable validation rules for forms:

     use Sylius\Component\Calendar\Calendar;
     
     $calendar = app(Calendar::class);
     $validator = Validator::make($data, [
         'date' => ['required', function ($value) use ($calendar) {
             return $calendar->isValidDateTime($value);
         }],
     ]);
     

3. Event Scheduling

   • Combine with Laravel Events for scheduled tasks:

     $eventDate = $calendar->createDateTime('2023-12-25', 'UTC');
     event(new ScheduledEvent($eventDate));
     

4. Testing

   • Mock DateTimeFactory for predictable test dates:

     $mockFactory = Mockery::mock(DateTimeFactory::class);
     $mockFactory->shouldReceive('createDateTime')
         ->with('2023-01-01', 'UTC')
         ->andReturn(new \DateTime('2023-01-01', new \DateTimeZone('UTC')));
     $calendar = new Calendar($mockFactory);