Vobject Laravel Package

Getting Started

Install via Composer:

composer require sabre/vobject "^4.0"

Ensure PHP ≥7.4 (latest releases support up to PHP 8.4). The library is fully namespaced under Sabre\VObject.

First use case: Parse a .vcf contact file or .ics calendar export:

use Sabre\VObject\Reader;

$vcard = Reader::read(file_get_contents('contact.vcf'));
echo $vcard->FN->getValue(); // Output contact name

$calendar = Reader::read(file_get_contents('events.ics'));
foreach ($calendar->VEVENT as $event) {
    printf("%s: %s\n", $event->DTSTART->getValue(), $event->SUMMARY);
}

Review the vCard and iCalendar docs for detailed patterns.

Implementation Patterns

• Import/Export pipeline: Use Reader::read() (accepts strings, streams, or filenames) to parse ICS/VCF sources, then $component->serialize() to generate RFC-compliant output for download or storage.
• Programmatic scheduling: Build events dynamically with createComponent() and attach recurrence rules:

  $event = $calendar->createComponent('VEVENT');
  $event->set('SUMMARY', 'Team Sync');
  $event->DTSTART = new DateTime('2025-06-02 09:00:00');
  $event->RRULE = 'FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE,FR';
  $calendar->add($event);
  

• iTip broker automation: Use ITip\Broker to auto-generate scheduling messages (REQUEST, CANCEL, REPLY) when events change. Detect significant changes and trigger notifications without manual SMTP code.
• Recurrence expansion: Iterate complex RRULEs (including BYSETPOS, YEARLY) via RRuleIterator to render future instances for calendars or reminders:

  $iterator = new RRuleIterator($event->RRULE, $event->DTSTART->getDateTime());
  foreach ($iterator->getOccurrencesBetween($start, $end) as $occurrence) {
      // Render or process each instance
  }
  

• Timezone-aware parsing: When handling scheduling, use Reader::read($data, Reader::OPTION_IGNORE_INVALID_LINES | Reader::OPTION_FORGIVING) to safely parse malformed but recoverable inputs (e.g., from legacy clients).

Gotchas and Tips

• Timezone handling: Floating vs. zoned times trip many developers. Always ensure DTSTART/DTEND use the correct value type (e.g., DATE-TIME with TZID or Z). Use Broker to generate correct timezones in iTip messages.
• RRULE pitfalls: Invalid RRULEs throw InvalidDataException since v4.5.6. Validate rules before setting them (e.g., via Rrule::validate() if using custom rules).
• Property groups matter: In vCards, ensure group prefixes (e.g., item1.FN, item1.EMAIL) are preserved or stripped consistently—use getProperty('item1.FN') or rely on select() when groups are unknown.
• Performance: For large calendars, avoid loading full .ics files if you only need a date range; manually parse and skip irrelevant components. Reader::read() is forgiving but may be slower than Document::parse() for known-good data.
• Extensibility: Extend Component or Property classes to add custom properties (e.g., X-CUSTOM-REF), and use VObject\NodeList to iterate non-standard fields.
• PHP 8.1+ compatibility: Avoid passing null where scalar types are expected. Many methods now declare strict return types (e.g., xmlSerialize(): void). Upgrade to v4.5.6+ for full PHP 8.4 support.