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

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 updates 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_Sharing\Event\BeforeTemplateRenderedEvent

Added in version 20.

Emitted before the rendering step of the public share page happens. The event holds a flag that specifies if it is the authentication page of a public share.

\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.

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\AppsLoadedEvent

Added in version 35.

This event is triggered when all enabled apps are loaded and available. So this can be used if your app needs to interact with other apps, which is not guaranteed to be available during the app bootstrapping phase.

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\Events\TokenInvalidatedEvent

Added in version 32.

Emitted when an authentication token is invalidated

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\Calendar\Events\CalendarObjectCreatedEvent

Added in version 32.

OCP\Calendar\Events\CalendarObjectDeletedEvent

Added in version 32.

OCP\Calendar\Events\CalendarObjectMovedEvent

Added in version 32.

OCP\Calendar\Events\CalendarObjectMovedToTrashEvent

Added in version 32.

OCP\Calendar\Events\CalendarObjectRestoredEvent

Added in version 32.

OCP\Calendar\Events\CalendarObjectUpdatedEvent

Added in version 32.

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: Dispatched as a typed event

Class CommentsEntityEvent

OCP\Comments\CommentsEvent

Added in version 9: In the future, once the deprecated methods are removed, this class will be abstract.

Class CommentsEvent

OCP\Comments\Events\BeforeCommentUpdatedEvent

Added in version 33.

Class BeforeCommentAddedEvent

OCP\Comments\Events\CommentAddedEvent

Added in version 33.

Class CommentAddedEvent

OCP\Comments\Events\CommentDeletedEvent

Added in version 33.

Class CommentRemovedEvent

OCP\Comments\Events\CommentUpdatedEvent

Added in version 33.

Class CommentUpdatedEvent

OCP\Config\BeforeAppConfigDeletedEvent

Added in version 36.

Emitted before an admin deletes an app config value via occ or the provisioning API. Listeners can refuse the change with setValid(false).

OCP\Config\BeforeAppConfigSetEvent

Added in version 36.

Emitted before an admin sets an app config value via occ or the provisioning API. Listeners can refuse the change with setValid(false).

OCP\Config\BeforePreferenceDeletedEvent

Added in version 25.

Dispatched before a user preference is deleted via the preferences API; the deletion is rejected unless a listener marks it valid.

OCP\Config\BeforePreferenceSetEvent

Added in version 25.

Dispatched before a user preference is set via the preferences API; the change is rejected unless a listener marks it valid.

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\ContextChat\Events\ContentProviderRegisterEvent

Added in version 32.

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 re-implementation of SymfonyComponentGenericEvent against OCPEventDispatcherEvent

OCP\Federation\Events\TrustedServerRemovedEvent

Added in version 25.

OCP\Files\Cache\AbstractCacheEvent

Added in version 22.

OCP\Files\Cache\CacheEntriesRemovedEvent

Added in version 34.

Meta-event wrapping multiple CacheEntryRemovedEvent for when an existing entry in the cache gets removed.

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 Prefer using CacheEntriesRemovedEvent as it is more efficient when deleting multiple files at the same time.

OCP\Files\Cache\CacheEntryUpdatedEvent

Added in version 21.

Event for when an existing entry in the cache gets updated

OCP\Files\Config\Event\UserMountAddedEvent

Added in version 32.

Event emitted when a user mount was added.

OCP\Files\Config\Event\UserMountRemovedEvent

Added in version 32.

Event emitted when a user mount was removed.

OCP\Files\Config\Event\UserMountUpdatedEvent

Added in version 32.

Event emitted when a user mount was moved.

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\BeforeFileSystemSetupEvent

Added in version 31.

Event triggered before the file system is set up.

OCP\Files\Events\BeforeFolderScannedEvent

Added in version 18.

OCP\Files\Events\BeforeRemotePropfindEvent

Added in version 33.

