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:
- A lot of REPORT queries got a lot faster. Especially some CalDAV-related requests can be exponentially faster. Some larger operations sped up from several minutes, to several seconds.
- The VObject library has spun off into a separate project: sabre/vobject.
- Experimental support for caldav-sharing and caldav-notifications.
- Added a vcard export plugin, similar to the iCalendar export plugin.
- Added a bunch of free-busy reports that now make it possible for iCal to use them.
- Added support for a PATCH format.
- Switched to using the Composer autoloader.
- Stronger validation of both iCalendar and vCard files.
- Support for
Brief
andPrefer: return-minimal
headers.
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:
lib/Sabre/HTTP/includes.php
lib/Sabre/DAV/includes.php
lib/Sabre/VObject/includes.php
lib/Sabre/CalDAV/includes.php
lib/Sabre/CardDAV/includes.php
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.