PHPTime

Поведение и события в 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
<?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
<?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
<?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Трейт, если метод естественно принадлежит этим классам
Гарантировать порядок обязательных шагов бизнес-операцииЯвные вызовы из сервиса приложения

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

Чек-лист перед добавлением события или поведения

  1. Задайте имя события константой. Зафиксируйте, когда оно срабатывает и какие данные получает обработчик.
  2. Для отменяемой операции явно проверьте флаг отмены после вызова обработчиков.
  3. Проверьте имена методов и свойств поведения на коллизии. Выберите точку подключения с учётом того, каким экземплярам оно нужно.
  4. Для событий ActiveRecord проверьте обычное сохранение, вызовы без валидации и массовую запись, если эти пути используются.
  5. В тесте проверьте результат операции и наблюдаемый эффект обработчика. Для подписки уровня класса предусмотрите снятие при завершении теста.

Частые вопросы

Чем событие отличается от поведения в Yii 2?

Событие вызывает зарегистрированные обработчики в определённой точке работы компонента. Поведение добавляет компоненту методы и свойства и при необходимости подписывается на его события.

Как остановить обработку события в Yii 2?

Присвойте свойству handled объекта события значение true. Для отмены самой операции используйте предусмотренный ею флаг. Например, в обработчике события перед сохранением ActiveRecord можно установить isValid в false.

Вызываются ли события каждой модели при updateAll()?

Вызов updateAll() выполняет массовое обновление на уровне базы и не запускает события сохранения каждого экземпляра. Поэтому обработчики beforeSave и afterSave отдельных записей при таком обновлении не сработают.

Справка по теме

Ещё в разделе «Yii»

Расширения Yii 2: где искать и как устанавливать через Composer

Где искать расширения Yii 2, как проверить совместимость с PHP 8.3–8.5 и выбрать пакет. Установка через Composer, настройка и примеры популярных расширений.

7 мин

Yii 2 сегодня: установка, PHP 8.x и выбор фреймворка

Как установить Yii 2 на PHP 8.3–8.5, выбрать шаблон Basic или Advanced, проверить зависимости и решить, когда перейти на Yii 3 или Laravel.

6 мин

Миграция с Yii 1.1 на Yii 2: как перенести действующий проект

Как перенести проект с Yii 1.1 на Yii 2: пространства имён, ActiveRecord, формы, виджеты и конфигурация. План миграции с тестами и откатом.

7 мин

Как настроить автодополнение scope-методов ActiveRecord в Yii2

Настройте автодополнение scope-методов Yii2 в PhpStorm: создайте класс ActiveQuery, типизируйте find() и используйте фильтры в связях hasOne и hasMany.

7 мин