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 communication 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
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 usually emitted 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 choose to name your event classes differently, sticking to the convention will allow Nextcloud developers understand each other’s apps more easily.

Note

For backwards compatibility with the Symfony class GenericEvent, Nextcloud also provides a \OCP\EventDispatcher\Event class. With the release of Nextcloud 22 this class has been deprecated. Named and typed event classes should be used instead.

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 {
    private IUser $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 $dispatcher */
            $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()->get(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\DAV\Events\AddressBookCreatedEvent`

Added in version 20.

This event is triggered when a user creates a new address-book.

`\OCA\DAV\Events\AddressBookDeletedEvent`

Added in version 20.

This event is triggered when a user deletes an address-book.

`\OCA\DAV\Events\AddressBookShareUpdatedEvent`

Added in version 20.

This event is triggered when a user shares or unshares an address-book.

`\OCA\DAV\Events\AddressBookUpdatedEvent`

Added in version 20.

This event is triggered when a user updates an address-book.

`\OCA\DAV\Events\CachedCalendarObjectCreatedEvent`

Added in version 20.

This event is triggered when a cached calendar object is being created while fetching a calendar-subscription.

`\OCA\DAV\Events\CachedCalendarObjectDeletedEvent`

Added in version 20.

This event is triggered when a cached calendar object is being deleted while fetching a calendar-subscription.

`\OCA\DAV\Events\CachedCalendarObjectUpdatedEvent`

Added in version 20.

This event is triggered when a cached calendar object is being updated while fetching a calendar-subscription.

`\OCA\DAV\Events\CalendarCreatedEvent`

Added in version 20.

This event is triggered when a user creates a new calendar.

`\OCA\DAV\Events\CalendarDeletedEvent`

Added in version 20.

This event is triggered when a user deletes a calendar.

`\OCA\DAV\Events\CalendarObjectCreatedEvent`

Added in version 20.

This event is triggered when a user creates a calendar-object.

`\OCA\DAV\Events\CalendarObjectDeletedEvent`

Added in version 20.

This event is triggered when a user deletes a calendar-object.

`\OCA\DAV\Events\CalendarObjectUpdatedEvent`

Added in version 20.

This event is triggered when a user updates a calendar-object.

`\OCA\DAV\Events\CalendarPublishedEvent`

Added in version 20.

This event is triggered when a user publishes a calendar.

`\OCA\DAV\Events\CalendarShareUpdatedEvent`

Added in version 20.

This event is triggered when a user shares or unshares a calendar.

`\OCA\DAV\Events\CalendarUnpublishedEvent`

Added in version 20.

This event is triggered when a user unpublishes calendar.

`\OCA\DAV\Events\CalendarUpdatedEvent`

Added in version 20.

This event is triggered when a user updates a calendar.

`\OCA\DAV\Events\CardCreatedEvent`

Added in version 20.

This event is triggered when a user creates a new card in an address-book.

`\OCA\DAV\Events\CardDeletedEvent`

Added in version 20.

This event is triggered when a user deletes a card in an address-book.

`\OCA\DAV\Events\CardUpdatedEvent`

Added in version 20.

This event is triggered when a user updates a card in an address-book.

`OCA\DAV\Events\SabrePluginAddEvent`

Added in version 28.

This event is triggered during the setup of the SabreDAV server to allow the registration of additional plugins.

`\OCA\DAV\Events\SabrePluginAuthInitEvent`

Added in version 20.

This event is triggered during the setup of the SabreDAV server to allow the registration of additional authentication backends.

`\OCA\DAV\Events\SubscriptionCreatedEvent`

Added in version 20.

This event is triggered when a user creates a new calendar-subscription.

`\OCA\DAV\Events\SubscriptionDeletedEvent`

Added in version 20.

This event is triggered when a user deletes a calendar-subscription.

`\OCA\DAV\Events\SubscriptionUpdatedEvent`

Added in version 20.

This event is triggered when a user deletes a calendar-subscription.

`\OCA\FederatedFileSharing\Events\FederatedShareAddedEvent`

Added in version 20.

This event is triggered when a federated share is successfully added.

`\OCA\Files\Event\LoadAdditionalScriptsEvent`

Added in version 17.

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

`\OCA\Files_Trashbin\Events\MoveToTrashEvent`

Added in version 28.

Emitted after a file or folder is moved to the trashbin.

`\OCA\Settings\Events\BeforeTemplateRenderedEvent`

Added in version 20.

This event is triggered right before the user management template is rendered.

`\OCA\User_LDAP\Events\GroupBackendRegistered`

Added in version 20.

This event is triggered right after the LDAP group backend is registered.

`\OCA\User_LDAP\Events\UserBackendRegistered`

Added in version 20.

This event is triggered right after the LDAP user backend is registered.

`\OCA\Viewer\Event\LoadViewer`

Added in version 17.

This event is triggered whenever the viewer is loaded and extensions should be loaded.

`OCP\Accounts\UserUpdatedEvent`

Added in version 28.

This event is triggered when the account data of a user was updated.

`OCP\App\Events\AppDisableEvent`

Added in version 27.

This event is triggered when an app is disabled.

`OCP\App\Events\AppEnableEvent`

Added in version 27.

This event is triggered when an app is enabled.

`OCP\App\Events\AppUpdateEvent`

Added in version 27.

This event is triggered when an app is updated.

`OCP\App\ManagerEvent`

Added in version 9.

Class ManagerEvent

`OCP\AppFramework\Http\Events\BeforeLoginTemplateRenderedEvent`

Added in version 28.

Emitted before the rendering step of the login TemplateResponse.

`OCP\AppFramework\Http\Events\BeforeTemplateRenderedEvent`

Added in version 20.

Emitted before the rendering step of each TemplateResponse. The event holds a flag that specifies if an user is logged in.

`OCP\Authentication\Events\AnyLoginFailedEvent`

Added in version 26.

Emitted when the authentication fails

`OCP\Authentication\Events\LoginFailedEvent`

Added in version 19.

Emitted when the authentication fails, but only if the login name can be associated with an existing user.

`OCP\Authentication\TwoFactorAuth\RegistryEvent`

Added in version 15.

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderChallengeFailed`

Added in version 28.

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderChallengePassed`

Added in version 28.

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderDisabled`

Added in version 20.

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserDisabled`

Added in version 22.

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserEnabled`

Added in version 22.

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserRegistered`

Added in version 28.

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserUnregistered`

Added in version 28.

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderUserDeleted`

Added in version 28.

`OCP\BeforeSabrePubliclyLoadedEvent`

Added in version 26.

Dispatched before Sabre is loaded when accessing public webdav endpoints This can be used to inject a Sabre plugin for example

`OCP\Collaboration\AutoComplete\AutoCompleteEvent`

Added in version 16.

`OCP\Collaboration\AutoComplete\AutoCompleteFilterEvent`

Added in version 28.

`OCP\Collaboration\Reference\RenderReferenceEvent`

Added in version 25.

Event emitted when apps might render references like link previews or smart picker widgets. This can be used to inject scripts for extending that. Further details can be found in the Reference providers deep dive.

`OCP\Collaboration\Resources\LoadAdditionalScriptsEvent`

Added in version 25.

This event is used by apps to register their own frontend scripts for integrating projects in their app. Apps also need to dispatch the event in order to load scripts during page load

`OCP\Comments\CommentsEntityEvent`

Added in version 9.1.

Changed in version 28.0.0: Dispatched as a typed event

Class CommentsEntityEvent

`OCP\Comments\CommentsEvent`

Added in version 9.

Class CommentsEvent

`OCP\Config\BeforePreferenceDeletedEvent`

Added in version 25.

`OCP\Config\BeforePreferenceSetEvent`

Added in version 25.

`OCP\Console\ConsoleEvent`

Added in version 9.

Class ConsoleEvent

`OCP\Contacts\Events\ContactInteractedWithEvent`

Added in version 19.

An event that allows apps to notify other components about an interaction between two users. This can be used to build better recommendations and suggestions in user interfaces. Emitters should add at least one identifier (uid, email, federated cloud ID) of the recipient of the interaction.

`OCP\DB\Events\AddMissingColumnsEvent`

Added in version 28.

Event to allow apps to register information about missing database columns This event will be dispatched for checking on the admin settings and when running occ db:add-missing-columns which will then create those columns

`OCP\DB\Events\AddMissingIndicesEvent`

Added in version 28.

Event to allow apps to register information about missing database indices This event will be dispatched for checking on the admin settings and when running occ db:add-missing-indices which will then create those indices

`OCP\DB\Events\AddMissingPrimaryKeyEvent`

Added in version 28.

Event to allow apps to register information about missing database primary keys This event will be dispatched for checking on the admin settings and when running occ db:add-missing-primary-keys which will then create those keys

`OCP\DirectEditing\RegisterDirectEditorEvent`

Added in version 18.

Event to allow to register the direct editor.

`OCP\EventDispatcher\GenericEvent`

Added in version 18.

Class GenericEvent convenience reimplementation of SymfonyComponentGenericEvent against OCPEventDispatcherEvent

`OCP\Federation\Events\TrustedServerRemovedEvent`

Added in version 25.

`OCP\Files\Cache\AbstractCacheEvent`

Added in version 22.

`OCP\Files\Cache\CacheEntryInsertedEvent`

Added in version 21.

Event for when an existing entry in the cache gets inserted

`OCP\Files\Cache\CacheEntryRemovedEvent`

Added in version 21.

Event for when an existing entry in the cache gets removed

`OCP\Files\Cache\CacheEntryUpdatedEvent`

Added in version 21.

Event for when an existing entry in the cache gets updated

`OCP\Files\Cache\CacheInsertEvent`

Added in version 16.

Event for when a new entry gets added to the cache

`OCP\Files\Cache\CacheUpdateEvent`

Added in version 16.

Event for when an existing entry in the cache gets updated

`OCP\Files\Events\BeforeDirectFileDownloadEvent`

Added in version 25.

This event is triggered when a user tries to download a file directly.

`OCP\Files\Events\BeforeFileScannedEvent`

Added in version 18.

`OCP\Files\Events\BeforeFolderScannedEvent`

Added in version 18.

`OCP\Files\Events\BeforeZipCreatedEvent`

Added in version 25.

`OCP\Files\Events\FileCacheUpdated`

Added in version 18.

`OCP\Files\Events\FileScannedEvent`

Added in version 18.

`OCP\Files\Events\FolderScannedEvent`

Added in version 18.

`OCP\Files\Events\InvalidateMountCacheEvent`

Added in version 24.

Used to notify the filesystem setup manager that the available mounts for a user have changed

`OCP\Files\Events\Node\BeforeNodeCopiedEvent`

Added in version 20.

`OCP\Files\Events\Node\BeforeNodeCreatedEvent`

Added in version 20.

`OCP\Files\Events\Node\BeforeNodeDeletedEvent`

Added in version 20.

`OCP\Files\Events\Node\BeforeNodeReadEvent`

Added in version 20.

`OCP\Files\Events\Node\BeforeNodeRenamedEvent`

Added in version 20.

`OCP\Files\Events\Node\BeforeNodeTouchedEvent`

Added in version 20.

`OCP\Files\Events\Node\BeforeNodeWrittenEvent`

Added in version 20.

`OCP\Files\Events\Node\FilesystemTornDownEvent`

Added in version 24.

Event fired after the filesystem has been torn down

`OCP\Files\Events\Node\NodeCopiedEvent`

Added in version 20.

`OCP\Files\Events\Node\NodeCreatedEvent`

Added in version 20.

`OCP\Files\Events\Node\NodeDeletedEvent`

Added in version 20.

`OCP\Files\Events\Node\NodeRenamedEvent`

Added in version 20.

`OCP\Files\Events\Node\NodeTouchedEvent`

Added in version 20.

`OCP\Files\Events\Node\NodeWrittenEvent`

Added in version 20.

`OCP\Files\Events\NodeAddedToCache`

Added in version 18.

`OCP\Files\Events\NodeAddedToFavorite`

Added in version 28.

`OCP\Files\Events\NodeRemovedFromCache`

Added in version 18.

`OCP\Files\Events\NodeRemovedFromFavorite`

Added in version 28.

`OCP\Files\Template\BeforeGetTemplatesEvent`

Added in version 30.

`OCP\Files\Template\FileCreatedFromTemplateEvent`

Added in version 21.

`OCP\Files\Template\RegisterTemplateCreatorEvent`

Added in version 30.

`OCP\FilesMetadata\Event\MetadataBackgroundEvent`

Added in version 28.

MetadataBackgroundEvent is an event similar to MetadataLiveEvent but dispatched on a background thread instead of live thread. Meaning there is no limit to the time required for the generation of your metadata.

`OCP\FilesMetadata\Event\MetadataLiveEvent`

Added in version 28.

MetadataLiveEvent is an event initiated when a file is created or updated. The app contains the Node related to the created/updated file, and a FilesMetadata that already contains the currently known metadata.

Setting new metadata, or modifying already existing metadata with different value, will trigger the save of the metadata in the database.

`OCP\FilesMetadata\Event\MetadataNamedEvent`

Added in version 28.

MetadataNamedEvent is an event similar to MetadataBackgroundEvent completed with a target name, used to limit the refresh of metadata only listeners capable of filtering themselves out. Meaning that when using this event, your app must implement a filter on the event’s registered name returned by getName()

This event is mostly triggered when a registered name is added to the files scan: i.e. ./occ files:scan –generate-metadata [name]

`OCP\Group\Events\BeforeGroupChangedEvent`

Added in version 26.

`OCP\Group\Events\BeforeGroupCreatedEvent`

Added in version 18.

`OCP\Group\Events\BeforeGroupDeletedEvent`

Added in version 18.

`OCP\Group\Events\BeforeUserAddedEvent`

Added in version 18.

`OCP\Group\Events\BeforeUserRemovedEvent`

Added in version 18.

`OCP\Group\Events\GroupChangedEvent`

Added in version 26.

`OCP\Group\Events\GroupCreatedEvent`

Added in version 18.

`OCP\Group\Events\GroupDeletedEvent`

Added in version 18.

`OCP\Group\Events\SubAdminAddedEvent`

Added in version 21.

`OCP\Group\Events\SubAdminRemovedEvent`

Added in version 21.

`OCP\Group\Events\UserAddedEvent`

Added in version 18.

`OCP\Group\Events\UserRemovedEvent`

Added in version 18.

`OCP\Log\Audit\CriticalActionPerformedEvent`

Added in version 22.

Emitted when the admin_audit app should log an entry

`OCP\Log\BeforeMessageLoggedEvent`

Added in version 28.

Even for when a log item is being logged

`OCP\Mail\Events\BeforeMessageSent`

Added in version 19.

Emitted before a system mail is sent. It can be used to alter the message.

`OCP\OCM\Events\ResourceTypeRegisterEvent`

Added in version 28.

Use this event to register additional OCM resources before the API returns them in the OCM provider list and capability

`OCP\Preview\BeforePreviewFetchedEvent`

Added in version 25.0.1.

Changed in version 28.0.0: the constructor arguments $width, $height, $crop and $mode are no longer nullable.

Emitted before a file preview is being fetched. It can be used to block preview rendering by throwing a OCP\Files\NotFoundException

`OCP\Profile\BeforeTemplateRenderedEvent`

Added in version 25.

Emitted before the rendering step of the public profile page happens.

`OCP\SabrePluginEvent`

Added in version 8.2.

`OCP\Security\CSP\AddContentSecurityPolicyEvent`

Added in version 17.

Allows to inject something into the default content policy. This is for example useful when you’re injecting Javascript code into a view belonging to another controller and cannot modify its Content-Security-Policy itself. Note that the adjustment is only applied to applications that use AppFramework controllers.

WARNING: Using this API incorrectly may make the instance more insecure. Do think twice before adding whitelisting resources. Please do also note that it is not possible to use the disallowXYZ functions.

`OCP\Security\Events\GenerateSecurePasswordEvent`

Added in version 18.

Event to request a secure password to be generated

`OCP\Security\Events\ValidatePasswordPolicyEvent`

Added in version 18.

This event can be emitted to request a validation of a password. If a password policy app is installed and the password is invalid, an OCPHintException will be thrown.

`OCP\Security\FeaturePolicy\AddFeaturePolicyEvent`

Added in version 17.

Event that allows to register a feature policy header to a request.

`OCP\Settings\Events\DeclarativeSettingsGetValueEvent`

Added in version 29.

`OCP\Settings\Events\DeclarativeSettingsRegisterFormEvent`

Added in version 29.

`OCP\Settings\Events\DeclarativeSettingsSetValueEvent`

Added in version 29.

`OCP\SpeechToText\Events\TranscriptionFailedEvent`

Added in version 27.

This Event is emitted if a transcription of a media file using a Speech-To-Text provider failed

`OCP\SpeechToText\Events\TranscriptionSuccessfulEvent`

Added in version 27.

This Event is emitted when a transcription of a media file happened successfully

`OCP\SystemTag\ManagerEvent`

Added in version 9.

Class ManagerEvent

`OCP\SystemTag\MapperEvent`

Added in version 9.

Class MapperEvent

`OCP\SystemTag\SystemTagsEntityEvent`

Added in version 9.1.

Changed in version 28.0.0: Dispatched as a typed event

Class SystemTagsEntityEvent

`OCP\TaskProcessing\Events\TaskFailedEvent`

Added in version 30.

`OCP\TaskProcessing\Events\TaskSuccessfulEvent`

Added in version 30.

`OCP\TextProcessing\Events\TaskFailedEvent`

Added in version 27.1.

`OCP\TextProcessing\Events\TaskSuccessfulEvent`

Added in version 27.1.

`OCP\TextToImage\Events\TaskFailedEvent`

Added in version 28.

`OCP\TextToImage\Events\TaskSuccessfulEvent`

Added in version 28.

`OCP\User\Events\BeforePasswordUpdatedEvent`

Added in version 18.

Emitted before the user password is updated.

`OCP\User\Events\BeforeUserCreatedEvent`

Added in version 18.

Emitted before a new user is created on the back-end.

`OCP\User\Events\BeforeUserDeletedEvent`

Added in version 18.

`OCP\User\Events\BeforeUserLoggedInEvent`

Added in version 18.

`OCP\User\Events\BeforeUserLoggedInWithCookieEvent`

Added in version 18.

Emitted before a user is logged in via remember-me cookies.

`OCP\User\Events\BeforeUserLoggedOutEvent`

Added in version 18.

Emitted before a user is logged out.

`OCP\User\Events\OutOfOfficeChangedEvent`

Added in version 28.

Emitted when a user’s out-of-office period has changed

`OCP\User\Events\OutOfOfficeClearedEvent`

Added in version 28.

Emitted when a user’s out-of-office period is cleared

`OCP\User\Events\OutOfOfficeEndedEvent`

Added in version 28.

Emitted when a user’s out-of-office period ended

`OCP\User\Events\OutOfOfficeScheduledEvent`

Added in version 28.

Emitted when a user’s out-of-office period is scheduled

`OCP\User\Events\OutOfOfficeStartedEvent`

Added in version 28.

Emitted when a user’s out-of-office period started

`OCP\User\Events\PasswordUpdatedEvent`

Added in version 18.

Emitted when the user password has been updated.

`OCP\User\Events\PostLoginEvent`

Added in version 18.

`OCP\User\Events\UserChangedEvent`

Added in version 18.

`OCP\User\Events\UserCreatedEvent`

Added in version 18.

Emitted when a new user has been created on the back-end.

`OCP\User\Events\UserDeletedEvent`

Added in version 18.

`OCP\User\Events\UserFirstTimeLoggedInEvent`

Added in version 28.

`OCP\User\Events\UserLiveStatusEvent`

Added in version 20.

`OCP\User\Events\UserLoggedInEvent`

Added in version 18.

`OCP\User\Events\UserLoggedInWithCookieEvent`

Added in version 18.

Emitted when a user has been successfully logged in via remember-me cookies.

`OCP\User\Events\UserLoggedOutEvent`

Added in version 18.

Emitted when a user has been logged out successfully.

`OCP\User\GetQuotaEvent`

Added in version 20.

Event to allow apps to

`OCP\WorkflowEngine\Events\LoadSettingsScriptsEvent`

Added in version 20.

Emitted when the workflow engine settings page is loaded.

`OCP\WorkflowEngine\Events\RegisterChecksEvent`

Added in version 18.

`OCP\WorkflowEngine\Events\RegisterEntitiesEvent`

Added in version 18.

`OCP\WorkflowEngine\Events\RegisterOperationsEvent`

Added in version 18.

Hooks

Deprecated since version 18: Use the OCP event dispatcher instead.

Hooks are used to execute code before or after an event has occurred. This is for instance useful to run cleanup code after users, groups or files have been deleted. Hooks should be registered in the app.php:

<?php
namespace OCA\MyApp\AppInfo;

$app = new Application();
$app->getContainer()->query('UserHooks')->register();

The hook logic should be in a separate class that is being registered in the App constructor:

<?php

namespace OCA\MyApp\AppInfo;

use \OCP\AppFramework\App;

use \OCA\MyApp\Hooks\UserHooks;


class Application extends App {

    public function __construct(array $urlParams=array()){
        parent::__construct('myapp', $urlParams);

        $container = $this->getContainer();

        /**
         * Controllers
         */
        $container->registerService('UserHooks', function($c) {
            return new UserHooks(
                $c->get(\OCP\IUserManager::class)
            );
        });
    }
}

<?php

namespace OCA\MyApp\Hooks;

use OCP\IUserManager;

class UserHooks {

    private $userManager;

    public function __construct(IUserManager $userManager){
        $this->userManager = $userManager;
    }

    public function register() {
        $callback = function($user) {
            // your code that executes before $user is deleted
        };
        $this->userManager->listen('\OC\User', 'preDelete', $callback);
    }

}

Available hooks

The scope is the first parameter that is passed to the listen method, the second parameter is the method and the third one the callback that should be executed once the hook is being called, e.g.:

<?php

// listen on user predelete
$callback = function($user) {
    // your code that executes before $user is deleted
};
$userManager->listen('\OC\User', 'preDelete', $callback);

Hooks can also be removed by using the removeListener method on the object:

<?php

// delete previous callback
$userManager->removeListener(null, null, $callback);

The following hooks are available:

Session

Injectable from the ServerContainer with the \OCP\IUserSession service.

Hooks available in scope \OC\User:

preSetPassword (\OC\User\User $user, string $password, string $recoverPassword)
postSetPassword (\OC\User\User $user, string $password, string $recoverPassword)
changeUser (\OC\User\User $user, string $feature, string $value)
preDelete (\OC\User\User $user)
postDelete (\OC\User\User $user)
preCreateUser (string $uid, string $password)
postCreateUser (\OC\User\User $user)
preLogin (string $user, string $password)
postLogin (\OC\User\User $user, string $password)
logout ()

UserManager

Injectable from the ServerContainer with the \OCP\IUserManager service.

Hooks available in scope \OC\User:

preSetPassword (\OC\User\User $user, string $password, string $recoverPassword)
postSetPassword (\OC\User\User $user, string $password, string $recoverPassword)
preDelete (\OC\User\User $user)
postDelete (\OC\User\User $user)
preCreateUser (string $uid, string $password)
postCreateUser (\OC\User\User $user, string $password)

GroupManager

Hooks available in scope \OC\Group:

preAddUser (\OC\Group\Group $group, \OC\User\User $user)
postAddUser (\OC\Group\Group $group, \OC\User\User $user)
preRemoveUser (\OC\Group\Group $group, \OC\User\User $user)
postRemoveUser (\OC\Group\Group $group, \OC\User\User $user)
preDelete (\OC\Group\Group $group)
postDelete (\OC\Group\Group $group)
preCreate (string $groupId)
postCreate (\OC\Group\Group $group)

Filesystem root

Injectable from the ServerContainer by calling the method getRootFolder(), getUserFolder() or getAppFolder().

To enable these events for your app you should add the following to your info.xml file:

<types>
    <filesystem/>
</types>

Filesystem hooks available in scope \OC\Files:

preWrite (\OCP\Files\Node $node)
postWrite (\OCP\Files\Node $node)
preCreate (\OCP\Files\Node $node)
postCreate (\OCP\Files\Node $node)
preDelete (\OCP\Files\Node $node)
postDelete (\OCP\Files\Node $node)
preTouch (\OCP\Files\Node $node, int $mtime)
postTouch (\OCP\Files\Node $node)
preCopy (\OCP\Files\Node $source, \OCP\Files\Node $target)
postCopy (\OCP\Files\Node $source, \OCP\Files\Node $target)
preRename (\OCP\Files\Node $source, \OCP\Files\Node $target)
postRename (\OCP\Files\Node $source, \OCP\Files\Node $target)

Filesystem scanner

Filesystem scanner hooks available in scope \OC\Files\Utils\Scanner:

scanFile (string $absolutePath)
scanFolder (string $absolutePath)
postScanFile (string $absolutePath)
postScanFolder (string $absolutePath)

Public emitter

Deprecated since version 18: Use the OCP event dispatcher instead.

tbd

Events

Overview

OCP event dispatcher

Naming scheme

Writing events

Writing a listener

Listener callbacks

Listener classes

Available Events

\OCA\DAV\Events\AddressBookCreatedEvent

\OCA\DAV\Events\AddressBookDeletedEvent

\OCA\DAV\Events\AddressBookShareUpdatedEvent

\OCA\DAV\Events\AddressBookUpdatedEvent

\OCA\DAV\Events\CachedCalendarObjectCreatedEvent

\OCA\DAV\Events\CachedCalendarObjectDeletedEvent

\OCA\DAV\Events\CachedCalendarObjectUpdatedEvent

\OCA\DAV\Events\CalendarCreatedEvent

\OCA\DAV\Events\CalendarDeletedEvent

\OCA\DAV\Events\CalendarObjectCreatedEvent

\OCA\DAV\Events\CalendarObjectDeletedEvent

\OCA\DAV\Events\CalendarObjectUpdatedEvent

\OCA\DAV\Events\CalendarPublishedEvent

\OCA\DAV\Events\CalendarShareUpdatedEvent

\OCA\DAV\Events\CalendarUnpublishedEvent

\OCA\DAV\Events\CalendarUpdatedEvent

\OCA\DAV\Events\CardCreatedEvent

\OCA\DAV\Events\CardDeletedEvent

\OCA\DAV\Events\CardUpdatedEvent

OCA\DAV\Events\SabrePluginAddEvent

\OCA\DAV\Events\SabrePluginAuthInitEvent

\OCA\DAV\Events\SubscriptionCreatedEvent

\OCA\DAV\Events\SubscriptionDeletedEvent

\OCA\DAV\Events\SubscriptionUpdatedEvent

\OCA\FederatedFileSharing\Events\FederatedShareAddedEvent

\OCA\Files\Event\LoadAdditionalScriptsEvent

\OCA\Files_Sharing\Event\BeforeTemplateRenderedEvent

\OCA\Files_Trashbin\Events\MoveToTrashEvent

\OCA\Settings\Events\BeforeTemplateRenderedEvent

\OCA\User_LDAP\Events\GroupBackendRegistered

\OCA\User_LDAP\Events\UserBackendRegistered

\OCA\Viewer\Event\LoadViewer

OCP\Accounts\UserUpdatedEvent

OCP\App\Events\AppDisableEvent

OCP\App\Events\AppEnableEvent

OCP\App\Events\AppUpdateEvent

OCP\App\ManagerEvent

OCP\AppFramework\Http\Events\BeforeLoginTemplateRenderedEvent

OCP\AppFramework\Http\Events\BeforeTemplateRenderedEvent

OCP\Authentication\Events\AnyLoginFailedEvent

OCP\Authentication\Events\LoginFailedEvent

OCP\Authentication\TwoFactorAuth\RegistryEvent

OCP\Authentication\TwoFactorAuth\TwoFactorProviderChallengeFailed

OCP\Authentication\TwoFactorAuth\TwoFactorProviderChallengePassed

OCP\Authentication\TwoFactorAuth\TwoFactorProviderDisabled

OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserDisabled

OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserEnabled

OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserRegistered

OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserUnregistered

OCP\Authentication\TwoFactorAuth\TwoFactorProviderUserDeleted

OCP\BeforeSabrePubliclyLoadedEvent

OCP\Collaboration\AutoComplete\AutoCompleteEvent

OCP\Collaboration\AutoComplete\AutoCompleteFilterEvent

OCP\Collaboration\Reference\RenderReferenceEvent

OCP\Collaboration\Resources\LoadAdditionalScriptsEvent

OCP\Comments\CommentsEntityEvent

OCP\Comments\CommentsEvent

OCP\Config\BeforePreferenceDeletedEvent

OCP\Config\BeforePreferenceSetEvent

OCP\Console\ConsoleEvent

OCP\Contacts\Events\ContactInteractedWithEvent

OCP\DB\Events\AddMissingColumnsEvent

OCP\DB\Events\AddMissingIndicesEvent

OCP\DB\Events\AddMissingPrimaryKeyEvent

OCP\DirectEditing\RegisterDirectEditorEvent

OCP\EventDispatcher\GenericEvent

OCP\Federation\Events\TrustedServerRemovedEvent

OCP\Files\Cache\AbstractCacheEvent

OCP\Files\Cache\CacheEntryInsertedEvent

OCP\Files\Cache\CacheEntryRemovedEvent

OCP\Files\Cache\CacheEntryUpdatedEvent

`\OCA\DAV\Events\AddressBookCreatedEvent`

`\OCA\DAV\Events\AddressBookDeletedEvent`

`\OCA\DAV\Events\AddressBookShareUpdatedEvent`

`\OCA\DAV\Events\AddressBookUpdatedEvent`

`\OCA\DAV\Events\CachedCalendarObjectCreatedEvent`

`\OCA\DAV\Events\CachedCalendarObjectDeletedEvent`

`\OCA\DAV\Events\CachedCalendarObjectUpdatedEvent`

`\OCA\DAV\Events\CalendarCreatedEvent`

`\OCA\DAV\Events\CalendarDeletedEvent`

`\OCA\DAV\Events\CalendarObjectCreatedEvent`

`\OCA\DAV\Events\CalendarObjectDeletedEvent`

`\OCA\DAV\Events\CalendarObjectUpdatedEvent`

`\OCA\DAV\Events\CalendarPublishedEvent`

`\OCA\DAV\Events\CalendarShareUpdatedEvent`

`\OCA\DAV\Events\CalendarUnpublishedEvent`

`\OCA\DAV\Events\CalendarUpdatedEvent`

`\OCA\DAV\Events\CardCreatedEvent`

`\OCA\DAV\Events\CardDeletedEvent`

`\OCA\DAV\Events\CardUpdatedEvent`

`OCA\DAV\Events\SabrePluginAddEvent`

`\OCA\DAV\Events\SabrePluginAuthInitEvent`

`\OCA\DAV\Events\SubscriptionCreatedEvent`

`\OCA\DAV\Events\SubscriptionDeletedEvent`

`\OCA\DAV\Events\SubscriptionUpdatedEvent`

`\OCA\FederatedFileSharing\Events\FederatedShareAddedEvent`

`\OCA\Files\Event\LoadAdditionalScriptsEvent`

`\OCA\Files_Sharing\Event\BeforeTemplateRenderedEvent`

`\OCA\Files_Trashbin\Events\MoveToTrashEvent`

`\OCA\Settings\Events\BeforeTemplateRenderedEvent`

`\OCA\User_LDAP\Events\GroupBackendRegistered`

`\OCA\User_LDAP\Events\UserBackendRegistered`

`\OCA\Viewer\Event\LoadViewer`

`OCP\Accounts\UserUpdatedEvent`

`OCP\App\Events\AppDisableEvent`

`OCP\App\Events\AppEnableEvent`

`OCP\App\Events\AppUpdateEvent`

`OCP\App\ManagerEvent`

`OCP\AppFramework\Http\Events\BeforeLoginTemplateRenderedEvent`

`OCP\AppFramework\Http\Events\BeforeTemplateRenderedEvent`

`OCP\Authentication\Events\AnyLoginFailedEvent`

`OCP\Authentication\Events\LoginFailedEvent`

`OCP\Authentication\TwoFactorAuth\RegistryEvent`

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderChallengeFailed`

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderChallengePassed`

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderDisabled`

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserDisabled`

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserEnabled`

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserRegistered`

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserUnregistered`

`OCP\Authentication\TwoFactorAuth\TwoFactorProviderUserDeleted`

`OCP\BeforeSabrePubliclyLoadedEvent`

`OCP\Collaboration\AutoComplete\AutoCompleteEvent`

`OCP\Collaboration\AutoComplete\AutoCompleteFilterEvent`

`OCP\Collaboration\Reference\RenderReferenceEvent`

`OCP\Collaboration\Resources\LoadAdditionalScriptsEvent`

`OCP\Comments\CommentsEntityEvent`

`OCP\Comments\CommentsEvent`

`OCP\Config\BeforePreferenceDeletedEvent`

`OCP\Config\BeforePreferenceSetEvent`

`OCP\Console\ConsoleEvent`

`OCP\Contacts\Events\ContactInteractedWithEvent`

`OCP\DB\Events\AddMissingColumnsEvent`

`OCP\DB\Events\AddMissingIndicesEvent`

`OCP\DB\Events\AddMissingPrimaryKeyEvent`

`OCP\DirectEditing\RegisterDirectEditorEvent`

`OCP\EventDispatcher\GenericEvent`

`OCP\Federation\Events\TrustedServerRemovedEvent`

`OCP\Files\Cache\AbstractCacheEvent`

`OCP\Files\Cache\CacheEntryInsertedEvent`

`OCP\Files\Cache\CacheEntryRemovedEvent`

`OCP\Files\Cache\CacheEntryUpdatedEvent`

`OCP\Files\Cache\CacheInsertEvent`

`OCP\Files\Cache\CacheUpdateEvent`

`OCP\Files\Events\BeforeDirectFileDownloadEvent`

`OCP\Files\Events\BeforeFileScannedEvent`

`OCP\Files\Events\BeforeFolderScannedEvent`

`OCP\Files\Events\BeforeZipCreatedEvent`

`OCP\Files\Events\FileCacheUpdated`

`OCP\Files\Events\FileScannedEvent`

`OCP\Files\Events\FolderScannedEvent`