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