126 lines
4.5 KiB
PHP
126 lines
4.5 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
/**
|
|
* SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors
|
|
* SPDX-License-Identifier: AGPL-3.0-or-later
|
|
*/
|
|
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 {
|
|
/**
|
|
* @return string defining the technical unique key
|
|
* @since 13.0.0
|
|
*/
|
|
public function getKey(): string;
|
|
|
|
/**
|
|
* In comparison to getKey() this function returns a unique uri within the scope of the principal
|
|
* @since 24.0.0
|
|
*/
|
|
public function getUri(): string;
|
|
|
|
/**
|
|
* In comparison to getKey() this function returns a human readable (maybe translated) name
|
|
* @return null|string
|
|
* @since 13.0.0
|
|
*/
|
|
public function getDisplayName(): ?string;
|
|
|
|
/**
|
|
* Calendar color
|
|
* @return null|string
|
|
* @since 13.0.0
|
|
*/
|
|
public function getDisplayColor(): ?string;
|
|
|
|
/**
|
|
* 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;
|
|
|
|
/**
|
|
* @return int build up using {@see \OCP\Constants}
|
|
* @since 13.0.0
|
|
*/
|
|
public function getPermissions(): int;
|
|
|
|
/**
|
|
* Indicates whether the calendar is in the trash bin
|
|
*
|
|
* @since 26.0.0
|
|
*/
|
|
public function isDeleted(): bool;
|
|
}
|