PHP Calendar API: Write support

[georgehrke]

OCP\Calendar\IManager is currently only providing a read-only API.
This is drastically limiting the number of use-cases, forcing app-developers to use the CalDAV interface via javascript, if they desire write-support for the user's calendar.

Nextcloud should provide a PHP api with write-support for the user's calendar.

Due to it's simple design, our current API is limited to read-only. Adding write-support to the existing API is not possible. This is mostly caused by the structure of events.
They are returned as a very simple key-value array. Some information from the ICS is already lost when the conversion takes place. Converting modified key-value arrays back to ICS could possibly lead to data-loss.

• Create objects into a calendar Add calendar object creation API to OCP #29188
  Documentation
• Update objects
• Deleting objects

---

Original proposition

Proposal:

1. Deprecate \OCP\Calendar\IManager and \OCP\Calendar\ICalendar with Nextcloud 20 and remove with Nextcloud 23.

• Implement \OCP\Calendar\IManagerV2:

interface \OCP\Calendar\IManagerV2{
        public function isEnabled():bool;
        public function getCalendars():ICalendarV2[];
        public function getCalendar(string $key):?ICalendarV2;
        public function search(string $pattern, array $searchProperties=[], array $options=[], int $limit=null, int $offset=null)?ICalendarObjectV2[];
        public function registerCalendar(ICalendarV2 $calendar):void;
        public function unregisterCalendar(ICalendarV2 $calendar):void;
        public function register(\Closure $callable):void;
        public function clear():void;
}

• Implement \OCP\Calendar\ICalendarV2:

interface \OCP\Calendar\ICalendarV2{
	public function getKey():string;
	public function getDisplayName():?string;
	public function getDisplayColor():?string;
        public function isWriteable():bool;
        public function getByUri(string $uri):?ICalendarObjectV2;
        public function search(string $pattern, array $searchProperties=[], array $options=[], int $limit=null, int $offset=null)?ICalendarObjectV2[];
        public function create(\Sabre\VObject\VCalendar $vObject):ICalendarObjectV2;
}

• Implement \OCP\Calendar\ICalendarObjectV2:

interface \OCP\Calendar\ICalendarObjectV2{
        public function getCalendarKey():string;
        public function getUri():string;
        public function getVObject():\Sabre\VObject\VCalendar;
        public function update():void;
        public function delete():void;
}

[georgehrke]

also ref #17129

[georgehrke]

cc @rullzer for feature planning :)

[georgehrke]

@tcitworld Who else needed write-access to the calendar?

[tcitworld]

I can think of

• @dartcafe for Compare date poll with user's calendar polls#747
• @juliushaertl for Integrate with Nextcloud CalDAV API [$185] deck#15
• maybe @ChristophWurst for the Mail app to add attachments events/handle invitations instead of using CalDAV through JS
• @blizzz for workflow engine
• https://github.com/audriga/nextcloud-jmap to write calendars / contacts
• @eneiluj for integration_google / integration_onedrive
• a lot of small apps I thought of at some point :p
• Integrate with Nextcloud Calendar to create a meal planner? cookbook#127

[tcitworld]

Added workflow engine to use cases.

[rotdrop]

FYI, have updated @tcitworld merge request #20178, re-basing it to the current master and fixing the failing merge checks, see #23234. Would be "nice to have" for polishing cafevdb.

[rotdrop]

Concerning use cases: cafevdb shares several objects among the members of the executive board of an orchestra. Shared events (rehearsals/concerts/meetings) are of course an important component.

[tbmatuka]

I have a use-case where I would need to add/update events for all users via the API. We have a self-hosted mail server and would like to automatically import any .ics file that users receive. The mail server side is simple and we have it ready, but importing the events into Nextcloud is our current problem.

Does the current state of the implementation support using a single API key to manage calendars for all users?

[ChristophWurst]

I would like to note that we should possibly include the user ID as argument of the APIs. Having the user as context makes the APIs usable for calendars of other users as well, and when there is no user context (background job, occ).

[ChristophWurst]

@miaulalala will implement the creation part of new events. To avoid leading sabre types in the public API she will add a create method that takes the calendar object name and the calendar object data as string.