diff options
Diffstat (limited to 'lib/public')
| -rw-r--r-- | lib/public/Calendar/ICalendar.php | 72 |
1 files changed, 65 insertions, 7 deletions
diff --git a/lib/public/Calendar/ICalendar.php b/lib/public/Calendar/ICalendar.php index 2dfc1ca632f..50152d1240b 100644 --- a/lib/public/Calendar/ICalendar.php +++ b/lib/public/Calendar/ICalendar.php @@ -8,10 +8,18 @@ declare(strict_types=1); */ namespace OCP\Calendar; +use DateTimeInterface; + /** * Interface ICalendar * * @since 13.0.0 + * + * @psalm-type CalendarSearchOptions = array{ + * timerange?: array{start?: DateTimeInterface, end?: DateTimeInterface}, + * uid?: string, + * types?: string[], + * } */ interface ICalendar { /** @@ -41,13 +49,63 @@ interface ICalendar { public function getDisplayColor(): ?string; /** - * @param string $pattern which should match within the $searchProperties - * @param array $searchProperties defines the properties within the query pattern should match - * @param array $options - optional parameters: - * ['timerange' => ['start' => new DateTime(...), 'end' => new DateTime(...)]] - * @param int|null $limit - limit number of search results - * @param int|null $offset - offset for paging of search results - * @return array an array of events/journals/todos which are arrays of key-value-pairs. the events are sorted by start date (closest first, furthest last) + * Search the current calendar for matching events. + * + * 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. + * + * @param string $pattern A string to search for within the events. The search is done case-insensitive. + * @param array $searchProperties Defines the properties within which the pattern should match. + * @param array $options 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) + * @psalm-param CalendarSearchOptions $options + * @param int|null $limit Limit the number of search results. + * @param int|null $offset For paging of search results. + * @return array 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: + * + * 1) 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 + * + * 2) Find all events where the location property contains the string 'Berlin': + * + * $calendar->search( + * 'Berlin', + * ['LOCATION'] + * ); + * * @since 13.0.0 */ public function search(string $pattern, array $searchProperties = [], array $options = [], ?int $limit = null, ?int $offset = null): array; |