Calendar integration

On this page you can learn more about integrating with the Nextcloud calendar services.

Access calendars and events

Calendar objects

You can query the contents of calendars in the back end through the calendar manager service. Queries are always scoped to a principal (user) but may follow further search criteria like string matches or date ranges.

Inject the calendar manager into your class. Then you can use newQuery and searchForPrincipal to build and execute a search query.

In the following example you see a basic use case of the calendar query API where specific user’s calendar is searched for any events and tasks during a given duration.

<?php

use OCP\Calendar\IManager;

class MyService {

    /** @var IManager */
    private $calendarManager;

    public function __construct(IManager $calendarManager) {
        $this->calendarManager = $calendarManager;
    }

    public function searchInUserCalendar(string $uid,
                                         string $calendarUri,
                                         DateTimeImmutable $from,
                                         DateTimeImmutable $to): void {
        $principal = 'principals/users/' . $uid;

        // Prepare the query
        $query = $this->calendarManager->newQuery($principal);
        $query->addSearchCalendar($uri);
        $query->setTimerangeStart($from);
        $query->setTimerangeEnd($to);

        // Execute the query
        $objects = $this->calendarManager->searchForPrincipal($query);
    }

}

Study the interface \OCP\Calendar\ICalendarQuery to learn more about other query options.

Calendars

You can access calendars through the IManager. Inject the service, then use the getCalendarsForPrincipal method.

You can either query all calendars of the principal if you omit the second argument, or look for specific calendars only. See the examples below.

<?php

use OCP\Calendar\IManager;

class MyService {

    /** @var IManager */
    private $calendarManager;

    public function __construct(IManager $calendarManager) {
        $this->calendarManager = $calendarManager;
    }

    public function processCalendarData(string $uid): void {
        $principal = 'principals/users/' . $uid;

        // This will find all calendars of the principal
        $calendars = $this->calendarManager->getCalendarsForPrincipal($principal);

        // Work with calendars
    }

    public function processCalendarData(string $uid, string $calendarUri): void {
        $principal = 'principals/users/' . $uid;

        // This will only find specific calendars of the principal
        $calendars = $this->calendarManager->getCalendarsForPrincipal(
            $principal,
            [$calendarUri]
        );

        // Check if the requested calendar was found and work with it
    }

}

The returned objects implement \OCP\Calendar\ICalendar. Study the interface methods to discover what data is available.

Note

All calendars are by default only readable, therefore ICalendar does not offer methods for mutation. Some of the calendars are mutable, however, and they may further extend the interface \OCP\Calendar\ICreateFromString.

Calendar providers

The Nextcloud groupware integration provides access to internal calendars. It is, however, for third party apps possible to provide individual calenders. The section Integration of custom calendar providers describes on how to implement a provider within the Nextcloud server.

Resources

Nextcloud apps can provide resource back ends for the CalDAV server in Nextcloud.

To register a custom back end, create a class that implements \OCP\Calendar\Resource\IBackend.

In the boot method of your Application class you can fetch the \OCP\Calendar\Resource\IManager instance and pass the fully qualified class name of your custom back end to registerBackend.

<?php

use OCP\Calendar\Resource\IManager;

class Application extends App implements IBootstrap {

    public function __construct() {
        parent::__construct('myapp');
    }

    public function register(IRegistrationContext $context): void {
        // ... registration logic goes here ...
    }

    public function boot(IBootContext $context): void {
        /** @var IManager $manager */
        $resourceManager = $serverContainer->get(IManager::class);
        $resourceManager->registerBackend(\OCA\MyApp\ResourceBackend::class);
    }

}

Note

Nextcloud queries the registered back ends only periodically through a background job. If the resources do not show up in the front-end double check if cron jobs are run on your development instance.

Rooms

Nextcloud apps can provide rooms back ends for the CalDAV server in Nextcloud.

To register a custom back end, create a class that implements \OCP\Calendar\Room\IBackend.

In the boot method of your Application class you can fetch the \OCP\Calendar\Room\IManager instance and pass the fully qualified class name of your custom back end to registerBackend.

<?php

use OCP\Calendar\Room\IManager;

class Application extends App implements IBootstrap {

    public function __construct() {
        parent::__construct('myapp');
    }

    public function register(IRegistrationContext $context): void {
        // ... registration logic goes here ...
    }

    public function boot(IBootContext $context): void {
        /** @var IManager $manager */
        $resourceManager = $serverContainer->get(IManager::class);
        $resourceManager->registerBackend(\OCA\MyApp\RoomBackend::class);
    }

}

Note

Nextcloud queries the registered back ends only periodically through a background job. If the rooms do not show up in the front-end double check if cron jobs are run on your development instance.