Server: 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.

---

Proposal:

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

2.

• 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

[georgehrke]

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

[tcitworld]

I can think of

• @dartcafe for https://github.com/nextcloud/polls/pull/747
• @juliushaertl for https://github.com/nextcloud/deck/issues/15
• @nickvergessen for https://github.com/nextcloud/spreed/issues/2226
• maybe @ChristophWurst for the Mail app to add attachments events/handle invitations instead of using CalDAV through JS
• @blizzz for workflow engine
• a lot of small apps I thought of at some point :p

[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?

[seyfeb]

Another use case exists for creating meal plans from the Cookbook app, see https://github.com/nextcloud/cookbook/issues/127