1<?php
2
3namespace Sabre\CalDAV\Backend;
4
5/**
6 * Every CalDAV backend must at least implement this interface.
7 *
8 * @copyright Copyright (C) fruux GmbH (https://fruux.com/)
9 * @author Evert Pot (http://evertpot.com/)
10 * @license http://sabre.io/license/ Modified BSD License
11 */
12interface BackendInterface {
13
14    /**
15     * Returns a list of calendars for a principal.
16     *
17     * Every project is an array with the following keys:
18     *  * id, a unique id that will be used by other functions to modify the
19     *    calendar. This can be the same as the uri or a database key.
20     *  * uri, which is the basename of the uri with which the calendar is
21     *    accessed.
22     *  * principaluri. The owner of the calendar. Almost always the same as
23     *    principalUri passed to this method.
24     *
25     * Furthermore it can contain webdav properties in clark notation. A very
26     * common one is '{DAV:}displayname'.
27     *
28     * Many clients also require:
29     * {urn:ietf:params:xml:ns:caldav}supported-calendar-component-set
30     * For this property, you can just return an instance of
31     * Sabre\CalDAV\Property\SupportedCalendarComponentSet.
32     *
33     * If you return {http://sabredav.org/ns}read-only and set the value to 1,
34     * ACL will automatically be put in read-only mode.
35     *
36     * @param string $principalUri
37     * @return array
38     */
39    function getCalendarsForUser($principalUri);
40
41    /**
42     * Creates a new calendar for a principal.
43     *
44     * If the creation was a success, an id must be returned that can be used to
45     * reference this calendar in other methods, such as updateCalendar.
46     *
47     * The id can be any type, including ints, strings, objects or array.
48     *
49     * @param string $principalUri
50     * @param string $calendarUri
51     * @param array $properties
52     * @return mixed
53     */
54    function createCalendar($principalUri, $calendarUri, array $properties);
55
56    /**
57     * Updates properties for a calendar.
58     *
59     * The list of mutations is stored in a Sabre\DAV\PropPatch object.
60     * To do the actual updates, you must tell this object which properties
61     * you're going to process with the handle() method.
62     *
63     * Calling the handle method is like telling the PropPatch object "I
64     * promise I can handle updating this property".
65     *
66     * Read the PropPatch documentation for more info and examples.
67     *
68     * @param mixed $calendarId
69     * @param \Sabre\DAV\PropPatch $propPatch
70     * @return void
71     */
72    function updateCalendar($calendarId, \Sabre\DAV\PropPatch $propPatch);
73
74    /**
75     * Delete a calendar and all its objects
76     *
77     * @param mixed $calendarId
78     * @return void
79     */
80    function deleteCalendar($calendarId);
81
82    /**
83     * Returns all calendar objects within a calendar.
84     *
85     * Every item contains an array with the following keys:
86     *   * calendardata - The iCalendar-compatible calendar data
87     *   * uri - a unique key which will be used to construct the uri. This can
88     *     be any arbitrary string, but making sure it ends with '.ics' is a
89     *     good idea. This is only the basename, or filename, not the full
90     *     path.
91     *   * lastmodified - a timestamp of the last modification time
92     *   * etag - An arbitrary string, surrounded by double-quotes. (e.g.:
93     *   '"abcdef"')
94     *   * size - The size of the calendar objects, in bytes.
95     *   * component - optional, a string containing the type of object, such
96     *     as 'vevent' or 'vtodo'. If specified, this will be used to populate
97     *     the Content-Type header.
98     *
99     * Note that the etag is optional, but it's highly encouraged to return for
100     * speed reasons.
101     *
102     * The calendardata is also optional. If it's not returned
103     * 'getCalendarObject' will be called later, which *is* expected to return
104     * calendardata.
105     *
106     * If neither etag or size are specified, the calendardata will be
107     * used/fetched to determine these numbers. If both are specified the
108     * amount of times this is needed is reduced by a great degree.
109     *
110     * @param mixed $calendarId
111     * @return array
112     */
113    function getCalendarObjects($calendarId);
114
115    /**
116     * Returns information from a single calendar object, based on it's object
117     * uri.
118     *
119     * The object uri is only the basename, or filename and not a full path.
120     *
121     * The returned array must have the same keys as getCalendarObjects. The
122     * 'calendardata' object is required here though, while it's not required
123     * for getCalendarObjects.
124     *
125     * This method must return null if the object did not exist.
126     *
127     * @param mixed $calendarId
128     * @param string $objectUri
129     * @return array|null
130     */
131    function getCalendarObject($calendarId, $objectUri);
132
133    /**
134     * Returns a list of calendar objects.
135     *
136     * This method should work identical to getCalendarObject, but instead
137     * return all the calendar objects in the list as an array.
138     *
139     * If the backend supports this, it may allow for some speed-ups.
140     *
141     * @param mixed $calendarId
142     * @param array $uris
143     * @return array
144     */
145    function getMultipleCalendarObjects($calendarId, array $uris);
146
147    /**
148     * Creates a new calendar object.
149     *
150     * The object uri is only the basename, or filename and not a full path.
151     *
152     * It is possible to return an etag from this function, which will be used
153     * in the response to this PUT request. Note that the ETag must be
154     * surrounded by double-quotes.
155     *
156     * However, you should only really return this ETag if you don't mangle the
157     * calendar-data. If the result of a subsequent GET to this object is not
158     * the exact same as this request body, you should omit the ETag.
159     *
160     * @param mixed $calendarId
161     * @param string $objectUri
162     * @param string $calendarData
163     * @return string|null
164     */
165    function createCalendarObject($calendarId, $objectUri, $calendarData);
166
167    /**
168     * Updates an existing calendarobject, based on it's uri.
169     *
170     * The object uri is only the basename, or filename and not a full path.
171     *
172     * It is possible return an etag from this function, which will be used in
173     * the response to this PUT request. Note that the ETag must be surrounded
174     * by double-quotes.
175     *
176     * However, you should only really return this ETag if you don't mangle the
177     * calendar-data. If the result of a subsequent GET to this object is not
178     * the exact same as this request body, you should omit the ETag.
179     *
180     * @param mixed $calendarId
181     * @param string $objectUri
182     * @param string $calendarData
183     * @return string|null
184     */
185    function updateCalendarObject($calendarId, $objectUri, $calendarData);
186
187    /**
188     * Deletes an existing calendar object.
189     *
190     * The object uri is only the basename, or filename and not a full path.
191     *
192     * @param mixed $calendarId
193     * @param string $objectUri
194     * @return void
195     */
196    function deleteCalendarObject($calendarId, $objectUri);
197
198    /**
199     * Performs a calendar-query on the contents of this calendar.
200     *
201     * The calendar-query is defined in RFC4791 : CalDAV. Using the
202     * calendar-query it is possible for a client to request a specific set of
203     * object, based on contents of iCalendar properties, date-ranges and
204     * iCalendar component types (VTODO, VEVENT).
205     *
206     * This method should just return a list of (relative) urls that match this
207     * query.
208     *
209     * The list of filters are specified as an array. The exact array is
210     * documented by Sabre\CalDAV\CalendarQueryParser.
211     *
212     * Note that it is extremely likely that getCalendarObject for every path
213     * returned from this method will be called almost immediately after. You
214     * may want to anticipate this to speed up these requests.
215     *
216     * This method provides a default implementation, which parses *all* the
217     * iCalendar objects in the specified calendar.
218     *
219     * This default may well be good enough for personal use, and calendars
220     * that aren't very large. But if you anticipate high usage, big calendars
221     * or high loads, you are strongly adviced to optimize certain paths.
222     *
223     * The best way to do so is override this method and to optimize
224     * specifically for 'common filters'.
225     *
226     * Requests that are extremely common are:
227     *   * requests for just VEVENTS
228     *   * requests for just VTODO
229     *   * requests with a time-range-filter on either VEVENT or VTODO.
230     *
231     * ..and combinations of these requests. It may not be worth it to try to
232     * handle every possible situation and just rely on the (relatively
233     * easy to use) CalendarQueryValidator to handle the rest.
234     *
235     * Note that especially time-range-filters may be difficult to parse. A
236     * time-range filter specified on a VEVENT must for instance also handle
237     * recurrence rules correctly.
238     * A good example of how to interprete all these filters can also simply
239     * be found in Sabre\CalDAV\CalendarQueryFilter. This class is as correct
240     * as possible, so it gives you a good idea on what type of stuff you need
241     * to think of.
242     *
243     * @param mixed $calendarId
244     * @param array $filters
245     * @return array
246     */
247    function calendarQuery($calendarId, array $filters);
248
249    /**
250     * Searches through all of a users calendars and calendar objects to find
251     * an object with a specific UID.
252     *
253     * This method should return the path to this object, relative to the
254     * calendar home, so this path usually only contains two parts:
255     *
256     * calendarpath/objectpath.ics
257     *
258     * If the uid is not found, return null.
259     *
260     * This method should only consider * objects that the principal owns, so
261     * any calendars owned by other principals that also appear in this
262     * collection should be ignored.
263     *
264     * @param string $principalUri
265     * @param string $uid
266     * @return string|null
267     */
268    function getCalendarObjectByUID($principalUri, $uid);
269
270}
271