Events¶

Events are used to communicate between different aspects of the Nextcloud eco system. They are used in the Nextcloud server internally, for server-to-apps communcation as well as inter-app communication.

Overview¶

The term “events” is a bit broad in Nextcloud and there are multiple ways of emitting them.

OCP event dispatcher
Symfony event dispatcher
Hooks
Public Emitter

OCP event dispatcher¶

This mechanism is a versatile and typed approach to events in Nextcloud’s php code. It uses objects rather than just passing primitives or untyped arrays. This should help provide a better developer experience while lowering the risk of unexpected changes in the API that are hard to find after the initial implementation.

Naming scheme¶

The name should reflect the subject and the actions. Suffixing event classes with Event makes it easier to recognize their purpose.

For example, if a user is created, a UserCreatedEvent will be emitted.

Events are ususally evmitted after the event has happened. If it’s emitted before, it should be prefixed with Before.

Thus BeforeUserCreatedEvent is emitted before the user data is written to the database.

Note

Although you may chose to name your event classes differently, sticking to the convention will allow Nextcloud developers understand each other’s apps more easily.

Writing events¶

As a rule events are dedicated classes extending \OCP\EventDispatcher\Event.

<?php

use OCP\EventDispatcher\Event;

namespace OCA\MyApp\Event;

class AddEvent extends Event {}

The event above allows signalling that something happened. But in many cases you want to actually transport data like the affected resource with the event. Then the events act as simple data transfer objects. Therefore they need a constructor that takes the arguments, private members to store them and getters to access the values in listeners.

<?php

use OCP\EventDispatcher\Event;
use OCP\IUser;

class UserCreatedEvent extends Event {

    /** @var IUser */
    private $user;

    public function __construct(IUser $user) {
        parent::__construct();
        $this->user = $user;
    }

    public function getUser(): IUser {
        return $this->user;
    }

}

Writing a listener¶

A listener can be a simple callback function (or anything else that is callable, or a dedicated class.

Listener callbacks¶

You can use simple callback to react on events. They will receive the event object as first and only parameter. You can type-hint the base Event class or the subclass you expect and register for.

<?php

use OCA\MyApp\Event\AddEvent;
use OCP\AppFramework\App;
use OCP\EventDispatcher\IEventDispatcher;

namespace OCA\MyApp\AppInfo;

class Application extends App {
    public function __construct() {
        parent::__construct('myapp');
            /* @var IEventDispatcher $eventDispatcher */
            $dispatcher = $this->getContainer()->query(IEventDispatcher::class);
            $dispatcher->addListener(AddEvent::class, function(AddEvent $event) {
                // ...
            });
    }
}

Note

Type-hinting the actual event class will give you better IDE and static analyzers support. It’s generally safe to assume the dispatcher will not give you any other objects.

Listener classes¶

A class that can handle an event will implement the \OCP\EventDispatcher\IEventListener interface. Class names should end with Listener.

<?php

use OCA\MyApp\Event\AddEvent;
use OCP\EventDispatcher\Event;
use OCP\EventDispatcher\IEventListener;

namespace OCA\MyApp\Event;

class AddTwoListener implements IEventListener {

    public function handle(Event $event): void {
        if (!($event instanceOf AddEvent)) {
            return;
        }

        $event->addToCounter(2);
    }
}

Note

Php parameter type hints are not allowed to be more specific than the type hints on the interface, thus you can’t use AddEvent in the method signature but use an instanceOf instead.

In the Application.php the event and the listener class are connected. The class is instantiated only when the actual event is fired.

<?php

use OCA\MyApp\Event\AddEvent;
use OCA\MyApp\Listener\AddTwoListener;
use OCP\AppFramework\App;
use OCP\EventDispatcher\IEventDispatcher;

namespace OCA\MyApp\AppInfo;

class Application extends App {
    public function __construct() {
        parent::__construct('myapp');

            /* @var IEventDispatcher $eventDispatcher */
            $dispatcher = $this->getContainer()->query(IEventDispatcher::class);
            $dispatcher->addServiceListener(AddEvent::class, AddTwoListener::class);
    }
}

Note

The listener is resolved via the DI container, therefore you can add a constructor and type-hint services required for processing the event.

Available Events¶

Here you find an overview of the public events that can be consumed in apps. See their source files for more details.

`\OCA\Files\Event\LoadAdditionalScriptsEvent`¶

Available in Nextcloud 17 and later.

This event is triggered when the files app is rendered. It canb e used to add additional scripts to the files app.