Icalcreator Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require kigkonsult/icalcreator
   

   Ensure your composer.json targets PHP 8+ for the latest stable version (2.40+).

2. First Use Case: Generate a basic .ics file for a single event:

   use Kigkonsult\Icalcreator\Vcalendar;
   
   $vcal = Vcalendar::factory(['UNIQUE_ID' => 'your-app@example.com']);
   $event = $vcal->newVevent()
       ->setSummary('Team Meeting')
       ->setDtstart(new \DateTime('20231015T100000'))
       ->setDtend(new \DateTime('20231015T110000'));
   
   $ics = $vcal->createCalendar();
   file_put_contents('meeting.ics', $ics);
   

3. Where to Look First:

   • Demo Usage: Real-world examples (recurring events, timezones, alarms).
   • Summary Docs: Component reference (e.g., VEVENT, VTODO, VTIMEZONE).
   • GitHub Issues: Check for recent RFC updates or bugs.

Implementation Patterns

Core Workflows

1. Event Creation with Recurrence

$event = $vcal->newVevent()
    ->setSummary('Weekly Sync')
    ->setDtstart(new \DateTime('20231001T090000'))
    ->setRrule([
        Vcalendar::FREQ => Vcalendar::WEEKLY,
        Vcalendar::UNTIL => new \DateTime('20231231'),
    ]);

• Tip: Use setExdate() to exclude specific instances (e.g., holidays).

2. Timezone Handling

$vcal->setTimezone('America/New_York');
$vcal->vtimezonePopulate(); // Auto-populates VTIMEZONE component

• Laravel Integration: Store timezones in a database and fetch dynamically:

  $tz = Timezone::where('id', $event->timezone_id)->first()->name;
  $vcal->setTimezone($tz);
  

3. Participant Management

$event->setOrganizer('admin@example.com', [
    Vcalendar::CN => 'Admin User',
    Vcalendar::ROLE => Vcalendar::CHAIR,
]);
$event->setAttendee('user@example.com', [
    Vcalendar::PARTSTAT => Vcalendar::NEEDS_ACTION,
    Vcalendar::RSVP => Vcalendar::TRUE,
]);

• Laravel Eloquent: Sync attendees from a users table:

  $attendees = User::whereIn('id', $event->attendees)->get();
  foreach ($attendees as $user) {
      $event->setAttendee($user->email, [
          Vcalendar::CN => $user->name,
          Vcalendar::PARTSTAT => Vcalendar::ACCEPTED,
      ]);
  }
  

4. Alarms/Notifications

$alarm = $event->newValarm()
    ->setAction(Vcalendar::DISPLAY)
    ->setTrigger('-PT1H') // 1 hour before
    ->setDescription('Meeting reminder!');

5. Export to File/Response

// Save to file
file_put_contents(storage_path('app/calendar.ics'), $vcal->createCalendar());

// Return as HTTP response (Laravel)
return response($vcal->createCalendar())
    ->header('Content-Type', 'text/calendar')
    ->header('Content-Disposition', 'attachment; filename="calendar.ics"');

Integration Tips

Laravel Service Provider

Register the package and bind a factory:

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->bind(Vcalendar::class, function () {
        return Vcalendar::factory([
            Vcalendar::UNIQUE_ID => config('app.name'),
            Vcalendar::PRODID => '-//' . config('app.name') . '//NONSGML v1//EN',
        ]);
    });
}

Database Sync

Use Laravel migrations to store iCal data:

Schema::create('ical_events', function (Blueprint $table) {
    $table->id();
    $table->string('uid')->unique();
    $table->string('summary');
    $table->dateTime('dtstart');
    $table->dateTime('dtend')->nullable();
    $table->json('rrule')->nullable();
    $table->json('attendees')->nullable();
    $table->timestamps();
});

API Endpoints

Create routes for calendar operations:

// routes/api.php
Route::get('/calendar/{event}', [CalendarController::class, 'export']);
Route::post('/calendar', [CalendarController::class, 'import']);

Gotchas and Tips

Pitfalls

1. Timezone Mismatches:

   • Always use DateTimezone objects (e.g., new DateTime('20231015T100000', new DateTimezone('America/New_York'))).
   • Fix: Call vtimezonePopulate() after setting the timezone.

2. Recurrence Rule Conflicts:

   • RRULE and RDATE/EXDATE can overlap. Validate with:

     $vcal->validateCalendar();
     

3. UID Collisions:

   • Ensure UNIQUE_ID is globally unique (e.g., include a UUID or database ID):

     $vcal->setUniqueId('event-' . Str::uuid()->toString());
     

4. PHP 8+ Deprecations:

   • Avoid create_function() or dynamic properties. Use modern syntax:

     // Bad (legacy)
     $event->setProperty('SUMMARY', 'Meeting');
     
     // Good (PHP 8+)
     $event->setSummary('Meeting');
     

5. Large Calendars:

   • Memory issues with thousands of events. Use chunking or streaming:

     $vcal->setOutputFormat(Vcalendar::OUTPUT_FORMAT_ICAL);
     $vcal->setOutputCharset('UTF-8');
     

Debugging

1. Validate Output:

   $vcal->validateCalendar();
   if ($vcal->errorCode()) {
       throw new \RuntimeException($vcal->errorMessage());
   }
   

2. Inspect Components:

   $vcal->debugComponent(); // Dumps raw iCal data
   

3. Common Errors:

   • "Invalid property value": Check DTSTART/DTEND formats (must be DateTime objects).
   • "Missing required property": Ensure SUMMARY and DTSTART are set for VEVENT.

Extension Points

1. Custom Properties:

   $event->setXprop('X-CUSTOM', 'value', [
       Vcalendar::ALTREP => 'CID:custom@example.com',
   ]);
   

2. Hooks for Pre/Post Processing:

   $vcal->setPreProcessor(function ($component) {
       if ($component instanceof \Kigkonsult\Icalcreator\Vevent) {
           $component->setComment('Auto-generated by ' . config('app.name'));
       }
   });
   

3. Laravel Events: Trigger events when calendars are generated:

   // app/Providers/EventServiceProvider.php
   public function boot()
   {
       CalendarGenerated::dispatch($vcal->createCalendar());
   }
   

4. Testing:

   • Use Mockery to stub DateTime objects:

     $mockDate = Mockery::mock(\DateTime::class);
     $mockDate->shouldReceive('format')->andReturn('20231015T100000');
     $event->setDtstart($mockDate);
     

Performance Tips

1. Reuse Components:

   $alarm = $vcal->newValarm()->setAction(Vcalendar::DISPLAY);
   $event1->setComponent($alarm);
   $event2->setComponent($alarm); // Reuse alarm
   

2. Batch Processing:

   $events = Event::where('is_recurring', true)->get();
   $vcal = Vcalendar::factory([...]);
   foreach ($events as $event) {
       $vcal->addComponent($event->toIcalComponent());
   }
   

3. Cache Timezones:

   // Cache VTIMEZONE components
   Cache::remember('vtimezone-Europe/London', 3