Documentation

PDO extends AbstractBackend
in package

Application

implements SyncSupport, SubscriptionSupport, SchedulingSupport, SharingSupport

PDO CalDAV backend.

This backend is used to store calendar-data in a PDO database, such as sqlite or MySQL

Interfaces, Classes and Traits

SyncSupport: WebDAV-sync support for CalDAV backends.
SubscriptionSupport: Every CalDAV backend must at least implement this interface.
SchedulingSupport: Implementing this interface adds CalDAV Scheduling support to your caldav server, as defined in rfc6638.
SharingSupport: Adds support for sharing features to a CalDAV server.

MAX_DATE = '2038-01-01': We need to specify a max date, because we need to stop *somewhere*.
$calendarChangesTableName : string: The table name that will be used for tracking changes in calendars.
$calendarInstancesTableName : string: The table name that will be used for calendars instances.
$calendarObjectTableName : string: The table name that will be used for calendar objects.
$calendarSubscriptionsTableName : string: The table name that will be used for calendar subscriptions.
$calendarTableName : string: The table name that will be used for calendars.
$propertyMap : array<string|int, mixed>: List of CalDAV properties, and how they map to database fieldnames Add your own properties by simply adding on to this array.
$schedulingObjectTableName : string: The table name that will be used inbox items.
$subscriptionPropertyMap : array<string|int, mixed>: List of subscription properties, and how they map to database fieldnames.
$pdo : PDO: pdo.
__construct() : mixed: Creates the backend.
calendarQuery() : array<string|int, mixed>: Performs a calendar-query on the contents of this calendar.
createCalendar() : string: Creates a new calendar for a principal.
createCalendarObject() : string|null: Creates a new calendar object.
createSchedulingObject() : mixed: Creates a new scheduling object. This should land in a users' inbox.
createSubscription() : mixed: Creates a new subscription for a principal.
deleteCalendar() : mixed: Delete a calendar and all it's objects.
deleteCalendarObject() : mixed: Deletes an existing calendar object.
deleteSchedulingObject() : mixed: Deletes a scheduling object.
deleteSubscription() : mixed: Deletes a subscription.
getCalendarObject() : array<string|int, mixed>|null: Returns information from a single calendar object, based on it's object uri.
getCalendarObjectByUID() : string|null: Searches through all of a users calendars and calendar objects to find an object with a specific UID.
getCalendarObjects() : array<string|int, mixed>: Returns all calendar objects within a calendar.
getCalendarsForUser() : array<string|int, mixed>: Returns a list of calendars for a principal.
getChangesForCalendar() : array<string|int, mixed>: The getChanges method returns all the changes that have happened, since the specified syncToken in the specified calendar.
getInvites() : array<string|int, Sharee>: Returns the list of people whom a calendar is shared with.
getMultipleCalendarObjects() : array<string|int, mixed>: Returns a list of calendar objects.
getSchedulingObject() : array<string|int, mixed>: Returns a single scheduling object.
getSchedulingObjects() : array<string|int, mixed>: Returns all scheduling objects for the inbox collection.
getSubscriptionsForUser() : array<string|int, mixed>: Returns a list of subscriptions for a principal.
setPublishStatus() : mixed: Publishes a calendar.
updateCalendar() : mixed: Updates properties for a calendar.
updateCalendarObject() : string|null: Updates an existing calendarobject, based on it's uri.
updateInvites() : mixed: Updates the list of shares.
updateSubscription() : mixed: Updates a subscription.
addChange() : mixed: Adds a change record to the calendarchanges table.
getDenormalizedData() : array<string|int, mixed>: Parses some information from calendar objects, used for optimized calendar-queries.
validateFilterForObject() : bool: This method validates if a filter (as passed to calendarQuery) matches the given object.

MAX_DATE

We need to specify a max date, because we need to stop *somewhere*.


    public
    mixed
    MAX_DATE
    = '2038-01-01'

On 32 bit system the maximum for a signed integer is 2147483647, so MAX_DATE cannot be higher than date('Y-m-d', 2147483647) which results in 2038-01-19 to avoid problems when the date is converted to a unix timestamp.

$calendarChangesTableName

The table name that will be used for tracking changes in calendars.


    public
        string
    $calendarChangesTableName
     = 'calendarchanges'

$calendarInstancesTableName

