Icalcreator Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dyvelop/icalcreator-bundle
   

   Ensure your composer.json pins icalcreator/icalcreator to ^2.24 for stability.

2. Enable Bundle: Add to config/app.php (Laravel 5.5+) or AppServiceProvider:

   $this->app->register(\Dyvelop\ICalCreatorBundle\DyvelopICalCreatorBundle::class);
   

3. First Use Case: Generate a basic .ics file in a controller:

   use Dyvelop\ICalCreatorBundle\Response\CalendarResponse;
   
   public function exportCalendar()
   {
       $calendar = app('dyvelop_icalcreator.factory')->create([
           'unique_id' => 'my_app_events',
           'filename' => 'events.ics',
       ]);
   
       $event = $calendar->newEvent();
       $event->setSummary('Team Meeting')
             ->setDtstart('20231005T140000')
             ->setDtend('20231005T150000');
   
       return new CalendarResponse($calendar);
   }
   

Where to Look First

• Bundle Docs: README for Symfony-specific setup.
• Underlying Library: iCalcreator v2.24 Docs for event properties (e.g., setRecurrenceRule()).
• Laravel Integration: Check vendor/dyvelop/icalcreator-bundle/Resources/config/services.yaml for service bindings.

Implementation Patterns

Core Workflows

1. Event Creation Pipeline:

   // In a service or controller
   public function createEvent($data)
   {
       $calendar = app('dyvelop_icalcreator.factory')->create();
       $event = $calendar->newEvent();
   
       // Map data to iCal properties
       $event->setUid($data['id'])
             ->setSummary($data['title'])
             ->setDtstart($data['start_at'] ?? now()->format('Ymd\THis\Z'))
             ->setDtend($data['end_at'] ?? now()->addHour()->format('Ymd\THis\Z'));
   
       // Add to calendar
       $calendar->addComponent($event);
   
       return $calendar;
   }
   

2. Timezone Handling: Configure globally in config/icalcreator.php:

   return [
       'default_timezone' => 'America/New_York',
   ];
   

   Override per event:

   $event->setTimezone('Europe/Paris');
   

3. Recurring Events: Use iCalcreator's recurrence rules:

   $event->setRecurrenceRule('FREQ=WEEKLY;BYDAY=MO,WE,FR');
   

Integration Tips

• API Responses: Return .ics files via Laravel’s Response:

  return response($calendar->render(), 200, [
      'Content-Type' => 'text/calendar',
      'Content-Disposition' => 'attachment; filename="events.ics"',
  ]);
  

• Email Attachments: Use SwiftMailer with the CalendarAttachment class:

  $message = app('mailer')->createMessage();
  $message->attach(new \Dyvelop\ICalCreatorBundle\Mailer\CalendarAttachment($calendar));
  

• Storage: Save .ics files to Laravel’s storage:

  $path = storage_path('app/calendars/' . $filename);
  file_put_contents($path, $calendar->render());
  

• Validation: Sanitize inputs before setting iCal properties (e.g., summary, description) to avoid injection:

  $event->setSummary(htmlspecialchars($data['title']));
  

Advanced Patterns

1. Dynamic Calendars: Create multiple calendars per request:

   $calendars = collect(['personal', 'work'])
       ->map(fn($type) => app('dyvelop_icalcreator.factory')->create([
           'unique_id' => "user_{$type}_calendar",
           'products' => [['name' => ucfirst($type)]],
       ]));
   

2. Event Serialization: Convert Laravel models to iCal events:

   public function toIcalEvent($model)
   {
       $event = $calendar->newEvent();
       $event->setUid($model->id)
             ->setSummary($model->title)
             ->setDtstart($model->start_at->format('Ymd\THis\Z'))
             ->setDescription($model->notes);
   
       return $event;
   }
   

3. Webhook Triggers: Generate .ics files on model events (e.g., saved):

   Event::listen('eloquent.saved: App\Models\Event', function ($model) {
       $calendar = $this->createEvent($model);
       Storage::put("public/exports/{$model->id}.ics", $calendar->render());
   });
   

Gotchas and Tips

Pitfalls

1. Deprecated API:

   • iCalCreator class is deprecated in v2.24; use Ical\Calendar directly:

     // ❌ Old
     $calendar = new \iCalCreator\iCalCreator();
     
     // ✅ New
     $calendar = app('dyvelop_icalcreator.factory')->create();
     

2. Timezone Quirks:

   • Events without explicit timezones default to the server’s timezone. Always set setTimezone() or configure globally:

     $event->setTimezone('UTC'); // Recommended for APIs
     

3. UTF-8 Encoding:

   • Ensure responses include charset=UTF-8:

     return response($calendar->render(), 200, [
         'Content-Type' => 'text/calendar; charset=UTF-8',
     ]);
     

4. Recurrence Rule Conflicts:

   • Invalid rules (e.g., FREQ=DAILY;UNTIL=20230101) may corrupt .ics files. Validate with:

     try {
         $event->setRecurrenceRule($rule);
     } catch (\Exception $e) {
         Log::error("Invalid recurrence rule: {$rule}", ['error' => $e->getMessage()]);
     }
     

5. Bundle Configuration Overrides:

   • Laravel’s config system may not merge Symfony’s config/packages/icalcreator.yaml. Explicitly define in config/icalcreator.php:

     return [
         'default_unique_id' => 'my_laravel_app',
         'default_timezone' => config('app.timezone'),
     ];
     

Debugging Tips

1. Log Raw Output:

   Log::debug('iCal Output:', [
       'raw' => $calendar->render(),
       'events' => $calendar->components(),
   ]);
   

2. Validate .ics Files: Use online validators like icalendar.org or:

   curl -H "Content-Type: text/calendar" --data-binary @events.ics https://icalendar.org/validator/
   

3. Check for Deprecations: Enable icalcreator debug mode in config/icalcreator.php:

   return [
       'debug' => env('ICAL_DEBUG', false),
   ];
   

Extension Points

1. Custom Event Properties: Extend Ical\Components\Event:

   use Ical\Components\Event as BaseEvent;
   
   class CustomEvent extends BaseEvent
   {
       public function setCustomField($name, $value)
       {
           $this->properties[] = new \Ical\Property\Text($name, $value);
       }
   }
   

2. Service Provider Overrides: Bind a custom factory in AppServiceProvider:

   public function register()
   {
       $this->app->bind('dyvelop_icalcreator.factory', function () {
           return new CustomCalendarFactory();
       });
   }
   

3. Middleware for .ics Files: Add headers or auth checks:

   public function handle($request, Closure $next)
   {
       if ($request->is('*.ics')) {
           $request->headers->set('X-Accel-Buffering', 'no');
       }
       return $next($request);
   }
   

Performance Quirks

• Large Calendars:

  • Avoid loading all events into memory at once. Stream responses:

    return response()->stream(function () use ($calendar) {
        echo $calendar->render();
    });
    

• Recurrence Calculation:

  • Complex rules (e.g., BYMONTHDAY=-1) can be slow. Pre-compute and cache: