aboutsummaryrefslogtreecommitdiffstats
path: root/lib/public/Calendar
diff options
context:
space:
mode:
Diffstat (limited to 'lib/public/Calendar')
-rw-r--r--lib/public/Calendar/BackendTemporarilyUnavailableException.php1
-rw-r--r--lib/public/Calendar/CalendarEventStatus.php8
-rw-r--r--lib/public/Calendar/ICalendar.php72
-rw-r--r--lib/public/Calendar/ICalendarExport.php2
-rw-r--r--lib/public/Calendar/ICalendarIsEnabled.php2
-rw-r--r--lib/public/Calendar/ICalendarIsShared.php2
-rw-r--r--lib/public/Calendar/ICalendarIsWritable.php2
-rw-r--r--lib/public/Calendar/ICreateFromString.php24
-rw-r--r--lib/public/Calendar/IMetadataProvider.php1
-rw-r--r--lib/public/Calendar/Resource/IBackend.php1
-rw-r--r--lib/public/Calendar/Resource/IResource.php1
-rw-r--r--lib/public/Calendar/Resource/IResourceMetadata.php1
-rw-r--r--lib/public/Calendar/Room/IBackend.php1
-rw-r--r--lib/public/Calendar/Room/IRoom.php1
-rw-r--r--lib/public/Calendar/Room/IRoomMetadata.php1
15 files changed, 103 insertions, 17 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/ICreateFromString.php b/lib/public/Calendar/ICreateFromString.php
index 5badaa2d4cf..2bb0f2ffa20 100644
--- a/lib/public/Calendar/ICreateFromString.php
+++ b/lib/public/Calendar/ICreateFromString.php
@@ -17,9 +17,31 @@ use OCP\Calendar\Exceptions\CalendarException;
*/
interface ICreateFromString extends ICalendar {
/**
- * @since 23.0.0
+ * Create an event in this calendar from an ICS string.
+ *
+ * @param string $name the file name - needs to contain the .ics ending
+ * @param string $calendarData a string containing a valid VEVENT ics
*
* @throws CalendarException
+ *
+ * @since 23.0.0
+ *
*/
public function createFromString(string $name, string $calendarData): void;
+
+ /**
+ * Create an event in this calendar from an ICS string using a minimal CalDAV server.
+ * Usually, the createFromString() method should be preferred.
+ *
+ * However, in some cases it is useful to not set up a full CalDAV server.
+ * Missing features include no iMIP plugin, no invitation emails amongst others.
+ *
+ * @param string $name the file name - needs to contain the .ics ending
+ * @param string $calendarData a string containing a valid VEVENT ics
+ *
+ * @throws CalendarException
+ *
+ * @since 32.0.0
+ */
+ public function createFromStringMinimal(string $name, string $calendarData): void;
}
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
generated by cgit v1.2.3 (git 2.39.1) at 2025-07-31 11:45:22 +0000