Events

Same name in other branches
  1. 9 core/core.api.php \events
  2. 8.9.x core/core.api.php \events
  3. 11.x core/core.api.php \events

Overview of event dispatch and subscribing

Introduction and terminology

Events allow different components of the system to interact and communicate with each other. One system component dispatches the event at an appropriate time; many events are dispatched by Drupal core and the Symfony event system in every request. Other system components can register as event subscribers; when an event is dispatched, a method is called on each registered subscriber, allowing each one to react. For more on the general concept of events, see http://symfony.com/doc/current/components/event_dispatcher/introduction…

Dispatching events

To dispatch an event, call the \Symfony\Contracts\EventDispatcher\EventDispatcherInterface::dispatch() method on the 'event_dispatcher' service (see the Services topic for more information about how to interact with services). The first argument is the unique event name, which you should normally define as a constant in a separate static class (see \Symfony\Component\HttpKernel\KernelEvents and \Drupal\Core\Config\ConfigEvents for examples). The second argument is a \Drupal\Component\EventDispatcher\Event object; normally you will need to extend this class, so that your event class can provide data to the event subscribers.

Registering event subscribers

Here are the steps to register an event subscriber:

  • Define a service in your module, tagged with 'event_subscriber' (see the Services topic for instructions).
  • Define a class for your subscriber service that implements \Symfony\Component\EventDispatcher\EventSubscriberInterface
  • In your class, the getSubscribedEvents method returns a list of the events this class is subscribed to, and which methods on the class should be called for each one. Example:

  public static function getSubscribedEvents() {
    // Subscribe to kernel terminate with priority 100.
    $events[KernelEvents::TERMINATE][] = ['onTerminate', 100];
    // Subscribe to kernel request with default priority of 0.
    $events[KernelEvents::REQUEST][] = ['onRequest'];
    return $events;
  }
  
  • Write the methods that respond to the events; each one receives the event object provided in the dispatch as its one argument. In the above example, you would need to write onTerminate() and onRequest() methods.

Note that in your getSubscribedEvents() method, you can optionally set the priority of your event subscriber (see terminate example above). Event subscribers with higher priority numbers get executed first; the default priority is zero. If two event subscribers for the same event have the same priority, the one defined in a module with a lower module weight will fire first. Subscribers defined in the same services file are fired in definition order. If order matters defining a priority is strongly advised instead of relying on these two tie breaker rules as they might change in a minor release.

Parent topics

File

core/core.api.php, line 2559

Constants