The table name that will be used for calendars instances.


    public
        string
    $calendarInstancesTableName
     = 'calendarinstances'

A single calendar can have multiple instances, if the calendar is shared.

$calendarObjectTableName

The table name that will be used for calendar objects.


    public
        string
    $calendarObjectTableName
     = 'calendarobjects'

$calendarSubscriptionsTableName

The table name that will be used for calendar subscriptions.


    public
        string
    $calendarSubscriptionsTableName
     = 'calendarsubscriptions'

$calendarTableName

The table name that will be used for calendars.


    public
        string
    $calendarTableName
     = 'calendars'

$propertyMap

List of CalDAV properties, and how they map to database fieldnames Add your own properties by simply adding on to this array.


    public
        array<string|int, mixed>
    $propertyMap
     = ['{DAV:}displayname' => 'displayname', '{urn:ietf:params:xml:ns:caldav}calendar-description' => 'description', '{urn:ietf:params:xml:ns:caldav}calendar-timezone' => 'timezone', '{http://apple.com/ns/ical/}calendar-order' => 'calendarorder', '{http://apple.com/ns/ical/}calendar-color' => 'calendarcolor']

Note that only string-based properties are supported here.

$schedulingObjectTableName

The table name that will be used inbox items.


    public
        string
    $schedulingObjectTableName
     = 'schedulingobjects'

$subscriptionPropertyMap

List of subscription properties, and how they map to database fieldnames.


    public
        array<string|int, mixed>
    $subscriptionPropertyMap
     = ['{DAV:}displayname' => 'displayname', '{http://apple.com/ns/ical/}refreshrate' => 'refreshrate', '{http://apple.com/ns/ical/}calendar-order' => 'calendarorder', '{http://apple.com/ns/ical/}calendar-color' => 'calendarcolor', '{http://calendarserver.org/ns/}subscribed-strip-todos' => 'striptodos', '{http://calendarserver.org/ns/}subscribed-strip-alarms' => 'stripalarms', '{http://calendarserver.org/ns/}subscribed-strip-attachments' => 'stripattachments']

$pdo

pdo.


    protected
        PDO
    $pdo

__construct()

Creates the backend.


    public
                __construct(PDO $pdo) : mixed

Parameters

$pdo : PDO

Return values

mixed —

calendarQuery()

Performs a calendar-query on the contents of this calendar.


    public
                calendarQuery(mixed $calendarId, array<string|int, mixed> $filters) : array<string|int, mixed>

The calendar-query is defined in RFC4791 : CalDAV. Using the calendar-query it is possible for a client to request a specific set of object, based on contents of iCalendar properties, date-ranges and iCalendar component types (VTODO, VEVENT).

This method should just return a list of (relative) urls that match this query.

The list of filters are specified as an array. The exact array is documented by \Sabre\CalDAV\CalendarQueryParser.

Note that it is extremely likely that getCalendarObject for every path returned from this method will be called almost immediately after. You may want to anticipate this to speed up these requests.

This method provides a default implementation, which parses all the iCalendar objects in the specified calendar.

This default may well be good enough for personal use, and calendars that aren't very large. But if you anticipate high usage, big calendars or high loads, you are strongly adviced to optimize certain paths.

The best way to do so is override this method and to optimize specifically for 'common filters'.

Requests that are extremely common are:

requests for just VEVENTS
requests for just VTODO
requests with a time-range-filter on a VEVENT.

..and combinations of these requests. It may not be worth it to try to handle every possible situation and just rely on the (relatively easy to use) CalendarQueryValidator to handle the rest.

Note that especially time-range-filters may be difficult to parse. A time-range filter specified on a VEVENT must for instance also handle recurrence rules correctly. A good example of how to interpret all these filters can also simply be found in \Sabre\CalDAV\CalendarQueryFilter. This class is as correct as possible, so it gives you a good idea on what type of stuff you need to think of.

This specific implementation (for the PDO) backend optimizes filters on specific components, and VEVENT time-ranges.

Parameters

$calendarId : mixed
$filters : array<string|int, mixed>

Return values

array<string|int, mixed> —

createCalendar()

Creates a new calendar for a principal.


    public
                createCalendar(string $principalUri, string $calendarUri, array<string|int, mixed> $properties) : string

