Event dispatcher (PSR-14 events)

Dispatching an event

1. Create an event class.

   An event class is basically a plain PHP object with getters for immutable properties and setters for mutable properties. It contains a constructor for all properties:

   EXT:my_extension/Classes/Event/DoingThisAndThatEvent.php

   <?php
   
   declare(strict_types=1);
   
   namespace MyVendor\MyExtension\Event;
   
   final class DoingThisAndThatEvent
   {
       public function __construct(
           private string $mutableProperty,
           private readonly int $immutableProperty,
       ) {
       }
   
       public function getMutableProperty(): string
       {
           return $this->mutableProperty;
       }
   
       public function setMutableProperty(string $mutableProperty): void
       {
           $this->mutableProperty = $mutableProperty;
       }
   
       public function getImmutableProperty(): int
       {
           return $this->immutableProperty;
       }
   }
   

   Copied!

   Read more about implementing event classes.

2. Inject the event dispatcher

   If you are in a controller, the event dispatcher has already been injected, and in this case you can omit this step.

   If the event dispatcher is not yet available, you need to inject it:

   EXT:my_extension/Classes/SomeClass.php

   <?php
   
   declare(strict_types=1);
   
   namespace MyVendor\MyExtension;
   
   use Psr\EventDispatcher\EventDispatcherInterface;
   
   final class SomeClass
   {
       public function __construct(
           private readonly EventDispatcherInterface $eventDispatcher,
       ) {
       }
   }
   

   Copied!

3. Dispatch the event

   Create an event object with the data that should be passed to the listeners. Use the data of mutable properties as it suits your business logic:

   EXT:my_extension/Classes/SomeClass.php

   <?php
   
   declare(strict_types=1);
   
   namespace MyVendor\MyExtension;
   
   use MyVendor\MyExtension\Event\DoingThisAndThatEvent;
   use Psr\EventDispatcher\EventDispatcherInterface;
   
   final class SomeClass
   {
       public function __construct(
           private readonly EventDispatcherInterface $eventDispatcher,
       ) {
       }
   
       public function doSomething(): void
       {
           // ..
   
           /** @var DoingThisAndThatEvent $event */
           $event = $this->eventDispatcher->dispatch(
               new DoingThisAndThatEvent('foo', 2)
           );
           $someChangedValue = $event->getMutableProperty();
   
           // ...
       }
   }
   

   Copied!

The event dispatcher object

The EventDispatcher object is used to trigger an event. TYPO3 has a custom event dispatcher implementation. In PSR-14 all event dispatchers of all frameworks are implementing \Psr\EventDispatcher\EventDispatcherInterface , thus it is possible to replace the event dispatcher with another. The EventDispatcher's main method dispatch() is called in TYPO3 Core or extensions. It receives a PHP object which will then be handed to all available listeners.

The listener provider

A ListenerProvider object that contains all listeners which have been registered for all events. TYPO3 has a custom listener provider that collects all listeners during compile time. This component is not exposed outside of TYPO3's Core Framework.

The events

An Event object can be any PHP object and is called from TYPO3 Core or an extension ("emitter") containing all information to be transported to the listeners. By default, all registered listeners get triggered by an event, however, if an event has the interface \Psr\EventDispatcher\StoppableEventInterface implemented, a listener can stop further execution of other event listeners. This is especially useful, if the listeners are candidates to provide information to the emitter. This allows to finish event dispatching, once this information has been acquired.

If an event can be modified, appropriate methods should be available, although due to PHP's nature of handling objects and the PSR-14 listener signature, it cannot be guaranteed to be immutable.

The listeners

Extensions and PHP packages can add listeners that are registered via YAML. They are usually associated to Event objects by the fully-qualified class name of the event to be listened on. It is the task of the listener provider to provide configuration mechanisms to represent this relationship.

Registering the event listener

If an extension author wants to provide a custom event listener, an according entry with the tag event.listener can be added to the Configuration/Services.yaml file of that extension.

services:
  # Place here the default dependency injection configuration

  MyVendor\MyExtension\EventListener\NullMailer:
    tags:
      - name: event.listener
        method: handleEvent
        identifier: 'myListener'
        before: 'redirects, anotherIdentifier'
        event: TYPO3\CMS\Core\Mail\Event\AfterMailerInitializationEvent

Read how to configure dependency injection in extensions.

The tag name event.listener identifies that a listener should be registered.

The custom PHP class \MyVendor\MyExtension\EventListener\NullMailer serves as the listener whose handleEvent() method is called, once the event is dispatched. The identifier is a common name, so orderings can be built upon the identifier, the optional before and after attributes allow for custom sorting against the identifier of other listeners.

If no attribute method is given, the class is treated as invokable, thus its __invoke() method will be called:

services:
  # Place here the default dependency injection configuration

  MyVendor\MyExtension\EventListener\NullMailer:
    tags:
      - name: event.listener
        identifier: 'myListener'
        before: 'redirects, anotherIdentifier'
        event: TYPO3\CMS\Core\Mail\Event\AfterMailerInitializationEvent

Read how to configure dependency injection in extensions.

The event listener class

An example listener, which hooks into the Mailer API to modify mailer settings to not send any emails, could look like this:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\EventListener;

use TYPO3\CMS\Core\Mail\Event\AfterMailerInitializationEvent;

final class NullMailer
{
    public function __invoke(AfterMailerInitializationEvent $event): void
    {
        $event->getMailer()->injectMailSettings(['transport' => 'null']);
    }
}

An extension can define multiple listeners.

Once the emitter is triggering an event, this listener is called automatically. Be sure to inspect the event's PHP class to fully understand the capabilities provided by an event.

Best practices

• When configuring listeners, it is recommended to add one listener class per event type, and have it called via __invoke().
• When creating a new event PHP class, it is recommended to add an Event suffix to the PHP class, and to move it into an appropriate folder like Classes/Event to easily discover events provided by a package. Be careful about the context that should be exposed.
• Emitters (TYPO3 Core or extension authors) should always use Dependency Injection to receive the event dispatcher object as a constructor argument, where possible, by adding a type declaration for \Psr\EventDispatcher\EventDispatcherInterface .

Any kind of event provided by TYPO3 Core falls under TYPO3's Core API deprecation policy, except for its constructor arguments, which may vary. Events that should only be used within TYPO3 Core, are marked as @internal, just like other non-API parts of TYPO3. Events marked as @internal should be avoided whenever technically possible.