Events — API

Все методы вызываются статически у localzet\Events.

Регистрация: on()

Events::on(string $eventName, callable|array $listener): int

Аргумент	Значение
$eventName	Точное имя либо префикс с завершающей *. Имена чувствительны к регистру.
$listener	PHP-callable. Также допускается массив [ClassName::class, 'method'] для нестатического метода: библиотека сама создаст объект без аргументов.
Результат	Возрастающий ID новой регистрации.

Готовый callable, включая статический метод класса, не требует создания объекта. Для зависимостей конструктора передавайте [new Handler($dependency), 'handle'] или замыкание: автоматическое создание не использует DI-контейнер.

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

Удаление: off()

Events::off(string $eventName, int $id): int

Возвращает 1, если регистрация существовала и удалена; 0 — если не найдена. Повторное удаление допустимо. Для on('cache.*', ...) нужно off('cache.*', $id), а не off('cache.clear', $id).

Отправка: emit()

Events::emit(string $eventName, mixed $data, bool $halt = false): mixed

Ситуация	Обычный режим	$halt = true
Нет слушателей	[]	null
Все callback вернули null	Массив null по числу callback	null
Callback вернул false	false включается в результаты, выполнение прекращается	Возвращается false, выполнение прекращается
Callback вернул другое ненулевое значение	Значение включается в массив, выполнение продолжается	Значение возвращается сразу
Callback выбросил Throwable	Исключение включается в массив, выполнение продолжается	Исключение пропускается, поиск ответа продолжается

$halt означает первый результат, не равный null, а не первый truthy-результат. Данные события передаются callback обычным PHP-вызовом; объекты могут быть изменены обработчиком и оставаться теми же объектами для следующих слушателей.

Просмотр регистраций

Метод	Результат
listeners(string $eventName): array	Callable, которые получат данное фактическое имя события. Ключи — ID регистраций, порядок — возрастание ID.
has(string $eventName): bool	Есть ли хотя бы один точный или подходящий префиксный слушатель.
list(): array	Все регистрации: id => [registrationName, callable]. У префиксных имён восстановлена завершающая *.

listeners() не исполняет callback. has('order.created') может вернуть true только из-за подписки order.*. list() возвращает callable, в том числе объекты и замыкания: не сериализуйте этот результат в логи или сетевой ответ.

Область действия

Реестр общий для вызовов класса внутри одного процесса. Нет TTL, дискового хранения, межпроцессного обмена, приоритетов, автоматических повторов и отката побочных эффектов. Ошибку listener нужно обработать приложению по результату emit().