diff options
| author | Joas Schilling <213943+nickvergessen@users.noreply.github.com> | 2025-01-08 11:48:53 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2025-01-08 11:48:53 +0100 |
| commit | dd0f7f0bbfb9c176fe4845458bdc62ec7b388d8f (patch) | |
| tree | 9da570ba67309bbdcb19e280deeb491109aa9d61 /lib/public | |
| parent | e7122a6864947ead88a022d0a6cf3a4c4209b6eb (diff) | |
| parent | 42fa3abc3ef31d6bfebc29b76c8f55da45c1d16c (diff) | |
| download | nextcloud-server-dd0f7f0bbfb9c176fe4845458bdc62ec7b388d8f.tar.gz nextcloud-server-dd0f7f0bbfb9c176fe4845458bdc62ec7b388d8f.zip | |
Merge pull request #49888 from nextcloud/feat/ocp/meetings-api-requirements
feat(ocp): calendar event builder api
Diffstat (limited to 'lib/public')
| -rw-r--r-- | lib/public/Calendar/ICalendarEventBuilder.php | 110 | ||||
| -rw-r--r-- | lib/public/Calendar/IManager.php | 8 |
2 files changed, 118 insertions, 0 deletions
diff --git a/lib/public/Calendar/ICalendarEventBuilder.php b/lib/public/Calendar/ICalendarEventBuilder.php new file mode 100644 index 00000000000..8afc817a61e --- /dev/null +++ b/lib/public/Calendar/ICalendarEventBuilder.php @@ -0,0 +1,110 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Calendar; + +use DateTimeInterface; +use InvalidArgumentException; +use OCP\Calendar\Exceptions\CalendarException; + +/** + * The calendar event builder can be used to conveniently build a calendar event and then serialize + * it to a ICS string. The ICS string can be submitted to calendar instances implementing the + * {@see \OCP\Calendar\ICreateFromString} interface. + * + * Also note this class can not be injected directly with dependency injection. + * Instead, inject {@see \OCP\Calendar\IManager} and use + * {@see \OCP\Calendar\IManager::createEventBuilder()} afterwards. + * + * All setters return self to allow chaining method calls. + * + * @since 31.0.0 + */ +interface ICalendarEventBuilder { + /** + * Set the start date, time and time zone. + * This property is required! + * + * @since 31.0.0 + */ + public function setStartDate(DateTimeInterface $start): self; + + /** + * Set the end date, time and time zone. + * This property is required! + * + * @since 31.0.0 + */ + public function setEndDate(DateTimeInterface $end): self; + + /** + * Set the event summary or title. + * This property is required! + * + * @since 31.0.0 + */ + public function setSummary(string $summary): self; + + /** + * Set the event description. + * + * @since 31.0.0 + */ + public function setDescription(string $description): self; + + /** + * Set the event location. It can either be a physical address or a URL. + * + * @since 31.0.0 + */ + public function setLocation(string $location): self; + + /** + * Set the event organizer. + * This property is required if attendees are added! + * + * The "mailto:" prefix is optional and will be added automatically if it is missing. + * + * @since 31.0.0 + */ + public function setOrganizer(string $email, ?string $commonName = null): self; + + /** + * Add a new attendee to the event. + * Adding at least one attendee requires also setting the organizer! + * + * The "mailto:" prefix is optional and will be added automatically if it is missing. + * + * @since 31.0.0 + */ + public function addAttendee(string $email, ?string $commonName = null): self; + + /** + * Serialize the built event to an ICS string if all required properties set. + * + * @since 31.0.0 + * + * @return string The serialized ICS string + * + * @throws InvalidArgumentException If required properties were not set + */ + public function toIcs(): string; + + /** + * Create the event in the given calendar. + * + * @since 31.0.0 + * + * @return string The filename of the created event + * + * @throws InvalidArgumentException If required properties were not set + * @throws CalendarException If writing the event to the calendar fails + */ + public function createInCalendar(ICreateFromString $calendar): string; +} diff --git a/lib/public/Calendar/IManager.php b/lib/public/Calendar/IManager.php index bb3808f133c..8056d57d859 100644 --- a/lib/public/Calendar/IManager.php +++ b/lib/public/Calendar/IManager.php @@ -157,4 +157,12 @@ interface IManager { * @since 25.0.0 */ public function handleIMipCancel(string $principalUri, string $sender, ?string $replyTo, string $recipient, string $calendarData): bool; + + /** + * Create a new event builder instance. Please have a look at its documentation and the + * \OCP\Calendar\ICreateFromString interface on how to use it. + * + * @since 31.0.0 + */ + public function createEventBuilder(): ICalendarEventBuilder; } |