Overview of event dispatch and subscribing
Introduction and terminology
Events are part of the Symfony framework: they allow for different components of the system to interact and communicate with each other. Each event has a unique string name. One system component dispatches the event at an appropriate time; many events are dispatched by Drupal core and the Symfony framework 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\Component\EventDispatcher\EventDispatchInterface::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 \Symfony\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 function getSubscribedEvents() { // Subscribe to kernel terminate with priority 100. $events[KernelEvents::TERMINATE][] = array('onTerminate', 100); // Subscribe to kernel request with default priority of 0. $events[KernelEvents::REQUEST][] = array('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.
File
- core/core.api.php, line 2457
- Documentation landing page and topics, plus core library hooks.
Constants
Name | Location | Description |
---|---|---|
ConfigEvents::COLLECTION_INFO | 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. |
ConsoleEvents::COMMAND | vendor/symfony/console/ConsoleEvents.php | The COMMAND event allows you to attach listeners before any command is executed by the console. It also allows you to modify the command, input and output before they are handled to the command. |
ConsoleEvents::EXCEPTION | vendor/symfony/console/ConsoleEvents.php | The EXCEPTION event occurs when an uncaught exception appears. |
ConsoleEvents::TERMINATE | vendor/symfony/console/ConsoleEvents.php | The TERMINATE event allows you to attach listeners after a command is executed by the console. |
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. |
KernelEvents::CONTROLLER | vendor/symfony/http-kernel/KernelEvents.php | The CONTROLLER event occurs once a controller was found for handling a request. |
KernelEvents::EXCEPTION | vendor/symfony/http-kernel/KernelEvents.php | The EXCEPTION event occurs when an uncaught exception appears. |
KernelEvents::REQUEST | vendor/symfony/http-kernel/KernelEvents.php | The REQUEST event occurs at the very beginning of request dispatching. |
KernelEvents::RESPONSE | vendor/symfony/http-kernel/KernelEvents.php | The RESPONSE event occurs once a response was created for replying to a request. |
KernelEvents::TERMINATE | vendor/symfony/http-kernel/KernelEvents.php | The TERMINATE event occurs once a response was sent. |
KernelEvents::VIEW | vendor/symfony/http-kernel/KernelEvents.php | The VIEW event occurs when the return value of a controller is not a Response instance. |
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. |
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 idmap. |
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. |
Please login to continue.