If the creation was a success, an id must be returned that can be used to reference this calendar in other methods, such as updateCalendar.

Parameters

$principalUri : string
$calendarUri : string
$properties : array<string|int, mixed>

Return values

string —

createCalendarObject()

Creates a new calendar object.


    public
                createCalendarObject(mixed $calendarId, string $objectUri, string $calendarData) : string|null

The object uri is only the basename, or filename and not a full path.

It is possible return an etag from this function, which will be used in the response to this PUT request. Note that the ETag must be surrounded by double-quotes.

However, you should only really return this ETag if you don't mangle the calendar-data. If the result of a subsequent GET to this object is not the exact same as this request body, you should omit the ETag.

Parameters

$calendarId : mixed
$objectUri : string
$calendarData : string

Return values

string|null —

createSchedulingObject()

Creates a new scheduling object. This should land in a users' inbox.


    public
                createSchedulingObject(string $principalUri, string $objectUri, string|resource $objectData) : mixed

Parameters

$principalUri : string
$objectUri : string
$objectData : string|resource

Return values

mixed —

createSubscription()

Creates a new subscription for a principal.


    public
                createSubscription(string $principalUri, string $uri, array<string|int, mixed> $properties) : mixed

If the creation was a success, an id must be returned that can be used to reference this subscription in other methods, such as updateSubscription.

Parameters

$principalUri : string
$uri : string
$properties : array<string|int, mixed>

Return values

mixed —

deleteCalendar()

Delete a calendar and all it's objects.


    public
                deleteCalendar(mixed $calendarId) : mixed

Parameters

$calendarId : mixed

Return values

mixed —

deleteCalendarObject()

Deletes an existing calendar object.


    public
                deleteCalendarObject(mixed $calendarId, string $objectUri) : mixed

The object uri is only the basename, or filename and not a full path.

Parameters

$calendarId : mixed
$objectUri : string

Return values

mixed —

deleteSchedulingObject()

Deletes a scheduling object.


    public
                deleteSchedulingObject(string $principalUri, string $objectUri) : mixed

Parameters

$principalUri : string
$objectUri : string

Return values

mixed —

deleteSubscription()

Deletes a subscription.


    public
                deleteSubscription(mixed $subscriptionId) : mixed

Parameters

$subscriptionId : mixed

Return values

mixed —

getCalendarObject()

Returns information from a single calendar object, based on it's object uri.


    public
                getCalendarObject(mixed $calendarId, string $objectUri) : array<string|int, mixed>|null

The object uri is only the basename, or filename and not a full path.

The returned array must have the same keys as getCalendarObjects. The 'calendardata' object is required here though, while it's not required for getCalendarObjects.

This method must return null if the object did not exist.

Parameters

$calendarId : mixed
$objectUri : string

Return values

array<string|int, mixed>|null —

getCalendarObjectByUID()

Searches through all of a users calendars and calendar objects to find an object with a specific UID.


    public
                getCalendarObjectByUID(string $principalUri, string $uid) : string|null

This method should return the path to this object, relative to the calendar home, so this path usually only contains two parts:

calendarpath/objectpath.ics

If the uid is not found, return null.

This method should only consider * objects that the principal owns, so any calendars owned by other principals that also appear in this collection should be ignored.

Parameters

$principalUri : string
$uid : string

Return values

string|null —

getCalendarObjects()

Returns all calendar objects within a calendar.


    public
                getCalendarObjects(mixed $calendarId) : array<string|int, mixed>

Every item contains an array with the following keys:

calendardata - The iCalendar-compatible calendar data
uri - a unique key which will be used to construct the uri. This can be any arbitrary string, but making sure it ends with '.ics' is a good idea. This is only the basename, or filename, not the full path.
lastmodified - a timestamp of the last modification time
etag - An arbitrary string, surrounded by double-quotes. (e.g.: ' "abcdef"')
size - The size of the calendar objects, in bytes.
component - optional, a string containing the type of object, such as 'vevent' or 'vtodo'. If specified, this will be used to populate the Content-Type header.

Note that the etag is optional, but it's highly encouraged to return for speed reasons.

The calendardata is also optional. If it's not returned 'getCalendarObject' will be called later, which is expected to return calendardata.

If neither etag or size are specified, the calendardata will be used/fetched to determine these numbers. If both are specified the amount of times this is needed is reduced by a great degree.

