XC_VM/docs/ru/development/event-system.md

Система событий

XC_VM использует типизированный диспетчер событий в стиле PSR-14. Все события — обычные PHP-классы, диспетчируемые и принимаемые по имени класса. Диспетчер хранится в DI-контейнере под ключом events.

---

EventDispatcher

EventDispatcher — синглтон с instance-мостом. Статические методы делегируют в активный экземпляр, поэтому существующие вызовы работают без изменений.

// bootstrap.php создаёт канонический экземпляр:
$dispatcher = new EventDispatcher();
EventDispatcher::setInstance($dispatcher);
$container->set('events', $dispatcher);

// Оба пути достигают одного хранилища слушателей:
EventDispatcher::dispatch(new MyEvent(...));           // статический вызов
$container->get('events')->dispatch(new MyEvent(...)); // вызов через экземпляр

В тестах изолируйте состояние на каждый тест:

protected function setUp(): void {
    $dispatcher = new EventDispatcher();
    EventDispatcher::setInstance($dispatcher);
}

protected function tearDown(): void {
    EventDispatcher::resetInstance();
}

---

Диспетчеризация и прослушивание

// Диспетчеризация
EventDispatcher::dispatch(new StreamStartedEvent($lineId, $streamId));

// Прослушивание
EventDispatcher::listen(StreamStartedEvent::class, function (StreamStartedEvent $e): void {
    // обработка
}, priority: 10);

// Удаление слушателя
EventDispatcher::unlisten(StreamStartedEvent::class, $myCallable);

// Проверка
EventDispatcher::hasListeners(StreamStartedEvent::class); // bool

Приоритет — чем выше целое число, тем раньше вызывается слушатель. По умолчанию 0.

---

Регистрация слушателей в модуле

Вариант 1 — массив getEventSubscribers()

public function getEventSubscribers(): array {
    return [
        StreamStartedEvent::class => [$this, 'onStreamStarted'],
        // с приоритетом:
        UserAuthenticatedEvent::class => [[$this, 'onAuth'], 20],
    ];
}

Вариант 2 — атрибут #[ListensTo]

use ListensTo;

class MyModuleModule extends BaseModule {

    #[ListensTo(StreamStartedEvent::class, priority: 20)]
    public function onStreamStarted(StreamStartedEvent $e): void {
        // обработка
    }

    // IS_REPEATABLE — несколько атрибутов на одном методе
    #[ListensTo(StreamStartedEvent::class)]
    #[ListensTo(StreamStoppedEvent::class)]
    public function onStreamChange(object $e): void {
        // обработка обоих событий
    }
}

Оба механизма работают одновременно и могут сосуществовать в одном модуле. ModuleLoader::bootAll() выполняет оба прохода для каждого загруженного модуля.

---

Останавливаемые события (stoppable)

Расширьте AbstractEvent и вызовите $e->stopPropagation():

class MyGatingEvent extends AbstractEvent {
    public bool $allowed = true;
}

EventDispatcher::listen(MyGatingEvent::class, function (MyGatingEvent $e): void {
    if (!$this->check()) {
        $e->allowed = false;
        $e->stopPropagation();
    }
}, priority: 100);

Слушатели пропускаются, как только isPropagationStopped() возвращает true.

---

Встроенные события ядра

Класс события	Расположение	Когда диспетчеризуется	Останавливаемое
ModuleLoadedEvent	Events/Module/	После загрузки файла модуля	Нет
ModuleBootedEvent	Events/Module/	После вызова boot()	Нет
PackageInstalledEvent	Events/Module/	После установки из маркетплейса	Нет
UserAuthenticatedEvent	Events/Auth/	После успешного входа	Да
UserLoggedOutEvent	Events/Auth/	После выхода	Нет
StreamStartedEvent	Events/Stream/	После старта стрима	Нет
StreamStoppedEvent	Events/Stream/	После остановки стрима	Нет
SettingsChangedEvent	Events/Settings/	После сохранения настроек	Нет

---

Создание пользовательского события

Обычный класс с readonly-свойствами для неизменяемой полезной нагрузки:

<?php
namespace XcVm\Module\MyModule;

final class MyModuleEvent {
    public function __construct(
        public readonly int    $lineId,
        public readonly string $reason,
    ) {}
}

Останавливаемое событие — расширяйте AbstractEvent:

<?php
namespace XcVm\Module\MyModule;

use AbstractEvent;

final class MyModuleGatingEvent extends AbstractEvent {
    public bool $vetoed = false;

    public function __construct(
        public readonly int $resourceId,
    ) {}
}

Диспетчеризация из любого места после bootstrap:

EventDispatcher::dispatch(new MyModuleEvent($lineId, 'reason'));

---

Справочник атрибута ListensTo

#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
final class ListensTo {
    public function __construct(
        public readonly string $eventClass,
        public readonly int    $priority = 0,
    ) {}
}

• eventClass — полное имя класса события (FQN)
• priority — приоритет слушателя (выше = вызывается раньше; по умолчанию 0)
• Размещается на публичных методах классов, расширяющих BaseModule
• IS_REPEATABLE — несколько #[ListensTo] на одном методе регистрируются все
• Если eventClass не существует во время выполнения — атрибут пропускается (не исключение)