Upgrading from SabreDAV 1.6 to 1.7

SabreDAV 1.7 is released, and as usual this brings a couple of changes to the table. If you are migrating from SabreDAV 1.6, this document is for you!

We make a conscious decision to always break a few API's we are unhappy with, so we don't get stuck in the past.

This time around there's a fairly significant list of changes. The sections below are ordered by how likely you will come across an issue.

If upgrading from 1.6 makes you uncomfortable, we will keep maintaining the 1.6 branch for 12 months.

New features

First the good news:

API breaks

Default CalDAV MySQL/SqLite backend needs upgrade

In order to make the CalDAV backend faster, it was needed to add a few more database fields. These fields ensure that the heavier CalDAV queries are indexable.

A migration script has been included in the distribution, it can be found in bin/migrate17.php.

Note that if you use non-default table names, or a custom CalDAV backend, this script will not work!

You should make absolutely sure that a backup of your database is created first. No warranty is provided, although both SQLite and MySQL have been tested.

To get information about how to call the script, simply run it:

php bin/migrate17.php

This will display a help screen.

Composer package name changed

This only applies to you, if you installed sabredav using 'composer'.

Starting 1.7, the composer package name is no longer 'evert/sabredav', but 'sabre/dav'. The best way to migrate, is to remove the old package completely, and then re-install 'sabre/dav'.

Now using composer for autoloading

The autoloader in lib/Sabre/autoload.php is now deprecated, and will be removed in a future version of sabredav.

Instead, you should include vendor/autoload.php.

VObject library moved to a separate package and now uses namespaces

The VObject library was useful enough to spawn into a separate project. One of the major things that changed in this library, is that PHP 5.3 namespaces are now used throughout.

This means that wherever in your code you used:

Sabre_VObject_Reader::read($str);

The correct syntax would now be:

\Sabre\VObject\Reader::read($str);

Or:

use Sabre\VObject;

VObject\Reader::read($str);

This applies to all VObject classes.

Moving it into a separate project has another effect. Even though the VObject library is still included in the zip, the sourcecode can now be found under:

vendor/sabre/vobject

This directory structure is automatically generated by composer. The required composer files are included in the zip distribution.

Note that the move to namespaces is indeed a sign of things to come for SabreDAV itself as well. In a next version SabreDAV will fully switch to namespaces.

PEAR packages are now deprecated

For those 3 people who still used this, from this point forward, the pear packages will no longer be created. They will be for the 1.6 range of packages.

Sabre_CalDAV_Server has been removed

This only applies to you if you used this class.

The Sabre_CalDAV_Server script had already been deprecated for some time, but it has now been fully removed.

The original intention was to show it as an example of how to extend Sabre_DAV_Server, but as feature requests came in for more flexibility, the best course of action was to simply remove it altogether.

For an alternative way to setup your CalDAV server, have a look at the examples directory.

lib/Sabre.includes.php has been removed

The lib/Sabre.includes.php was deprecated earlier, and has now been removed from the SabreDAV distribution. Every individual package does still have an includes file, so if you prefer this way of loading in PHP files, use:

CalDAV Backend API design

This only applies to you if you created a custom CalDAV backend. If you use the default PDO class, you can skip this section.

In SabreDAV 1.6 the backend base class for backends was Sabre_CalDAV_Backend_Abstract. While this class still exists, it not implements the Sabre_CalDAV_Backend_BackendInterface interface.

The interface, and abstract class now have a new method: calendarQuery. This method is called for the caldav-query REPORT and free-busy operations.

You must implement this. However, Sabre_CalDAV_Backend_Abstract has a default implementation.

If you're having performance issues with these operations, it's recommended to override the default calendarQuery method. The PDO backend does this to optimize common queries.

Removed Sabre_DAV_Directory and Sabre_DAV_SimpleDirectory

If you still used either of these classes, you should now use Sabre_DAV_Collection and Sabre_DAV_SimpleCollection.

urn:DAV is no longer used

This only applies to you, if you ever used 'urn:DAV' in your code as an xml namespace.

In the past the PHP xml parser had a bug, that prevented us from using 'DAV:' as an xml namespace. To work around this, a pre-processor changed all references to this namespace into 'urn:DAV'.

This is no longer an issue in PHP 5.3, which is also the minimum required PHP version, so this workaround is now removed.

EDIT: This was re-introduced in version 1.7.4 as there were still certain setups that had issues with this. The new decision is to wait till 2015 to try and take this out again.

Sabre_CalDAV_Schedule_IMip has been slightly modified

This only applies to you, if you subclassed Sabre_CalDAV_Schedule_IMip.

The sendMessage method in Sabre_CalDAV_Schedule_IMip now has an extra argument. If you extend this class, be sure to add it to your implementation too.

Sabre_CalDAV_ICalendar interface now has a new method

This only applies to you, if you directly implemented Sabre_CalDAV_ICalendar.

The calendarQuery method has been added to the Sabre_CalDAV_ICalendar class. If you implemented this class directory, you must add it.

The default implementations delegate this functionality to the CalDAV backend classes. If you did indeed roll your own, you should take a look at these implementations on how to properly implement this method.