Upgrading from SabreDAV 1.5 to 1.6
To keep a clean codebase, and not one that's stuck in the past, compatibility breaks are needed.
1.6 is leap forward in a number of areas, so as a result, there are also a 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 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 administrators. 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 Sabre_DAV_Exception_FileNotFound
exception still exists, but
it extends Sabre_DAV_Exception_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 other 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
andSabre_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 privileges 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 atSabre_VObject_DateTimeParser
.Sabre_CalDAV_Exception_InvalidICalendarObject
was removed as well.
Renamed some VObject classes
Sabre_VObject_Element_MultiDateTime
is nowSabre_VObject_Property_MultiDateTime
Sabre_VObject_Element_DateTime
is nowSabre_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.