Поведение и события в Yii 2
События в Yii 2 позволяют запускать обработчики в определённый момент работы компонента. Поведения добавляют компоненту методы и свойства и могут сами подписываться на его события. Разберём оба механизма на примерах и посмотрим, где они уместны в коде на PHP 8.3–8.5.
Как устроены события и поведения
Оба механизма доступны в классах, унаследованных от yii\base\Component, в том числе в контроллерах, компонентах приложения и моделях ActiveRecord. Событие связывает точку в коде с одним или несколькими обработчиками. Поведение инкапсулирует возможности, которые можно подключить к компоненту и использовать в других классах.
- Компонент вызывает
trigger()в нужный момент. Подписчики, ранее зарегистрированные черезon(), получают объект события. - Компонент подключает объект
yii\base\Behaviorчерезbehaviors()илиattachBehavior(). Публичные методы и доступные свойства поведения можно использовать через компонент. - Поведение может описать подписки на события владельца в методе
events(). Yii добавит обработчики при подключении и снимет их при отключении.
Примеры используют синтаксис PHP 8.3–8.5. При обновлении проекта учитывайте совместимость установленного выпуска Yii 2 и расширений с целевой версией PHP. Сигнатуры собственных методов типизируйте, а при переопределении методов фреймворка соблюдайте совместимость с родительским классом.
Как объявить событие, подписаться и вызвать его
Для собственного события задайте имя константой. Если обработчикам нужны данные операции, передайте экземпляр специализированного класса, наследующего yii\base\Event. В примере событие сообщает количество строк готового отчёта. Запустите фрагмент в приложении с загруженным Yii.
<?php
declare(strict_types=1);
use yii\base\Component;
use yii\base\Event;
final class ReportReadyEvent extends Event
{
public function __construct(public readonly int $rowCount)
{
parent::__construct();
}
}
final class ReportBuilder extends Component
{
public const EVENT_REPORT_READY = 'reportReady';
public function build(array $rows): array
{
$report = array_values($rows);
// Отчёт сформирован, можно уведомить подписчиков.
$this->trigger(self::EVENT_REPORT_READY, new ReportReadyEvent(count($report)));
return $report;
}
}
$builder = new ReportBuilder();
$logReady = static function (ReportReadyEvent $event): void {
Yii::info('Строк в отчёте: ' . $event->rowCount, 'reports');
};
$builder->on(ReportBuilder::EVENT_REPORT_READY, $logReady);
$report = $builder->build([['id' => 42]]);
$builder->off(ReportBuilder::EVENT_REPORT_READY, $logReady);Для подписки подходят замыкание и другие PHP-колбэки, например [$listener, 'onReportReady']. Чтобы снять отдельную подписку с замыканием, сохраните то же замыкание в переменной и передайте его в off(). Вызов off() только с именем события снимает все подписки экземпляра на это имя.
В обработчике $event->sender обычно содержит компонент, вызвавший trigger(). Третий аргумент on() задаёт $event->data для конкретной подписки. Данные самой операции, такие как число строк, удобнее хранить в свойствах специализированного события.
Порядок обработчиков и отмена операции
Обработчики экземпляра по умолчанию выполняются в порядке регистрации. Четвёртый аргумент on() со значением false помещает обработчик в начало списка. Вызов синхронный. Если обработчик выбросит исключение и вызывающий код его не перехватит, исключение выйдет из trigger(), а оставшиеся обработчики в этом вызове не выполнятся. При отсутствии подписчиков событие можно вызывать так же, как обычно.
Для остановки дальнейшей обработки установите $event->handled = true. Чтобы отменить саму операцию, компонент должен предусмотреть отдельный контракт. Например, yii\base\ModelEvent содержит свойство isValid. Метод beforeSave() в ActiveRecord возвращает это значение, и при false операция сохранения прерывается. Возвращаемое значение колбэка Yii при вызове события не использует.
Подписка через on() на объекте действует для этого экземпляра. Для подписки на события класса и его подклассов есть yii\base\Event::on(). При обычном вызове Component::trigger() обработчики экземпляра идут перед обработчиками уровня класса. В тестах и долгоживущих воркерах учитывайте, что подписка уровня класса хранится до снятия через Event::off() или до завершения процесса.
Как подключить поведение и вызвать его метод
В behaviors() обычно задают постоянные для класса подключения. Для подключения к отдельному экземпляру используйте attachBehavior(). Поведение может обратиться к своему компоненту через $this->owner. Имя подключения пригодится для явного доступа через getBehavior() и снятия через detachBehavior().
В примере модель хранит имя пользователя, а поведение формирует подпись для интерфейса. User можно использовать как обычную модель Yii. Метод поведения также можно вызвать напрямую у полученного объекта поведения, когда нужно явно указать, какая реализация используется.
<?php
declare(strict_types=1);
use yii\base\Behavior;
use yii\base\Model;
final class DisplayNameBehavior extends Behavior
{
public function displayName(): string
{
$user = $this->owner;
if (!$user instanceof User) {
throw new LogicException('Поведение подключается к модели User.');
}
// Пустое имя заменяем подписью для интерфейса.
$name = trim($user->name);
return $name === '' ? 'Без имени' : $name;
}
}
final class User extends Model
{
public string $name = '';
public function behaviors(): array
{
return ['display' => DisplayNameBehavior::class];
}
}
$user = new User(['name' => ' Анна ']);
echo $user->displayName(); // АннаСобственный публичный метод компонента имеет приоритет перед одноимённым методом поведения. Если имя есть у нескольких подключённых поведений, Yii использует первое подходящее по порядку подключения. Давайте экспортируемым методам различимые имена. В коде, где важна строгая проверка статическим анализатором, удобно получить поведение по имени и проверить его тип перед вызовом.
Как поведение подписывается на события ActiveRecord
Метод events() возвращает соответствие между именами событий владельца и обработчиками поведения. Например, несколько моделей могут перед валидацией обрезать внешние пробелы в одном и том же атрибуте. У атрибута title в примере должна быть соответствующая колонка таблицы. Правила валидации задаются в самой модели.
<?php
declare(strict_types=1);
use yii\base\Behavior;
use yii\base\ModelEvent;
use yii\db\ActiveRecord;
final class TrimTitleBehavior extends Behavior
{
public function events(): array
{
return [ActiveRecord::EVENT_BEFORE_VALIDATE => 'trimTitle'];
}
public function trimTitle(ModelEvent $event): void
{
$record = $event->sender;
if (!$record instanceof ActiveRecord || !$record->hasAttribute('title')) {
return;
}
// Остальные значения оставляем правилам валидации модели.
$title = $record->getAttribute('title');
if (is_string($title)) {
$record->setAttribute('title', trim($title));
}
}
}
// $article — экземпляр ActiveRecord с атрибутом title.
$article->attachBehavior('trimTitle', TrimTitleBehavior::class);
$article->validate();Для одиночной модели ту же нормализацию можно задать встроенным валидатором trim в rules(). Поведение пригодится, когда одна настройка объединяет несколько действий или переиспользуется в разных моделях. Для заполнения временных меток перед вставкой и обновлением у Yii 2 есть готовое yii\behaviors\TimestampBehavior.
Точка подключения должна соответствовать способу записи. save(false) пропускает валидацию и её события. Массовые операции updateAll() и deleteAll() выполняются без событий отдельных записей. Если правило должно соблюдаться при всех способах записи, проверьте также массовые обновления и прямой SQL.
События EVENT_AFTER_INSERT и EVENT_AFTER_UPDATE относятся к выполнению операции ActiveRecord. При открытой внешней транзакции они могут сработать до её фиксации. Если отправка письма или постановка задачи допустима только после успешного коммита, выполняйте её после фиксации в сервисе, который управляет транзакцией. Для надёжной доставки можно сохранять запись о задаче в той же транзакции и обрабатывать её отдельно.
Что выбрать для конкретной задачи
| Задача | Механизм |
|---|---|
| Записать в журнал факт формирования отчёта | Обработчик события компонента |
| Подключить одинаковые методы и обработчики к нескольким моделям | Поведение Yii 2 |
| Добавить один и тот же метод нескольким классам на уровне PHP | Трейт, если метод естественно принадлежит этим классам |
| Гарантировать порядок обязательных шагов бизнес-операции | Явные вызовы из сервиса приложения |
Событие удобно, когда компонент публикует факт или предоставляет документированную точку расширения. Если корректность операции зависит от конкретного обработчика и его места в цепочке, явный вызов делает эту зависимость видимой. Поведение стоит подключать там, где вызывающему коду действительно нужны его методы, свойства или подписки на жизненный цикл компонента.
Чек-лист перед добавлением события или поведения
- Задайте имя события константой. Зафиксируйте, когда оно срабатывает и какие данные получает обработчик.
- Для отменяемой операции явно проверьте флаг отмены после вызова обработчиков.
- Проверьте имена методов и свойств поведения на коллизии. Выберите точку подключения с учётом того, каким экземплярам оно нужно.
- Для событий ActiveRecord проверьте обычное сохранение, вызовы без валидации и массовую запись, если эти пути используются.
- В тесте проверьте результат операции и наблюдаемый эффект обработчика. Для подписки уровня класса предусмотрите снятие при завершении теста.
Частые вопросы
Чем событие отличается от поведения в Yii 2?
Событие вызывает зарегистрированные обработчики в определённой точке работы компонента. Поведение добавляет компоненту методы и свойства и при необходимости подписывается на его события.
Как остановить обработку события в Yii 2?
Присвойте свойству handled объекта события значение true. Для отмены самой операции используйте предусмотренный ею флаг. Например, в обработчике события перед сохранением ActiveRecord можно установить isValid в false.
Вызываются ли события каждой модели при updateAll()?
Вызов updateAll() выполняет массовое обновление на уровне базы и не запускает события сохранения каждого экземпляра. Поэтому обработчики beforeSave и afterSave отдельных записей при таком обновлении не сработают.