This event is fired before a PROPFIND request is sent to remote WebDAV storage Used to extend the list of properties to request additional data from the remote server

OCP\Files\Events\BeforeZipCreatedEvent

Added in version 25.

This event is triggered before an archive is created when a user requested downloading a folder or multiple files. By setting successful to false the tar creation can be aborted and the download denied.

If allowsPartialArchive returns true, listeners should only block the archive creation if access to the entire directory or all files is denied. Single nodes can be excluded from the archive with addNodeFilter. Listeners can always block the whole archive with setSuccessful(false).

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\NodeOpenedEvent

Added in version 36.

A user opened a node in a client, as reported by that client. Unlike OCP\Files\Events\Node\BeforeNodeReadEvent, this is not dispatched when the content is read (sync, previews, downloads) but only when a client says the user actually opened it.

It is meant for statistics only, like recommending the files a user works with. Clients report it when they choose to, so it can be missing, repeated or sent for a node the user never looked at. Never use it for permissions, access control, auditing, or anything else that has to be reliable.

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\Events\UserHomeSetupEvent

Added in version 34.

Event triggered after the users home mount has been setup, before any other mounts are setup.

OCP\Files\ObjectStore\Events\BucketCreatedEvent

Added in version 33.

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\Install\Events\InstallationCompletedEvent

Added in version 33.

Emitted when the Nextcloud installation has been completed successfully. This event is dispatched after: - The database has been configured and migrations have run - The admin user has been created (if applicable) - Default apps have been installed - Background jobs have been configured - The system has been marked as installed

Apps can listen to this event to perform additional actions after installation, such as: - Sending notification emails - Triggering external APIs - Initializing app-specific data - Setting up integrations

OCP\Interaction\RestrictInteractionEvent

Added in version 34.0.2.

This event can be emitted to check if a user is allowed to perform an action, such that the receivers would become aware of the resources. If the resources have a distinction between an owner and a initiator, the event must be emitted for each separately. Emitters may omit one or multiple properties, if they are not known. Emitters must call OCP\Interaction\RestrictInteractionEvent::isInteractionRestricted() instead of dispatching the event manually, to ensure exception handling and audit logging is done correctly. Listeners may ignore any of the properties and only check the ones that are relevant to them. Listeners must throw an OCP\Interaction\InteractionRestrictedException, if they want to restrict the interaction.

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\Navigation\Events\LoadAdditionalEntriesEvent

Added in version 31.

OCP\OCM\Events\LocalOCMDiscoveryEvent

Added in version 33.

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

OCP\OCM\Events\OCMEndpointRequestEvent

Added in version 33.

Use this event to catch and manage incoming OCM request

OCP\OCM\Events\OCMNotificationReceivedEvent

Added in version 35.

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: the constructor arguments $width, $height, $crop and $mode are no longer nullable.

Changed in version 31: the constructor arguments $mimeType was added

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.

Changed in version 31: Provides getContext to apply different rules per password context, e.g. account or share passwords.

Event to request a secure password to be generated

OCP\Security\Events\ValidatePasswordPolicyEvent

Added in version 18.

Changed in version 31: Provides getContext to apply different rules per password context, e.g. account or share passwords.

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\Share\Events\BeforeShareCreatedEvent

Added in version 28.

OCP\Share\Events\BeforeShareDeletedEvent

Added in version 28.

OCP\Share\Events\ShareAcceptedEvent

Added in version 28.

OCP\Share\Events\ShareCreatedEvent

Added in version 18.

OCP\Share\Events\ShareDeletedEvent

Added in version 21.

OCP\Share\Events\ShareDeletedFromSelfEvent

Added in version 28.

OCP\Share\Events\ShareMovedEvent

Added in version 33.

OCP\Share\Events\ShareTransferredEvent

Added in version 33.

OCP\Share\Events\VerifyMountPointEvent

Added in version 19.

OCP\Share\ShareReview\Events\ShareReviewAccessCheckEvent

