Vobject Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require sabre/vobject "^4.0"
   

   Ensure PHP ≥7.4 (or use ^3.4 for PHP 5.5).

2. First Use Case: Parse an .ics or .vcf file:

   use Sabre\VObject\Component\VCalendar;
   use Sabre\VObject\Component\VCard;
   
   // Parse iCalendar
   $ical = VCalendar::fromString(file_get_contents('event.ics'));
   $events = $ical->getChildren(['VEVENT']);
   
   // Parse vCard
   $vcard = VCard::fromString(file_get_contents('contact.vcf'));
   $name = $vcard->FN; // Access properties directly
   

3. Key Entry Points:

   • iCalendar: VCalendar, VEVENT, VTODO, VJOURNAL.
   • vCard: VCard, FN, EMAIL, TEL, ADR.
   • Recurrence: RRULE, RDATE, EXDATE (via Sabre\VObject\RecurrenceIterator).

4. Where to Look First:

   • Official Docs (vCard/iCalendar guides).
   • API Reference (e.g., Component, Property, RecurrenceIterator).
   • Changelog for breaking changes (e.g., PHP 8.x support).

Implementation Patterns

Core Workflows

1. Parsing and Serialization

• Parse from string/stream:

  $vcard = VCard::fromString($rawVcf);
  $ical  = VCalendar::fromStream($icsStream);
  

• Serialize to string:

  $serialized = $vcard->serialize();
  $ical->serialize($outputStream);
  

• Use Forgiving mode for malformed input:

  $vcard = VCard::fromString($brokenVcf, ['forgiving' => true]);
  

2. Working with Components

• Access nested components:

  foreach ($ical->getChildren(['VEVENT']) as $event) {
      $summary = $event->SUMMARY;
      $dtstart = $event->DTSTART->getDateTime();
  }
  

• Add/modify properties:

  $event->UID = 'unique-id-123';
  $event->DTSTART = '20230101T120000Z';
  $event->RRULE = 'FREQ=WEEKLY;UNTIL=20231231T235959Z';
  

3. Recurrence Handling

• Iterate over recurring events:

  $iterator = new \Sabre\VObject\RecurrenceIterator($event);
  foreach ($iterator as $instance) {
      $instanceDate = $instance->DTSTART->getDateTime();
  }
  

• Check if a date is excluded (e.g., EXDATE):

  if ($iterator->isDateInRange($date, $endDate)) {
      // Date is part of the recurrence
  }
  

4. vCard Manipulation

• Add/remove properties:

  $vcard->add('EMAIL', ['type' => ['WORK', 'INTERNET']], 'user@example.com');
  $vcard->remove('TEL', ['type' => 'CELL']);
  

• Access multi-valued properties:

  $emails = $vcard->EMAIL->getValues();
  

5. iTip (Scheduling Messages)

• Create a meeting request:

  use Sabre\VObject\iTip\Message;
  
  $message = new Message($event, 'REQUEST', 'organizer@example.com');
  $serialized = $message->serialize();
  

• Handle replies/cancellations:

  $broker = new \Sabre\VObject\iTip\Broker();
  $response = $broker->parse($rawItipMessage);
  

6. Timezone Handling

• Set timezone for events:

  $event->DTSTART = '20230101T120000';
  $event->DTSTAMP = '20230101T120000Z';
  $event->VTIMEZONE = $timezoneComponent; // From \Sabre\VObject\Component\VTimezone
  

• Convert timezones:

  $dt = $event->DTSTART->getDateTime();
  $dt->setTimezone(new \DateTimeZone('America/New_York'));
  

Integration Tips

Laravel-Specific Patterns

1. Store/Retrieve from Database:

   • Serialize to JSON for storage:

     $serialized = $vcard->serialize();
     $vcardData = ['raw' => $serialized, 'type' => 'vcard'];
     

   • Reconstruct on retrieval:

     $vcard = VCard::fromString($vcardData['raw']);
     

2. API Endpoints:

   • Export vCard/iCalendar:

     return response($vcard->serialize(), 200, [
         'Content-Type' => 'text/vcard',
         'Content-Disposition' => 'attachment; filename="contact.vcf"',
     ]);
     

   • Import from request:

     $vcard = VCard::fromString(request()->file('vcard')->getContent());
     

3. Queue Jobs for Recurrence Processing:

   RecurrenceJob::dispatch($event)
       ->onQueue('calendar')
       ->delay(now()->addHour());
   

4. Validation:

   • Use Laravel’s validation to check required fields:

     $validator = Validator::make($request->all(), [
         'vcard' => 'required|string',
     ]);
     

5. Event Listeners:

   • Trigger actions on recurrence changes:

     Event::listen('calendar.event.recurrence.changed', function ($event) {
         // Send notifications, update UI, etc.
     });
     

Common Extensions

1. Custom Property Types: Extend Sabre\VObject\Property for domain-specific fields:

   class CustomProperty extends \Sabre\VObject\Property\Property {
       public function __construct($name, $value, array $parameters = []) {
           parent::__construct($name, $value, $parameters);
       }
   }
   

2. Recurrence Filters: Create a decorator for RecurrenceIterator:

   class FilteredRecurrenceIterator extends \Sabre\VObject\RecurrenceIterator {
       public function __construct(\Sabre\VObject\Component\VEvent $event, callable $filter) {
           parent::__construct($event);
           $this->filter = $filter;
       }
   
       public function current() {
           $event = parent::current();
           return $this->filter($event) ? $event : null;
       }
   }
   

3. Timezone Service: Centralize timezone logic:

   class TimezoneService {
       public function getTimezoneComponent(string $tzId): \Sabre\VObject\Component\VTimezone {
           // Fetch or create VTIMEZONE component
       }
   }
   

Gotchas and Tips

Pitfalls

1. Timezone Quirks:

   • Floating vs. Fixed Timezones: Floating times (e.g., DTSTART:20230101T120000) are local time; fixed times (e.g., DTSTART:20230101T120000Z) are UTC. Always specify TZID for floating times to avoid ambiguity.
   • Daylight Saving Transitions: Use Sabre\VObject\Timezone\TimezoneConverter for accurate conversions:

     $converter = new \Sabre\VObject\Timezone\TimezoneConverter();
     $dt = $converter->convert($dt, 'America/New_York', 'UTC');
     

2. Recurrence Edge Cases:

   • Infinite Loops: Yearly RRULEs with BYMONTHDAY or BYDAY can cause infinite loops. Use UNTIL to bound ranges:

     $event->RRULE = 'FREQ=YEARLY;BYMONTH=12;UNTIL=20300101T000000Z';
     

   • **EXDATE vs. RD