Title Sort descending Deprecated File name Summary
AccountEvents::SET_USER core/lib/Drupal/Core/Session/AccountEvents.php Name of the event fired when the current user is set.
BlockContentEvents::BLOCK_CONTENT_GET_DEPENDENCY core/modules/block_content/src/BlockContentEvents.php Name of the event when getting the dependency of a non-reusable block.
ConfigCollectionEvents::COLLECTION_INFO core/lib/Drupal/Core/Config/ConfigCollectionEvents.php Event dispatched to collect information on all config collections.
ConfigCollectionEvents::DELETE_IN_COLLECTION core/lib/Drupal/Core/Config/ConfigCollectionEvents.php Event dispatched when deleting configuration not in the default collection.
ConfigCollectionEvents::RENAME_IN_COLLECTION core/lib/Drupal/Core/Config/ConfigCollectionEvents.php Event dispatched when renaming configuration not in the default collection.
ConfigCollectionEvents::SAVE_IN_COLLECTION core/lib/Drupal/Core/Config/ConfigCollectionEvents.php Event dispatched when saving configuration not in the default collection.
ConfigEvents::COLLECTION_INFO Deprecated core/lib/Drupal/Core/Config/ConfigEvents.php Name of event fired to collect information on all config collections.
ConfigEvents::DELETE core/lib/Drupal/Core/Config/ConfigEvents.php Name of the event fired when deleting a configuration object.
ConfigEvents::IMPORT core/lib/Drupal/Core/Config/ConfigEvents.php Name of the event fired when importing configuration to target storage.
ConfigEvents::IMPORT_VALIDATE core/lib/Drupal/Core/Config/ConfigEvents.php Name of the event fired when validating imported configuration.
ConfigEvents::RENAME core/lib/Drupal/Core/Config/ConfigEvents.php Name of the event fired when renaming a configuration object.
ConfigEvents::SAVE core/lib/Drupal/Core/Config/ConfigEvents.php Name of the event fired when saving a configuration object.
ConfigEvents::STORAGE_TRANSFORM_EXPORT core/lib/Drupal/Core/Config/ConfigEvents.php Name of the event fired when the export storage is used.
ConfigEvents::STORAGE_TRANSFORM_IMPORT core/lib/Drupal/Core/Config/ConfigEvents.php Name of the event fired just before importing configuration.
EntityTypeEvents::CREATE core/lib/Drupal/Core/Entity/EntityTypeEvents.php The name of the event triggered when a new entity type is created.
EntityTypeEvents::DELETE core/lib/Drupal/Core/Entity/EntityTypeEvents.php The name of the event triggered when an existing entity type is deleted.
EntityTypeEvents::UPDATE core/lib/Drupal/Core/Entity/EntityTypeEvents.php The name of the event triggered when an existing entity type is updated.
FieldStorageDefinitionEvents::CREATE core/lib/Drupal/Core/Field/FieldStorageDefinitionEvents.php Name of the event triggered for field storage definition creation.
FieldStorageDefinitionEvents::DELETE core/lib/Drupal/Core/Field/FieldStorageDefinitionEvents.php Name of the event triggered for field storage definition deletion.
FieldStorageDefinitionEvents::UPDATE core/lib/Drupal/Core/Field/FieldStorageDefinitionEvents.php Name of the event triggered for field storage definition update.
LanguageConfigOverrideEvents::DELETE_OVERRIDE core/modules/language/src/Config/LanguageConfigOverrideEvents.php The name of the event fired when deleting the configuration override.
LanguageConfigOverrideEvents::SAVE_OVERRIDE core/modules/language/src/Config/LanguageConfigOverrideEvents.php The name of the event fired when saving the configuration override.
LayoutBuilderEvents::SECTION_COMPONENT_BUILD_RENDER_ARRAY core/modules/layout_builder/src/LayoutBuilderEvents.php Name of the event fired when a component's render array is built.
LocaleEvents::SAVE_TRANSLATION core/modules/locale/src/LocaleEvents.php The name of the event fired when saving a translated string.
MigrateEvents::IDMAP_MESSAGE core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired when saving a message to the ID map.
MigrateEvents::MAP_DELETE core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired when removing an entry from a migration's map.
MigrateEvents::MAP_SAVE core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired when saving to a migration's map.
MigrateEvents::POST_IMPORT core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired when finishing a migration import operation.
MigrateEvents::POST_ROLLBACK core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired when finishing a migration rollback operation.
MigrateEvents::POST_ROW_DELETE core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired just after a single item has been deleted.
MigrateEvents::POST_ROW_SAVE core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired just after a single item has been imported.
MigrateEvents::PRE_IMPORT core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired when beginning a migration import operation.
MigrateEvents::PRE_ROLLBACK core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired when beginning a migration rollback operation.
MigrateEvents::PRE_ROW_DELETE core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired when about to delete a single item.
MigrateEvents::PRE_ROW_SAVE core/modules/migrate/src/Event/MigrateEvents.php Name of the event fired when about to import a single item.
RenderEvents::SELECT_PAGE_DISPLAY_VARIANT core/lib/Drupal/Core/Render/RenderEvents.php Name of the event when selecting a page display variant to use.
RoutingEvents::ALTER core/lib/Drupal/Core/Routing/RoutingEvents.php Name of the event fired during route collection to allow changes to routes.
RoutingEvents::DYNAMIC core/lib/Drupal/Core/Routing/RoutingEvents.php Name of the event fired during route collection to allow new routes.
RoutingEvents::FINISHED core/lib/Drupal/Core/Routing/RoutingEvents.php Name of the event fired to indicate route building has ended.
UserEvents::FLOOD_BLOCKED_IP core/modules/user/src/Event/UserEvents.php The name of the event fired when a login is blocked by flood control.
UserEvents::FLOOD_BLOCKED_USER core/modules/user/src/Event/UserEvents.php The name of the event fired when a login is blocked by flood control.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.