ICalendar
in
Interface ICalendar
Tags
Table of Contents
Methods
- getDisplayColor() : null|string
- Calendar color
- getDisplayName() : null|string
- In comparison to getKey() this function returns a human readable (maybe translated) name
- getKey() : string
- getPermissions() : int
- getUri() : string
- In comparison to getKey() this function returns a unique uri within the scope of the principal
- isDeleted() : bool
- Indicates whether the calendar is in the trash bin
- search() : array<string|int, mixed>
- Search the current calendar for matching events.
Methods
getDisplayColor()
Calendar color
public
getDisplayColor() : null|string
Tags
Return values
null|stringgetDisplayName()
In comparison to getKey() this function returns a human readable (maybe translated) name
public
getDisplayName() : null|string
Tags
Return values
null|stringgetKey()
public
getKey() : string
Tags
Return values
string —defining the technical unique key
getPermissions()
public
getPermissions() : int
Tags
Return values
int —build up using Constants
getUri()
In comparison to getKey() this function returns a unique uri within the scope of the principal
public
getUri() : string
Tags
Return values
stringisDeleted()
Indicates whether the calendar is in the trash bin
public
isDeleted() : bool
Tags
Return values
boolsearch()
Search the current calendar for matching events.
public
search(string $pattern[, array<string|int, mixed> $searchProperties = [] ][, array<string|int, mixed> $options = [] ][, int|null $limit = null ][, int|null $offset = null ]) : array<string|int, mixed>
This method searches for events in the calendar that match a given pattern within specified properties. The search is case-insensitive. It supports optional parameters such as a time range, limit, and offset. The results are sorted by start date, with the closest events appearing first.
Parameters
- $pattern : string
-
A string to search for within the events. The search is done case-insensitive.
- $searchProperties : array<string|int, mixed> = []
-
Defines the properties within which the pattern should match.
- $options : array<string|int, mixed> = []
-
Optional parameters for the search:
- 'timerange' element that can have 'start' (DateTimeInterface), 'end' (DateTimeInterface), or both.
- 'uid' element to look for events with a given uid.
- 'types' element to only return events for a given type (e.g. VEVENT or VTODO)
- $limit : int|null = null
-
Limit the number of search results.
- $offset : int|null = null
-
For paging of search results.
Tags
Return values
array<string|int, mixed> —An array of events/journals/todos which are arrays of key-value-pairs. The events are sorted by start date (closest first, furthest last).
Implementation Details:
An event can consist of many sub-events, typically the case for events with recurrence rules. On a database level, there's only one event stored (with a matching first occurrence and last occurrence timestamp). Expanding an event into sub-events is done on the backend level. Using limit, offset, and timerange comes with some drawbacks. When asking the database for events, the result is ordered by the primary key to guarantee a stable order. After expanding the events into sub-events, they are sorted by the date (closest to furthest).
Usage Examples:
- Find 7 events within the next two weeks:
$dateTime = (new DateTimeImmutable())->setTimestamp($this->timeFactory->getTime()); $inTwoWeeks = $dateTime->add(new DateInterval('P14D'));
$calendar->search( '', [], ['timerange' => ['start' => $dateTime, 'end' => $inTwoWeeks]], 7 );
Note: When combining timerange and limit, it's possible that the expected outcome is not in the order you would expect.
Example: Create 7 events for tomorrow, starting from 11:00, 30 minutes each. Then create an 8th event for tomorrow at 10:00. The above code will list the event at 11:00 first, missing the event at 10:00. The reason is the ordering by the primary key and expanding on the backend level. This is a technical limitation. The easiest workaround is to fetch more events than you actually need, with the downside of needing more resources.
Related:
- https://github.com/nextcloud/server/pull/45222
- https://github.com/nextcloud/server/issues/53002
- Find all events where the location property contains the string 'Berlin':
$calendar->search( 'Berlin', ['LOCATION'] );