События

Когда развёртывается событие, оно определяется уникальным именем (например, kernel.response), которое может слушать любое количество слушателей. Также создаётся и передаётся всем слушателям экземпляр Event. Как вы увидите позже, сам объект Event часто содержит данные о запускаемом событии.

Диспетчер

Диспетчер - это центральный объект системы запуска событий. Обычно создаётся один диспетчер, который содержит реестр слушателей. Когда событие запускается через диспетчер, он уведомляет всех слушателей, зарегистрированных с этим событием:

1
2
3

use Symfony\Component\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher();

Соединение слушателей

Чтобы воспользоваться преимуществами существующего события, вам нужно соединить слушателя с диспетчером, чтобы он мог быть уведомлён, когда событие будет запущено. Вызов метода диспетчера addListener() ассоциирует все вызываемые PHP с событием:

1
2

$listener = new AcmeListener();
$dispatcher->addListener('acme.foo.action', array($listener, 'onFooAction'));

Метод addListener() имеет до трёх аргументов:

1. Имя события (строка), которое хочет слушать этот слушатель;
2. Вызываемое PHP, которое будет выполнено при запуске указанного события;
3. Необязательное число приоритета (чем выше - тем важнее, следовательно этот слушатель будет запущен раньше), которое определяет, когда вызывается слушатель по отношению к другим слушателям (по умолчанию 0). Если два слушателя имеют одинаковый приоритет, они выполняются в том порядке, в котором были добавлены в диспетчер.

1
2
3
4
5

use Symfony\Component\EventDispatcher\Event;

$dispatcher->addListener('acme.foo.action', function (Event $event) {
    // будет выполнено при запуске события acme.foo.action
});

Когда слушатель зарегистрирован в диспетчере, он ждёт, пока не будет уведомления о событии. В примере выше, когда запускается событие acme.foo.action, диспетчер вызывает метод AcmeListener::onFooAction() и передаёт объект Event в виде единственного аргумента:

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Component\EventDispatcher\Event;

class AcmeListener
{
    // ...

    public function onFooAction(Event $event)
    {
        // ... сделать что-то
    }
}

Аргумент $event - это объект события, который был передан при запуске события. Во многих случаях, передаётся специальный подкласс события с дополнительной информацией. Вы можете посмотреть документацию или реализацию каждого событий, чтобы определить, какой экземпляр передаётся.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
use Symfony\Component\DependencyInjection\Reference;
use Symfony\Component\EventDispatcher\EventDispatcher;
use Symfony\Component\EventDispatcher\DependencyInjection\RegisterListenersPass;

$containerBuilder = new ContainerBuilder(new ParameterBag());
// регистрирует пропуск компилировщика, который обрабатывает теги сервиса
// 'kernel.event_listener' и 'kernel.event_subscriber'
$containerBuilder->addCompilerPass(new RegisterListenersPass());

$containerBuilder->register('event_dispatcher', EventDispatcher::class);

// регистрирует слушателя события
$containerBuilder->register('listener_service_id', \AcmeListener::class)
    ->addTag('kernel.event_listener', array(
        'event' => 'acme.foo.action',
        'method' => 'onFooAction',
    ));

// регистрирует подписчика событий
$containerBuilder->register('subscriber_service_id', \AcmeSubscriber::class)
    ->addTag('kernel.event_subscriber');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

use Symfony\Component\DependencyInjection\Compiler\PassConfig;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
use Symfony\Component\DependencyInjection\Reference;
use Symfony\Component\EventDispatcher\DependencyInjection\AddEventAliasesPass;
use Symfony\Component\EventDispatcher\DependencyInjection\RegisterListenersPass;
use Symfony\Component\EventDispatcher\EventDispatcher;

$containerBuilder = new ContainerBuilder(new ParameterBag());
$containerBuilder->addCompilerPass(new AddEventAliasesPass([
    \AcmeFooActionEvent::class => 'acme.foo.action',
]));
$containerBuilder->addCompilerPass(new RegisterListenersPass(), PassConfig::TYPE_BEFORE_REMOVING);

$containerBuilder->register('event_dispatcher', EventDispatcher::class);

// регистрирует слушателя событий
$containerBuilder->register('listener_service_id', \AcmeListener::class)
    ->addTag('kernel.event_listener', [
        // will be translated to 'acme.foo.action' by RegisterListenersPass.
        'event' => \AcmeFooActionEvent::class,
        'method' => 'onFooAction',
    ]);

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

Кроме регистрации в слушателях существующих событий, вы можете создавать и запускать собственные события. Это полезно при создании сторонних библиотек, а также,когда вы хотите сохранять разные компоненты вашей собственной системы гибкими и разделёнными.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