Parameters

$calendarId : mixed

Return values

array<string|int, mixed> —

getCalendarsForUser()

Returns a list of calendars for a principal.


    public
                getCalendarsForUser(string $principalUri) : array<string|int, mixed>

Every project is an array with the following keys:

id, a unique id that will be used by other functions to modify the calendar. This can be the same as the uri or a database key.
uri. This is just the 'base uri' or 'filename' of the calendar.
principaluri. The owner of the calendar. Almost always the same as principalUri passed to this method.

Furthermore it can contain webdav properties in clark notation. A very common one is '{DAV:}displayname'.

Many clients also require: {urn:ietf:params:xml:ns:caldav}supported-calendar-component-set For this property, you can just return an instance of Sabre\CalDAV\Xml\Property\SupportedCalendarComponentSet.

If you return {http://sabredav.org/ns}read-only and set the value to 1, ACL will automatically be put in read-only mode.

Parameters

$principalUri : string

Return values

array<string|int, mixed> —

getChangesForCalendar()

The getChanges method returns all the changes that have happened, since the specified syncToken in the specified calendar.


    public
                getChangesForCalendar(mixed $calendarId, string $syncToken, int $syncLevel[, int $limit = null ]) : array<string|int, mixed>

This function should return an array, such as the following:

[ 'syncToken' => 'The current synctoken', 'added' => [ 'new.txt', ], 'modified' => [ 'modified.txt', ], 'deleted' => [ 'foo.php.bak', 'old.txt' ] ];

The returned syncToken property should reflect the current syncToken of the calendar, as reported in the {http://sabredav.org/ns}sync-token property this is needed here too, to ensure the operation is atomic.

If the $syncToken argument is specified as null, this is an initial sync, and all members should be reported.

The modified property is an array of nodenames that have changed since the last token.

The deleted property is an array with nodenames, that have been deleted from collection.

The $syncLevel argument is basically the 'depth' of the report. If it's 1, you only have to report changes that happened only directly in immediate descendants. If it's 2, it should also include changes from the nodes below the child collections. (grandchildren)

The $limit argument allows a client to specify how many results should be returned at most. If the limit is not specified, it should be treated as infinite.

If the limit (infinite or not) is higher than you're willing to return, you should throw a Sabre\DAV\Exception\TooMuchMatches() exception.

If the syncToken is expired (due to data cleanup) or unknown, you must return null.

The limit is 'suggestive'. You are free to ignore it.

Parameters

$calendarId : mixed
$syncToken : string
$syncLevel : int
$limit : int = null

Return values

array<string|int, mixed> —

getInvites()

Returns the list of people whom a calendar is shared with.


    public
                getInvites(mixed $calendarId) : array<string|int, Sharee>

Every item in the returned list must be a Sharee object with at least the following properties set: $href $shareAccess $inviteStatus

and optionally: $properties

Parameters

$calendarId : mixed

Return values

array<string|int, Sharee> —

getMultipleCalendarObjects()

Returns a list of calendar objects.


    public
                getMultipleCalendarObjects(mixed $calendarId, array<string|int, mixed> $uris) : array<string|int, mixed>

This method should work identical to getCalendarObject, but instead return all the calendar objects in the list as an array.

If the backend supports this, it may allow for some speed-ups.

Parameters

$calendarId : mixed
$uris : array<string|int, mixed>

Return values

array<string|int, mixed> —

getSchedulingObject()

Returns a single scheduling object.


    public
                getSchedulingObject(string $principalUri, string $objectUri) : array<string|int, mixed>

The returned array should contain the following elements:

uri - A unique basename for the object. This will be used to construct a full uri.
calendardata - The iCalendar object
lastmodified - The last modification date. Can be an int for a unix timestamp, or a PHP DateTime object.
etag - A unique token that must change if the object changed.
size - The size of the object, in bytes.

Parameters

$principalUri : string
$objectUri : string

Return values

array<string|int, mixed> —

getSchedulingObjects()

Returns all scheduling objects for the inbox collection.


    public
                getSchedulingObjects(string $principalUri) : array<string|int, mixed>

These objects should be returned as an array. Every item in the array should follow the same structure as returned from getSchedulingObject.

The main difference is that 'calendardata' is optional.

Parameters

$principalUri : string

Return values

array<string|int, mixed> —

getSubscriptionsForUser()

Returns a list of subscriptions for a principal.


    public
                getSubscriptionsForUser(string $principalUri) : array<string|int, mixed>

Every subscription is an array with the following keys:

id, a unique id that will be used by other functions to modify the subscription. This can be the same as the uri or a database key.
uri. This is just the 'base uri' or 'filename' of the subscription.
principaluri. The owner of the subscription. Almost always the same as principalUri passed to this method.
source. Url to the actual feed

Furthermore, all the subscription info must be returned too:

{DAV:}displayname
{http://apple.com/ns/ical/}refreshrate
{http://calendarserver.org/ns/}subscribed-strip-todos (omit if todos should not be stripped).
{http://calendarserver.org/ns/}subscribed-strip-alarms (omit if alarms should not be stripped).
{http://calendarserver.org/ns/}subscribed-strip-attachments (omit if attachments should not be stripped).
{http://apple.com/ns/ical/}calendar-color
{http://apple.com/ns/ical/}calendar-order
{urn:ietf:params:xml:ns:caldav}supported-calendar-component-set (should just be an instance of Sabre\CalDAV\Property\SupportedCalendarComponentSet, with a bunch of default components).

Parameters

$principalUri : string

Return values

array<string|int, mixed> —

setPublishStatus()

Publishes a calendar.


    public
                setPublishStatus(mixed $calendarId, bool $value) : mixed

Parameters

$calendarId : mixed
$value : bool

Return values

mixed —

updateCalendar()

Updates properties for a calendar.


    public
                updateCalendar(mixed $calendarId, PropPatch $propPatch) : mixed

The list of mutations is stored in a Sabre\DAV\PropPatch object. To do the actual updates, you must tell this object which properties you're going to process with the handle() method.

Calling the handle method is like telling the PropPatch object "I promise I can handle updating this property".

Read the PropPatch documentation for more info and examples.

Parameters

$calendarId : mixed
$propPatch : PropPatch

Return values

mixed —

updateCalendarObject()

Updates an existing calendarobject, based on it's uri.


    public
                updateCalendarObject(mixed $calendarId, string $objectUri, string $calendarData) : string|null

The object uri is only the basename, or filename and not a full path.

It is possible return an etag from this function, which will be used in the response to this PUT request. Note that the ETag must be surrounded by double-quotes.

Parameters

$calendarId : mixed
$objectUri : string
$calendarData : string

Return values

string|null —

updateInvites()

Updates the list of shares.


    public
                updateInvites(mixed $calendarId, array<string|int, Sharee> $sharees) : mixed

Parameters

$calendarId : mixed
$sharees : array<string|int, Sharee>

Return values

mixed —

updateSubscription()

Updates a subscription.


    public
                updateSubscription(mixed $subscriptionId, PropPatch $propPatch) : mixed

The list of mutations is stored in a Sabre\DAV\PropPatch object. To do the actual updates, you must tell this object which properties you're going to process with the handle() method.

Calling the handle method is like telling the PropPatch object "I promise I can handle updating this property".

Read the PropPatch documentation for more info and examples.

Parameters

$subscriptionId : mixed
$propPatch : PropPatch

Return values

mixed —

addChange()

Adds a change record to the calendarchanges table.


    protected
                addChange(mixed $calendarId, string $objectUri, int $operation) : mixed

Parameters

$calendarId : mixed
$objectUri : string
$operation : int: 1 = add, 2 = modify, 3 = delete

Return values

mixed —

getDenormalizedData()

Parses some information from calendar objects, used for optimized calendar-queries.


    protected
                getDenormalizedData(string $calendarData) : array<string|int, mixed>

Returns an array with the following keys:

etag - An md5 checksum of the object without the quotes.
size - Size of the object in bytes
componentType - VEVENT, VTODO or VJOURNAL
firstOccurence
lastOccurence
uid - value of the UID property

Parameters

$calendarData : string

Return values

array<string|int, mixed> —

validateFilterForObject()

This method validates if a filter (as passed to calendarQuery) matches the given object.


    protected
                validateFilterForObject(array<string|int, mixed> $object, array<string|int, mixed> $filters) : bool

Parameters

$object : array<string|int, mixed>
$filters : array<string|int, mixed>

Return values

bool —