diff options
Diffstat (limited to 'lib/public/Calendar')
-rw-r--r-- | lib/public/Calendar/BackendTemporarilyUnavailableException.php | 1 | ||||
-rw-r--r-- | lib/public/Calendar/CalendarEventStatus.php | 8 | ||||
-rw-r--r-- | lib/public/Calendar/ICalendar.php | 72 | ||||
-rw-r--r-- | lib/public/Calendar/ICalendarExport.php | 2 | ||||
-rw-r--r-- | lib/public/Calendar/ICalendarIsEnabled.php | 2 | ||||
-rw-r--r-- | lib/public/Calendar/ICalendarIsShared.php | 2 | ||||
-rw-r--r-- | lib/public/Calendar/ICalendarIsWritable.php | 2 | ||||
-rw-r--r-- | lib/public/Calendar/IMetadataProvider.php | 1 | ||||
-rw-r--r-- | lib/public/Calendar/Resource/IBackend.php | 1 | ||||
-rw-r--r-- | lib/public/Calendar/Resource/IResource.php | 1 | ||||
-rw-r--r-- | lib/public/Calendar/Resource/IResourceMetadata.php | 1 | ||||
-rw-r--r-- | lib/public/Calendar/Room/IBackend.php | 1 | ||||
-rw-r--r-- | lib/public/Calendar/Room/IRoom.php | 1 | ||||
-rw-r--r-- | lib/public/Calendar/Room/IRoomMetadata.php | 1 |
14 files changed, 80 insertions, 16 deletions
diff --git a/lib/public/Calendar/BackendTemporarilyUnavailableException.php b/lib/public/Calendar/BackendTemporarilyUnavailableException.php index e02ef1a84fd..c2bbb1417ee 100644 --- a/lib/public/Calendar/BackendTemporarilyUnavailableException.php +++ b/lib/public/Calendar/BackendTemporarilyUnavailableException.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Calendar/CalendarEventStatus.php b/lib/public/Calendar/CalendarEventStatus.php index 5e070545758..fd735150578 100644 --- a/lib/public/Calendar/CalendarEventStatus.php +++ b/lib/public/Calendar/CalendarEventStatus.php @@ -7,11 +7,9 @@ declare(strict_types=1); */ namespace OCP\Calendar; -/** - * The status of a calendar event. - * - * @since 32.0.0 - */ +use OCP\AppFramework\Attribute\Listenable; + +#[Listenable(since: '32.0.0')] enum CalendarEventStatus: string { case TENTATIVE = 'TENTATIVE'; case CONFIRMED = 'CONFIRMED'; 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; diff --git a/lib/public/Calendar/ICalendarExport.php b/lib/public/Calendar/ICalendarExport.php index 61b286e1668..d884c104a4a 100644 --- a/lib/public/Calendar/ICalendarExport.php +++ b/lib/public/Calendar/ICalendarExport.php @@ -16,7 +16,7 @@ use Generator; * @since 32.0.0 */ interface ICalendarExport { - + /** * Export objects * diff --git a/lib/public/Calendar/ICalendarIsEnabled.php b/lib/public/Calendar/ICalendarIsEnabled.php index 868159d208f..6bcb487e3dc 100644 --- a/lib/public/Calendar/ICalendarIsEnabled.php +++ b/lib/public/Calendar/ICalendarIsEnabled.php @@ -13,7 +13,7 @@ namespace OCP\Calendar; * @since 32.0.0 */ interface ICalendarIsEnabled { - + /** * Indicates whether the calendar is enabled * diff --git a/lib/public/Calendar/ICalendarIsShared.php b/lib/public/Calendar/ICalendarIsShared.php index 8121c826f4e..6f63c6eefd0 100644 --- a/lib/public/Calendar/ICalendarIsShared.php +++ b/lib/public/Calendar/ICalendarIsShared.php @@ -14,7 +14,7 @@ namespace OCP\Calendar; * @since 31.0.0 */ interface ICalendarIsShared { - + /** * Indicates whether the calendar is shared with the current user * diff --git a/lib/public/Calendar/ICalendarIsWritable.php b/lib/public/Calendar/ICalendarIsWritable.php index f80769e9033..5bf08a25cdc 100644 --- a/lib/public/Calendar/ICalendarIsWritable.php +++ b/lib/public/Calendar/ICalendarIsWritable.php @@ -14,7 +14,7 @@ namespace OCP\Calendar; * @since 31.0.0 */ interface ICalendarIsWritable { - + /** * Indicates whether the calendar can be modified * diff --git a/lib/public/Calendar/IMetadataProvider.php b/lib/public/Calendar/IMetadataProvider.php index bee840c955f..acacf7efdaf 100644 --- a/lib/public/Calendar/IMetadataProvider.php +++ b/lib/public/Calendar/IMetadataProvider.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Calendar/Resource/IBackend.php b/lib/public/Calendar/Resource/IBackend.php index b43d79e3618..23d37c102f2 100644 --- a/lib/public/Calendar/Resource/IBackend.php +++ b/lib/public/Calendar/Resource/IBackend.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Calendar/Resource/IResource.php b/lib/public/Calendar/Resource/IResource.php index f284eee955f..15abe4e2d0f 100644 --- a/lib/public/Calendar/Resource/IResource.php +++ b/lib/public/Calendar/Resource/IResource.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Calendar/Resource/IResourceMetadata.php b/lib/public/Calendar/Resource/IResourceMetadata.php index acf02bc3609..29f628d6f7f 100644 --- a/lib/public/Calendar/Resource/IResourceMetadata.php +++ b/lib/public/Calendar/Resource/IResourceMetadata.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Calendar/Room/IBackend.php b/lib/public/Calendar/Room/IBackend.php index 52ec2fa5948..c99f5fbdb72 100644 --- a/lib/public/Calendar/Room/IBackend.php +++ b/lib/public/Calendar/Room/IBackend.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Calendar/Room/IRoom.php b/lib/public/Calendar/Room/IRoom.php index 580c676331f..526e65b8f5f 100644 --- a/lib/public/Calendar/Room/IRoom.php +++ b/lib/public/Calendar/Room/IRoom.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Calendar/Room/IRoomMetadata.php b/lib/public/Calendar/Room/IRoomMetadata.php index 3fb4089b6a7..15d4b501e12 100644 --- a/lib/public/Calendar/Room/IRoomMetadata.php +++ b/lib/public/Calendar/Room/IRoomMetadata.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later |