namespace Acme\Store\Event;

use Symfony\Component\EventDispatcher\Event;
use Acme\Store\Order;

/**
 * Событие order.placed запускается каждый раз, когда создаётся заказ
 * в системе.
 */
class OrderPlacedEvent extends Event
{
    public const NAME = 'order.placed';

    protected $order;

    public function __construct(Order $order)
    {
        $this->order = $order;
    }

    public function getOrder(): Order
    {
        return $this->order;
    }
}

1
2
3
4
5
6
7
8
9
10

use Acme\Store\Order;
use Acme\Store\Event\OrderPlacedEvent;

// создаёт или извлекает порядок каким-либо образом
$order = new Order();
// ...

// создаёт OrderPlacedEvent и запускает его
$event = new OrderPlacedEvent($order);
$dispatcher->dispatch(OrderPlacedEvent::NAME, $event);

Использование подписчиков событий

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

Другим способом слушать события является через подписчика событий. Подписчик событий - это PHP класс, который способен сообщить диспетчеру, на какие именно события ему нужно подпистаься. Он реализует интерфейс EventSubscriberInterface, который требует одного статичного метода, под названием getSubscribedEvents(). Возьмите следующий пример подписчика, который подписывается на события kernel.response и order.placed:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

namespace Acme\Store\Event;

use Acme\Store\Event\OrderPlacedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use Symfony\Component\HttpKernel\KernelEvents;

class StoreSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            KernelEvents::RESPONSE => [
                ['onKernelResponsePre', 10],
                ['onKernelResponsePost', -10],
            ],
            OrderPlacedEvent::NAME => 'onStoreOrder',
        ];
    }


    public function onKernelResponsePre(ResponseEvent $event)
    {
        // ...
    }

    public function onKernelResponsePost(ResponseEvent $event)
    {
        // ...
    }

    public function onStoreOrder(OrderPlacedEvent $event)
    {
        // ...
    }
}

Это очень похоже на класс слушателя, кроме того, что сам классможет сказать диспетчеру, какие события ему стоит слушать. Чтобы зарегистрирвать подписчика в диспетчере, используйте метод addSubscriber():

1
2
3
4
5

use Acme\Store\Event\StoreSubscriber;
// ...

$subscriber = new StoreSubscriber();
$dispatcher->addSubscriber($subscriber);

Диспетчер автоматически зарегистрирует подписчика для каждого события, возвращённого методом getSubscribedEvents(). Этот метод возвращает массив, индексированный по именам событий, значения которых являются либо именем метода для вызова, либо массивом, составленным из именим метода для вызова и приоритетом.

Вышеописанный пример демонстрирует, как зарегистрировать несколько методов слушателя для одного и того же события в подписчике, а также, как передать приоритет каждого метода слушателя. Чем выше приоритет, тем раньше вызывается метод. В вышеописанном примере, когда запускается событие kernel.response, вызываются методы onKernelResponsePre() и onKernelResponsePost() в таком порядке.

Остановка потока / распространения событий

В некоторых случаях, слушателю имеет смысл предотвращать вызов любых слушателей. Другими словами, слушателю нужно иметь возможность сказать диспетчеру прекратить расространене события в будущие слушатели (т.е. более не уведомлять слушателей). Это можно сделать изнутри слушателя,с помощью метода stopPropagation():

1
2
3
4
5
6
7
8

use Acme\Store\Event\OrderPlacedEvent;

public function onStoreOrder(OrderPlacedEvent $event)
{
    // ...

    $event->stopPropagation();
}

Теперь, любые слушатели order.placed, которые ещё не были вызваны, не будут вызваны.

Возможно определить, было ли событие остановлено с использованием метода isPropagationStopped(), который возвращает булево значение:

1
2
3
4
5

// ...
$dispatcher->dispatch($event, 'foo.event');
if ($event->isPropagationStopped()) {
    // ...
}

События и слушатели, знающие об EventDispatcher

EventDispatcher всегда передаёт запущенное событие, имя события и ссылку на себя самого слушателям. Это может привести к некоторым продвинутым применениям EventDispatcher, включая запуск других событий внутри слушателей, связывание событий или даже ленивую загрузку слушателей в объекте диспетчера.

Интроспекция имени события

Экземпляр EventDispatcher, так же как и имя события, которое запускается, передаются в качестве аргументов слушателя:

1
2
3
4
5
6
7
8
9
10

use Symfony\Contracts\EventDispatcher\Event;
use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;

class Foo
{
    public function myEventListener(Event $event, $eventName, EventDispatcherInterface $dispatcher)
    {
        // ... сделать что-то с именем события
    }
}