Как работает EventDispatcher в Symfony

Привет, Хабр!

Сегодня рассмотрим одну из самых сильных сторон Symfony — компонент EventDispatcher.

Если очень кратко, EventDispatcher позволяет создавать реактивную архитектуру: одни части приложения инициируют события, другие на них реагируют, не зная напрямую друг о друге.

В итоге проект получается гибким, расширяемым, легко тестируемым и не превращается в ужасный комок зависимостей.

Но чтобы использовать EventDispatcher правильно, мало просто вызвать dispatch() в коде. Нужно понимать:

• как создавать свои события

• как проектировать подписчиков

• как управлять порядком вызовов

• как останавливать цепочки событий

• как тестировать их безопасно

• как не наломать архитектуру плохим проектированием событий

И всё это мы сегодня коротко разберем.

Как устроен EventDispatcher

Когда мы диспатчим событие, происходит следующее:

1. Мы создаём объект события, т.е Event или его наследник.

2. Вызываем dispatch($event, $eventName).

3. Внутри компонента по имени события ищутся все зарегистрированные слушатели.

4. Каждый слушатель вызывается с этим объектом события.

5. Если кто-то остановит распространение события stopPropagation(), оставшиеся слушатели не вызываются.

Именно так EventDispatcher реализует паттерны Observer и Mediator: слушатели подписаны на события, но не знают о других участниках цепочки.

Событие всегда передаётся одним и тем же экземпляром объекта. Слушатели могут не только читать данные события, но и модифицировать их.

Пример работы

Начнём с самого простого — диспатчинг события и один слушатель. Допустим, есть сайт, и нужно реагировать на регистрацию пользователя.

Создадим EventDispatcher, слушателя и диспатчинг:

use Symfony\Component\EventDispatcher\EventDispatcher; use Symfony\Contracts\EventDispatcher\Event;  // Создаём диспетчер $dispatcher = new EventDispatcher();  // Регистрируем слушателя $dispatcher->addListener('user.registered', function (Event $event) {     echo "Пользователь зареган."; });  // Где-то в коде диспатчим событие $dispatcher->dispatch(new Event(), 'user.registered');

Отправить ‘пустое’ событие — это только начало. В реальных задачах почти всегда нужно передавать вместе с событием данные. Посмотрим, как это делается

Как создавать события с полезной нагрузкой

В реальных приложениях почти всегда используется собственный класс события, а не голый Event.

Допустим, есть сущность User, и мы хотим передавать её внутри события.

Создадим свой Event-класс:

namespace App\Event;  use Symfony\Contracts\EventDispatcher\Event; use App\Entity\User;  class UserRegisteredEvent extends Event {     public function __construct(private User $user)     {     }      public function getUser(): User     {         return $this->user;     } }

Теперь, при диспатче события можно передать полноценного пользователя:

use App\Event\UserRegisteredEvent;  $user = new User('ivan.ivanov@example.com');  $event = new UserRegisteredEvent($user); $dispatcher->dispatch($event, UserRegisteredEvent::class);

И слушатель тоже получает доступ к объекту пользователя:

$dispatcher->addListener(UserRegisteredEvent::class, function (UserRegisteredEvent $event) {     $user = $event->getUser();     echo "Привет, " . $user->getEmail(); });

Таким образом, мы диспатчим смысленное событие, а не абстрактное что-то случилось.

Как подписываться на события правильно: Listener vs Subscriber

В Symfony есть два способа подписываться на события:

Слушатель

Просто отдельная функция или метод, который регистрируется через addListener().

Используем тогда, когда нужна быстрая реакция на одно событие или сама по себе малая логика

Пример:

$dispatcher->addListener(UserRegisteredEvent::class, [new SendWelcomeEmail(), 'handle']);

Подписчик

Класс, который реализует EventSubscriberInterface и явно описывает:

• на какие события он подписан

• какими методами реагировать

Подписчик хорош когда: нужно подписаться на несколько события, задавать приоритеты и адекватно структурировать код. Его в основном и используют в проектах.

Пример подписчика:

namespace App\EventSubscriber;  use App\Event\UserRegisteredEvent; use Symfony\Component\EventDispatcher\EventSubscriberInterface;  class WelcomeEmailSubscriber implements EventSubscriberInterface {     public static function getSubscribedEvents(): array     {         return [             UserRegisteredEvent::class => 'onUserRegistered',         ];     }      public function onUserRegistered(UserRegisteredEvent $event): void     {         $user = $event->getUser();         // отправляем email     } }

И в конфигурации:

services:     App\EventSubscriber\WelcomeEmailSubscriber:         tags:             - { name: 'kernel.event_subscriber' }

Подписчики — это более организованный способ работы, и в проектах всегда стоит их использовать.

Приоритеты вызова слушателей

Когда на одно событие подписаны несколько обработчиков, порядок их вызова имеет значение.

Symfony позволяет задавать приоритет слушателю. Больше приоритет = раньше вызов.

Пример в подписчике:

public static function getSubscribedEvents(): array {     return [         UserRegisteredEvent::class => [             ['sendWelcomeEmail', 10],             ['logUserRegistration', 5],             ['notifyAdmin', -10],         ],     ]; }

Сначала отправится email, потом залогируется регистрация, а далее будет уведомление админа

Остановка цепочки событий

Иногда нужно прервать дальнейшее распространение события.

Для этого в классе события можно вызвать stopPropagation():

public function onUserRegistered(UserRegisteredEvent $event): void {     if ($event->getUser()->isBanned()) {         $event->stopPropagation();     } }

После вызова stopPropagation(), остальные слушатели для этого события уже не будут вызваны.

Как правильно тестировать события

Хорошая архитектура предполагает наличие тестов.

Самый простой способ протестировать работу события — это поймать диспатчинг события в юнит-тестах.

Пример теста:

use Symfony\Component\EventDispatcher\EventDispatcher; use PHPUnit\Framework\TestCase; use App\Event\UserRegisteredEvent;  class UserEventTest extends TestCase {     public function testUserRegisteredEventDispatched()     {         $dispatcher = new EventDispatcher();          $called = false;          $dispatcher->addListener(UserRegisteredEvent::class, function (UserRegisteredEvent $event) use (&$called) {             $called = true;         });          $user = new User('test@example.com');         $dispatcher->dispatch(new UserRegisteredEvent($user), UserRegisteredEvent::class);          $this->assertTrue($called);     } }

Простой способ проверить, что событие действительно диспатчится и слушатели вызываются.

Типичные ошибки

Немного опыта:

Мини-проект

Допустим, нам нужно нужно смоделировать мини-проект интернет-магазина, который продаёт корм для котиков. После оформления заказа должны произойти следующие действия:

1. Отправить покупателю письмо с благодарностью.

2. Уведомить склад о необходимости собрать заказ.

3. Начислить бонусные баллы клиенту.

4. В случае проблем остановить цепочку событий.

Все эти действия должны быть реализованы через цепочку событий, чтобы система оставалась гибкой и расширяемой.

Архитектура событий

Для начала определимся с основной схемой: событие у нас будет называться OrderPlacedEvent, а реагировать на него будут сразу три слушателя —SendThankYouEmailListener (отправить письмо с благодарностью), NotifyWarehouseListener (уведомить склад о заказе) и AccrueBonusPointsListener (начислить клиенту бонусные баллы). Вся координация действий будет происходить через EventDispatcher.

Создание события

Создадим класс события OrderPlacedEvent, который будет содержать данные о заказе.

namespace App\Event;  use Symfony\Contracts\EventDispatcher\Event; use App\Entity\Order;  class OrderPlacedEvent extends Event {     public function __construct(private Order $order)     {     }      public function getOrder(): Order     {         return $this->order;     } }

Событие несёт внутри себя объект заказа. Через метод getOrder() слушатели могут получить доступ к данным.

Сущность заказа

Для полноты картины сделаем упрощённую модель заказа:

namespace App\Entity;  class Order {     private int $id;     private string $customerEmail;     private bool $stockAvailable;      public function __construct(int $id, string $customerEmail, bool $stockAvailable = true)     {         $this->id = $id;         $this->customerEmail = $customerEmail;         $this->stockAvailable = $stockAvailable;     }      public function getId(): int     {         return $this->id;     }      public function getCustomerEmail(): string     {         return $this->customerEmail;     }      public function isStockAvailable(): bool     {         return $this->stockAvailable;     } }

Флаг stockAvailable показывает, есть ли товар на складе. Если его нет — событие должно быть остановлено, чтобы не слать письма и не начислять бонусы зря.

Реализация слушателей

Теперь создаём три слушателя.

Отправка письма благодарности

namespace App\Listener;  use App\Event\OrderPlacedEvent;  class SendThankYouEmailListener {     public function __invoke(OrderPlacedEvent $event): void     {         $order = $event->getOrder();         $email = $order->getCustomerEmail();          // Имитируем отправку письма         echo "Отправляем письмо на {$email}: Спасибо за заказ для вашего котика!\n";     } }

__invoke, чтобы слушателя можно было регистрировать компактно.

Уведомление склада

namespace App\Listener;  use App\Event\OrderPlacedEvent;  class NotifyWarehouseListener {     public function __invoke(OrderPlacedEvent $event): void     {         $order = $event->getOrder();          if (!$order->isStockAvailable()) {             echo "Ошибка: нет товара на складе. Останавливаем событие.\n";             $event->stopPropagation();             return;         }          echo "Уведомляем склад: собрать заказ №{$order->getId()}.\n";     } }

Если товара нет, то сразу вызываем stopPropagation(), чтобы прекратить дальнейшую обработку.

Начисление бонусов

namespace App\Listener;  use App\Event\OrderPlacedEvent;  class AccrueBonusPointsListener {     public function __invoke(OrderPlacedEvent $event): void     {         $order = $event->getOrder();         echo "Начисляем бонусные баллы покупателю с email: {$order->getCustomerEmail()}.\n";     } }

Бонусы начисляются только если событие не было остановлено ранее.

Сборка всего вместе

Создадим диспетчер и зарегистрируем слушателей.

use Symfony\Component\EventDispatcher\EventDispatcher; use App\Event\OrderPlacedEvent; use App\Listener\SendThankYouEmailListener; use App\Listener\NotifyWarehouseListener; use App\Listener\AccrueBonusPointsListener; use App\Entity\Order;  // Инициализируем диспетчер $dispatcher = new EventDispatcher();  // Регистрируем слушателей $dispatcher->addListener(OrderPlacedEvent::class, new NotifyWarehouseListener(), 20); $dispatcher->addListener(OrderPlacedEvent::class, new SendThankYouEmailListener(), 10); $dispatcher->addListener(OrderPlacedEvent::class, new AccrueBonusPointsListener(), 0);  // Создаём заказ $order = new Order(101, 'catlover@example.com', true);  // Диспатчим событие $dispatcher->dispatch(new OrderPlacedEvent($order));

Что увидим на выходе?

Если товар есть на складе:

Уведомляем склад: собрать заказ №101. Отправляем письмо на catlover@example.com: Спасибо за заказ для вашего котика! Начисляем бонусные баллы покупателю с email: catlover@example.com.

Если товара нет:

Ошибка: нет товара на складе. Останавливаем событие.

И всё — никакого письма и бонусов.

В итоге

EventDispatcher — мощная штука, если пользоваться с умом: чёткие события, отдельные классы, нормальные подписчики и порядок вызовов. А как у вас с событиями в проектах? Часто ими пользуетесь или пока мимо?

---

В заключение рекомендую посетить открытый урок по локализации текстов в Symfony, который пройдет 15 мая в 20:00 в OTUS. Разберём локализацию как статичных, так и динамических текстов, хранимых в базе данных, с использованием компонента symfony/translation. Узнаете, как эффективно работать с переводами и нестандартным маппингом.

Готовы проверить свои знания по Symfony? Пройдите вступительное тестирование и узнайте, насколько уверенно вы себя чувствуете в теме.