Added in version 34.0.2.

Authorization gate for deleting an app-managed share through a share-review app. Background: Apps such as Deck or Tables manage their own shares outside of the regular sharing backend (OCP\Share\IManager). They can expose those shares to a share-review app — a compliance tool that lets designated operators audit and revoke shares across all apps — by implementing OCP\Share\ShareReview\IShareReviewSource. When a share-review operator requests the deletion of such a share, the deletion is executed by the app that owns the share, not by the share-review app. The owning app has no way of knowing whether the acting user is actually authorized to perform share reviews — only the share-review app knows that. This event closes that gap: it lets the owning app ask “may the current user delete this share on behalf of a share review?” before deleting anything.

Dispatched by: the app that owns the share, i.e. the OCP\Share\ShareReview\IShareReviewSource implementation, at the beginning of its deleteShare() method:

public function deleteShare(string $shareId): bool {
    $event = new ShareReviewAccessCheckEvent('MyApp', $shareId);
    $this->dispatcher->dispatchTyped($event);
    if (!$event->isHandled() || !$event->isGranted()) {
        return false; // default-deny: no listener means no access
    }
    // ... actually delete the share ...
}

Listened to by: the share-review app. Its listener decides whether the current user is an authorized share-review operator (e.g. the app is enabled for the user) and answers with grantAccess() or denyAccess():

public function handle(Event $event): void {
    if (!$event instanceof ShareReviewAccessCheckEvent) {
        return;
    }
    if ($this->isShareReviewOperator()) {
        $event->grantAccess();
    } else {
        $event->denyAccess('User is not a share-review operator.');
    }
}

Apps that merely expose shares must not listen to this event; answering it is the responsibility of the share-review app that triggered the deletion.

Semantics:

  • Default-deny: if no listener responds (isHandled() is false, e.g. no share-review app is installed), the dispatcher must not delete the share.

  • Deny wins: once denyAccess() is called, further grantAccess() calls are ignored and propagation is stopped immediately.

  • Multiple grants are harmless; the last listener to deny is authoritative.

OCP\Share\ShareReview\RegisterShareReviewSourceEvent

Added in version 34.0.2.

Event dispatched by a share-review app to collect share sources from other apps. Listeners register the class name of their OCP\Share\ShareReview\IShareReviewSource implementation; the share-review app resolves it from the dependency injection container.

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\Events\TagCreatedEvent

Added in version 35.

Event triggered when creating a new tag.

OCP\SystemTag\Events\TagDeletedEvent

Added in version 35.

Event triggered when deleting a new tag.

OCP\SystemTag\Events\TagUpdatedEvent

Added in version 35.

Event triggered when updated a tag.

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: Dispatched as a typed event

Class SystemTagsEntityEvent

OCP\SystemTag\TagAssignedEvent

Added in version 32.

Event class for when a system tag is assigned to an object

OCP\SystemTag\TagUnassignedEvent

Added in version 32.

Event class for when a system tag is unassigned from an object

OCP\TaskProcessing\Events\GetTaskProcessingProvidersEvent

Added in version 32.

Event dispatched by the server to collect Task Processing Providers and custom Task Types from listeners (like AppAPI). Listeners should add their providers and task types using the addProvider() and addTaskType() methods.

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\BeforeUserIdUnassignedEvent

Added in version 31.

Emitted before removing the mapping between an external user and an internal userid

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\UserConfigChangedEvent

Added in version 33.

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\UserEnumerationFilterEvent

Added in version 31.0.14.

OCP\User\Events\UserFirstTimeLoggedInEvent

Added in version 28.

OCP\User\Events\UserIdAssignedEvent

Added in version 31.

Emitted by backends (like user_ldap) when a user created externally is mapped for the first time and assigned a userid

OCP\User\Events\UserIdUnassignedEvent

Added in version 31.

Emitted after removing the mapping between an external user and an internal userid

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 Bootstrapping process.

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