Example: Events
Same name in other branches
- 4.0.x modules/events_example/events_example.module \events_example
Demonstrates subscribing to, and dispatching, events.
Events allow for different components of the system to interact and communicate with each other. Modules can either dispatch events, subscribe to events, or both.
Subscribing to an event allows a module to declare that it would like to be notified anytime a specific event happens. A module can subscribe to any number of events, and can even subscribe to the same event more than once.
Dispatching an event allows a module, or Drupal core subsystem, to notify any registered subscribers that a specific event has just taken place. When an event is dispatched the registered code for each subscriber is executed. For example, whenever a configuration entity is updated the Configuration API dispatches a new event allowing all subscribers to react to the change.
This allows modules to extend other systems without the need to modify the original code.
Each event has a unique string name. This string is often referred to as "the event", or "the event name". This string is how you identify which event(s) you are interested in. A complete list of events dispatched by core is available at https://api.drupal.org/api/drupal/core%21core.api.php/group/events/
Drupal's event system is an extension of the Symfony EventDispatcher component, and implements the Mediator pattern.
Subscribing to an event requires:
- Defining a service in your module, tagged with 'event_subscriber'.
- Defining a class for your subscriber service that implements \Symfony\Component\EventDispatcher\EventSubscriberInterface
- Using the getSubscribedEvents method to return a list of the events you want to subscribe to, and which methods on the class should be called for each one.
For an example of subscribing to an event see the events_example.services.yml file. And the \Drupal\events_example\EventSubscriber\EventsExampleSubscriber class.
Dispatching an event requires:
- Defining a new static class with constants for unique event names and documentation. Example: \Drupal\events_exampl\Event\IncidentEvents
- Defining an event class that extends \Symfony\Component\EventDispatcher\Event Example: \Drupal\events_example\Event\IncidentReportEvent
- Use the 'event_dispatcher' service in your code to dispatch an event and provide an event object as an argument. Example: \Drupal\events_example\Form\EventsExampleForm::submitForm()
This example code is based off of the article Responding to Events in Drupal 8.
See also
\Symfony\Component\EventDispatcher\EventDispatcherInterface
\Drupal\Component\EventDispatcher\ContainerAwareEventDispatcher
Parent topics
File
-
modules/
events_example/ events_example.module, line 8
Classes
| Title Sort descending | File name | Summary |
|---|---|---|
| EventsExampleForm | modules/ |
Implements the SimpleForm form controller. |
| EventsExampleServiceTest | modules/ |
Test to ensure 'events_example_subscriber' service is reachable. |
| EventsExampleSubscriber | modules/ |
Subscribe to IncidentEvents::NEW_REPORT events and react to new reports. |
| EventsExampleTest | modules/ |
Test the functionality of the Events Example module. |
| IncidentEvents | modules/ |
Defines events for the events_example module. |
| IncidentReportEvent | modules/ |
Wraps a incident report event for event subscribers. |