Sabre VObject 3 released
I just released version 3 of the sabre/vobject library. The ultimate library for parsing and manipulating vCard and iCalendar files in PHP (I hope!).
The library started off as component of SabreDAV, but it’s actually become more popular than it’s parent project.
It’s been an interesting project for me. SabreDAV is my main other open source project at fruux, and that project has a really strong focus on a proper OOP design and structure.
With vobject, the focus has been on providing as convenient API as possible and follows the “api over implementation” mantra. For me this means that the experience for the user is the most important, but if you pop open the hood it can turn out to be a bit messy.
This is especially true because I’m supporting:
- iCalendar 2.0
- vCard 2.1
- vCard 3.0
- vCard 4.0
And while each of those formats look quite similar on the surface, each has their own set of rules for encoding, and a lot of edge-cases.
I admit to not having dug into that enough when I originally created the library, and I was required to rewrite huge portions of it and break BC just to properly support everything. Hence: 3.0.
A mini tutorial
Reading a vCard:
<?php use Sabre\VObject\Reader; $card = Reader::read('contact.vcf'); echo (string)$card->FN; ?>
Creating an iCalendar object:
<?php use Sabre\VObject\Component\VCalendar; $cal = new VCalendar(); $cal->add('VEVENT', [ 'summary' => 'Birthday party', 'dtstart' => new DateTime('2014-07-04 22:00:00'), 'categories' => ['party!', 'byob'], ]); echo $cal->serialize(); ?>
This will output something like:
BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Sabre//Sabre VObject 3.0.0//EN CALSCALE:GREGORIAN BEGIN:VEVENT SUMMARY:Birthday party DTSTART;TZID=Europe/London:20140704T220000 CATEGORIES:party!,byob END:VEVENT END:VCALENDAR
Check out the documentation for everything else, there’s quite a bit :).
- We’re now following all the escaping rules from vCard 2.1, 3.0, 4.0, iCalendar 2.0 and rfc6868.
- Support for exporting jCal and jCard formats, which are json representations of this format, and soon to be official RFC’s.
- Easily create multi-valued properties using arrays.
- Great vCard 2.1 support, including the broken vCards microsoft generates.
- It’s much easier to create components such as VEVENT, VTODO.
- Stream-based parser.
- Almost every property type got specialized API’s to easily deal with them. For instance, you can now simply create date-time-related properties by just setting a native PHP DateTime object.
- Added a remove() method to components.
- iCalendar and vCard objects are automatically initialized with common default properties.
Some BC breaks were required, read the migration document to find out how to upgrade.
Information for SabreDAV users
VObject 3.0 will be included in the next major release of SabreDAV. SabreDAV 1.7.x and 1.8.x will continue to ship with vObject 2 to avoid BC breaks.
However, both those branches have been modified so they can run with either vObject 2 or 3. So if you do need the new features and improvements, you can just drop it in.
A few people have been especially helpful in testing, criticising and thinking along:
Thanks guys! You rock.