Как устроен пакет

#События

Решения не вызывают друг друга напрямую. Вместо этого одно объявляет событие, а другое на него подписывается.

плохо:  Форма  →  CRM::создатьЗаявку()
хорошо: Форма  →  событие form.submitted
        CRM    →  слушает form.submitted → создаёт заявку

Почему так

Разница не в красоте. При прямом вызове форма перестаёт работать, если CRM не установлена: класса нет, вызов падает. Через событие форма не знает, слушает её кто-нибудь или нет, и работает одна.

#Какие события есть

Событие	Кто объявляет	Когда
`form.submitted`	Формы	посетитель отправил форму
`crm.lead.created`	CRM	появилась заявка
`crm.lead.status_changed`	CRM	заявка перешла в другой статус
`task.created`	Задачи	создана задача
`task.status_changed`	Задачи	задача сменила статус
`task.completed`	Задачи	задача завершена
`module.rendered`	ядро	блок нарисован — можно дописать разметку
`admin.record.rendered`	ядро	открыта запись в панели — можно добавить блок

#Кто на что подписан сейчас

Решение	Слушает	Что делает
CRM и формы	`form.submitted`	заводит заявку из отправленной формы
	`admin.record.rendered`	показывает связь с заявкой в карточке
Задачи по сделкам	`crm.lead.created`	создаёт задачу на новую заявку
	`crm.lead.status_changed`	создаёт задачу при переходе статуса
Формы	`module.rendered`	дописывает в блок формы её поля

Примечание

Последняя строка показывает, зачем событие module.rendered нужно ядру. Набор полей формы заранее в вёрстке не перечислить — их заводит человек. Ядро при этом не должно знать про формы: кто хочет дописать разметку — тот подписывается.

#Как подписаться

В манифесте своего решения:

"listeners": {
  "crm.lead.created": "MoiKlass::onLead"
}

Обработчик — метод класса из src/ решения:

class MoiKlass
{
    public static function onLead(array &$payload)
    {
        // $payload['lead'] — номер заявки
        // Данные можно дополнить: они вернутся тому, кто объявил событие.
    }
}

Данные передаются ссылкой: слушатель вправе их дополнить. Так CRM возвращает форме номер созданной заявки, а форма показывает его посетителю.

#Защита от кольца

Событие, вызванное из обработчика того же события, ушло бы в бесконечную рекурсию. Такой вызов отклоняется, а в журнал сервера уходит строка «кольцо на событии …».

#Журнал событий сайта

Отдельно от шины событий сайт ведёт журнал — что и когда менялось. Туда попадают:

module_created       модуль заведён
module_updated       вёрстка модуля или вида изменена
template_restored    нажата «Вернуть исходный код»

Первый вопрос при «сайт вдруг сломался» — что менялось и когда. Журнал на него отвечает.