Events: события

В ТАО реализована система событий (модуль Events), описывающая стандартный механизм событий в ООП. Что позволяет достаточно быстро внедрять дополнительный функционал в существующий код.

Основной принцип работы заключается в том, что во фреймворке по различным поводам генерируются события, а в коде проекта могут присутствовать специальные обработчики этих событий. Любое событие имеет имя - строковое значение, также в него могут быть переданы аргументы. В некоторых случаях обработчики событий могут возвращать какие-либо значения (в зависимости от самого события).

Генерация событий

Генерация события производится с использованием метода Events::call().

Events::call('name.of.event', $arg1, $arg2);

где,

• name.of.event - имя события, строковое значение.
• $arg1, $arg2 - аргументы, которые будут переданы в обработчик.

При формировании имен событий, для поддержания единообразия, желательно придерживаться сложившегося правила именования событий во фреймворке. А именно, если событие будет генерироваться в рамках компонента, то в имени указывается ключевое слово component и имя компонента, далее идет название модуля (где будет генерироваться событие), название действия. Если событие относится к библиотеке, то в имени должно быть указано ключевое слово CMS .

Например,

component.comments.before.add - компонент Комментарии, вызов события, позволяющего произвести какие-то действия до записи комментария в базу

cms.actions.dispatch - библиотечное событие. Вызывается перед началом диспетчеризации запроса.

Обработка событий

Как правило, в проектах редко возникает необходимость генерировать события. Основное место генерации в ядре фреймворка, в CMS, в библиотечных компонентах. На проектах часто осуществляется только обработка событий. Для этого применяется метод Events::add_listener(), с помощью которого можно подписаться на то или иное событие и повесить на него обработчик.

Events::add_listener('name.of.event', 'my_listener'); //подписываемся на событие name.of.event и вешаем на него функцию my_listener

function my_listener($arg1,$arg2)
{
	// ... здесь какой-то код
}

На одно событие можно повесить и несколько обработчиков - просто вызвав несколько раз Events::add_listener. Второй параметр - это callback, поэтому мы можем использовать в качестве обработчиков методы классов, а начиная с PHP 5.3 - и безымянные функции.

// безымянная функция в качестве аргумента
Events::add_listener('name.of.event', function($arg1, $arg2) {
	// ... здесь какой-то код
});

Есть возможность указать в качестве обработчика функцию из еще не загруженного модуля.

// метод класса в качестве аргумента
Events::add_listener('name.of.event', 'App.MyModule::listener');

В этом случае при вызове события модуль App.MyModule будет автоматически подгружен, и в нем будет вызван статический метод listener().

Отдельный вопрос - где располагать описание обработчиков. С технической стороны нет ограничений, соответственно вызов можно организовать в любом месте кода. Здесь важно придерживаться здравого смысла.

1. Регистрация события и реализация метода (функции), который будет вызван при наступлении события в одном месте.

Например, для вывода дополнительного поля в админке для списка записей, необходимо подписаться на событие nodus.admin.items.on_row. Для этого в описании дататайпа подпишемся на данное событие и здесь же, в классе дататайпа, опишем метод, реализующий вывод поля в списке.

// Nodus/app/Datatype/Cat/Type.php

Events::add_listener(
	'nodus.admin.items.on_row',
	'Component.Nodus.App.Datatype.Cat.Type::on_row'
);
class Component_Nodus_App_Datatype_Cat_Type extends Component_Nodus_Datatype implements Core_ModuleInterface
{
	...
	public static function on_row($row, $controller)
	{
		if ($row->datatype()->mnemocode() == 'cat') {
			$term = Component_Nodus::taxonomy_term($row->color);
			if ($term){
				$row->color = $term->field('title');
			}
			else{
				$row->color = '';
				}
		}
	}
}

2. Вынесение регистрации события в конфигурационные настройки компонента.

Все события внутри компонента можно вынести и зарегистрировать в конфигурационных настройках (/ComponentName/config/component.php). Для этого зарезервирована специальная настройка events.

// Nodus/config/component.php

return array(
	...
	'events' => array(
		'nodus.admin.items.on_row' => array(
			Component_Nodus::datatype('cat'), 'on_row'
		),
	),
);

3. Если событий много, правильнее будет, вообще вынести их в отдельный класс со всем описанием функций-обработчиков. Например, в папку app/lib/ проекта.

// app/lib/Events.php

class App_Events implements Core_ModuleInterface
{
	public static function initialize()
	{
		Events::add_listener('nodus.admin.items.on_row',
			array(Component_Nodus::datatype('cat'), 'on_row')

		);
	}
}

После этого не забываем подключить в index.php.

...
Core::load('App.Events');
...
CMS::Run();

Справочник событий ТАО