Upgrading from SabreDAV 2.0 to 2.1

sabre/dav 2.1 has a number of new features, and as usual, a number of backwards compatibility breaks.

This page lists them all.

New features

To read the full list of changes (there's quite a few!) read the changelogs:

API Changes and BC breaks

Database structure changes

If you use the default PDO backend for CalDAV, you need to migrate to the latest database structure.

Before you start the migration process, please make a backup first! No warranty is given for lost data.

To run the database upgrade, simply start ./bin/migrate21.php from the SabreDAV project. This script will give you more information about its arguments.

CalDAV backends have a new method

Every CalDAV backend must now implement a new method: getCalendarObjectByUID. If you are not using the default PDO backend, but created a custom backend, you must add support for this new method.

If you extended Sabre\CalDAV\Backend\AbstractBackend, a fallback method has been provided. This method works, but it's very slow. For most backends it's possible to optimize this quite a bit.

Note that this is mainly used for Scheduling support.

Renamed classes

We have renamed a few classes:

  1. Sabre\CalDAV\CalendarRootNode is renamed to Sabre\CalDAV\CalendarRoot.
  2. Sabre\CalDAV\UserCalendars is renamed to Sabre\CalDAV\CalendarHome

The classes behave the same. The old classes still exist, but will be removed in sabre/dav 3.0. If you instantiated any of these classes, make sure you use the new names.

The iMipHandler has been removed

The imipHandler has been removed entirely. This class was used in the past to work around an iCal bug.

This bug no longer exists when a CalDAV server supports scheduling, so we've also removed the workaround.

A part of its functionality was to send out email invites. This functionality has been replaced by a new iMip plugin. The benefit of this plugin, is that it works for every caldav client, and not just broken iCal versions.

Support for free-busy reports has moved to a new plugin

sabre/dav supported a 'freebusy' report for a long time. This report was used by several clients, but was actually part of the scheduling specification.

Now we've fully implemented support for scheduling, and so we've also moved the freebusy functionality.

If you need it back, make sure you enable the scheduling plugin in your server:

$server->addPlugin(new Sabre\CalDAV\Schedule\Plugin());

Support for notifications has moved to a new plugin

If you wrote a CalDAV backend that supports notifications (for share invites and replies), you need to now explicitly turn on a plugin for this to work.

Before this was just part of the CalDAV plugin, but this meant that this extra functionality was enabled, and not used for most users.

If you need it back, make sure you enable the notifications plugin in your server:

$server->addPlugin(new Sabre\CalDAV\Notifications\Plugin());

vCards now return a different content-type.

When doing a GET request on a vCard, we always returned the following header:

Content-Type: text/x-vcard; charset=utf-8

This was wrong. We've changed it to:

Content-Type: text/vcard; charset=utf-8

If you relied on the old behavior, make sure you update this.

Updating table names in PDO backends now work differently

A few people always found it important to use their own table names for the various PDO backends, one major reason is that this would allow people to prefix all their table names with for example sabre_.

This was always done by allowing people to set the various database table names in the constructors of the various PDO backends.

This is now deprecated!

Instead you must now set the table names as public properties. The old way using arguments still works, but will be removed in version 3.0.

Affected PDO backends:

PropertyStorage classes now have a move method.

If you implemented your own Sabre\DAV\PropertyStorage\Backend class, you must now implement the new move method.

The propertystorage system allows a client to store any arbitrary property on any resource.

One problem with this system was that it didn't handle MOVE requests correctly. If a MOVE is done on a resource, any dead properties must also be moved with it.

The new move method will be called when a HTTP MOVE is done, and allows you to re-assign all the properties to the new location.

Principal backends now have a findByUri method

If you implemented your own PrincipalBackend class, you must now implement the findByUri method as well.

This method takes some kind of URI, such as a mailto: address, and returns a local principal url.

This is used by CalDAV scheduling to deliver invites and replies to the right user inbox.

It's possible to just return null from this method, but this will prevent local invite delivery.

ObjectTree and Tree\FileSystem classes have been removed

The Sabre\DAV\ObjectTree and Sabre\DAV\Tree\FileSystem classes both extended Sabre\DAV\Tree.

This particular extension point was very rarely used. The main reason to extend either of these classes, was to make MOVE operations faster.

Since 2.1, both of these classes are removed. Functionality from ObjectTree has been merged into Sabre\DAV\Tree, which is no longer abstract.

Usually there is no need to instantiate this class directly, as it's also created by Sabre\DAV\Server, but if you did use this extension point for optimizing moves, we now recommend to implement Sabre\DAV\IMoveTarget in your Collection classes instead.

sabre/http changes

The sabre/http package has been upgraded to version 3.0. Several BC breaking changes have been made, specifically in how methods related to HTTP headers work.

If you ever used Sabre\HTTP\Request or Sabre\HTTP\Response objects, you should make sure that it still works with the new behavior.

For more details, read the blogpost.

New ZIP structure

The zip distribution now has a new directory structure. Before a part of the source was in the lib/ directory, and another part in the vendor/ directory.

We've now combined everything in the vendor/ directory. If you used the composer autoloader (in vendor/autoload.php) you don't have to change a thing, but if you rolled your own autoloading mechanism, you may need to revise this.