Migrating from 1.5 to 1.6

To keep a clean codebase, and not one that's stuck in the past compatbility breaks are needed.

1.6 is leap forward in a number of areas, so as a result there are also an number of breaks.

If for some reason you cannot upgrade to 1.6, 1.5 will be maintained for as long as there's demand.

This document describes the breaks. Items in this list are ordered by how likely you are to be affected by it. Every section starts with a paragraph explaining why it would be relevant to you.

But we'll start with the good news.

New features

We just released SabreDAV 1.6.0. This version contains a bunch of new features, and a ton of "under the hood" changes. It is fair to say that this release has seen the most effort yet.

The main changes are:

• SabreDAV now requires PHP 5.3
• SabreDAV is now a composer package. Check out http://getcomposer.org/ to find out what that means.
• Support for 'make this my card' in OS/X Addressbook.app.
• Support for the 'free-busy-query' report. This allows people with support clients to find out if other users are available for meetings. Note that this is not the same feature used by iCal to show free-busy reports. The report iCal uses will be added in a later version.
• Correct support for the calendar-query filter (now takes recurring events into consideration), as well as expanding of events.
• SabreDAV now contains functionality to send emails for events, such as inviting, accepting an event, declining an event and deleting an event. To use this, you must setup the IMipHandler. This feature is only used by iCal, because it wrongly assumed that the server would handle emails, even when the server doesn't advertise for this feature. So using this feature is a workaround to invitation bugs in iCal.
• A ton of improvements in the Browser plugin. This should make it easier to perform some management tasks, such as adding calendars and addressbooks.
• Support for adminstrators. If you add principal-urls to Sabre_DAVACL_Plugin::$adminPrincipals, these principals will receive every permission, everywhere.
• Improvements in Sabre_VObject to aid with parsing complex iCalendar data, such as recurrence and turning a regular iCalendar file into a FREEBUSY report.

A big release like this also means that there's a fair number of compatibility breaks, which may especially affect you if you customized your SabreDAV setup.

Read the full Changelog for more details.

SabreDAV now requires PHP 5.3

There are a number of features that depend on functionality that has been introduced with PHP 5.3. Among these items are the DateTime-related additions and closures.

If your system runs an older version than 5.2, you must stick with the SabreDAV 1.5. versions. 1.5. will still be actively maintained, but will not receive any new features.

Database changes

If you use Sabre_DAVACL_PrincipalBackend_PDO or have a 'principals' table, you must run the following script to keep it compatible:

-- MySQL
ALTER TABLE principals ADD vcardurl VARCHAR(80);

-- SQLite
ALTER TABLE principals ADD vcardurl TEXT;

This new field stores a url to a vcard associated with a specific principal. This enables the "Make this My Card" feature in OS/X's Addressbook.

If you're authenticated, you can read other people\'s FREE-BUSY information

Since 1.6 support for the 'freebusy' report is added. The default that was added was to give any use who's authenticated, access to these reports.

So although no calendars are shared, it is shared when people have events scheduled at certain times.

lib/Sabre.includes.php is deprecated

Every package now has a specific includes file:

• Sabre/HTTP/includes.php
• Sabre/DAV/includes.php
• Sabre/VObject/includes.php
• Sabre/DAVACL/includes.php
• Sabre/CalDAV/includes.php
• Sabre/CardDAV/includes.php

The 'old' includes file only includes the first two items. In 1.7 this includes file will be removed.

Sabre_DAV_Exception_FileNotFound is now Sabre_DAV_Exception_NotFound

We renamed this exception because it makes more sense. The FileNotFound exception still exists, but it extends 'NotFound'.

The old exception will be removed in version 1.7.

Sabre_CalDAV_Server is deprecated

This class always kind of served as an example class to implement custom server classes, and was intentionally inflexible. In 1.6 this is is marked as deprecated, and it will be removed in 1.7.

To fix this, we suggest users to simply copy the old class, and change the class name. If you don't want to do this, take a look at the "calendarserver.php" file in the examples/ directory. This file contains a full explanation of how to setup a calendar server.

Sabre_DAVACL_IPrincipalBackend has new methods

The Sabre_DAVACL_IPrincipalBackend interface now has two new methods:

• updatePrincipal
• searchPrincipals

Refer to the interface for documentation about these two new methods. This may also apply to you if you extend Sabre_DAVACL_PrincipalBackend_PDO.

Removed Sabre_DAV_ILockable

Before 1.6 it was possible to implement locking-functionality directly in nodes, by implementing Sabre_DAV_ILockable. This was found to be problematic and barely used, so this functionality is completely removed.

If you relied on this feature, you have no ther option but to migrate your custom implementation to a Sabre_DAV_Locks_Backend_Abstract-based class.

If you have trouble with this, head over to the mailing list, we're we'll gladly figure out a solution for your use-case.

Validation of iCalendar objects no longer happens in Sabre_CalDAV_Calendar

A syntax check of iCalendar objects used to be done in:

• Sabre_CalDAV_Calendar::createFile and
• Sabre_CalDAV_CalendarObject::put

This functionality has been moved to Sabre_CalDAV_Plugin. The new check is a bit more strict, so this should be very helpful to reduce corruption of data.

Added method to Sabre_DAVACL_IACL interface

If you implemented Sabre_DAVACL_IACL directly, you must now also implement a getSupportedPrivilegeSet method. This method allows you to specify a custom set of priviliges per node.

To simply retain the old behaviour, you can simply return null. This will cause the default permission set to kick in.

Removed classes in CalDAV plugin

• Sabre_CalDAV_ICalendarUtil contained functions to validate iCalendar objects, as well as a utility to convert iCalendar objects to a simple xml format. Neither was needed anymore, and both were poorly implemented. All this type of functionality is now going to the Sabre_VObject package, but there's no alternative to convert to the xml format.
• Sabre_CalDAV_XMLUtil contained various functions to parse iCalendar dates, as well as certain CalDAV requests. This functionality has also all been moved to the VObject package. If you just want to parse iCalendar dates, take a look at Sabre_VObject_DateTimeParser.
• Sabre_CalDAV_Exception_InvalidICalendarObject was removed as well.

Renamed some VObject classes

• Sabre_VObject_Element_MultiDateTime is now Sabre_VObject_Property_MultiDateTime
• Sabre_VObject_Element_DateTime is now Sabre_VObject_Property_DateTime

The old classes still exist, and still work but will be removed in a future version.

calendars/username now contains an outbox node

The calendars/username collection always listed just the users' calendars. Now it also contains an 'outbox', which is currently used by iCal to send event invitations. In the future this outbox will be used more heavily to support other scheduling-related features.