Модуль «Обработчики событий»

1. Описание

Модуль listevent («Обработчики событий») — это административный инструмент для Bitrix24, который:

  • Регистрирует собственные обработчики событий разных модулей (main, crm, tasks, iblock, sale, im, disk и др.) через единый интерфейс.

  • Создаёт PHP-классы обработчиков автоматически в каталоге модуля и подключает их к ядру Bitrix через RegisterModuleDependences.

  • Позволяет просматривать, добавлять, редактировать сортировку и удалять привязки событий без правки кода вручную.

  • Ведёт логирование ошибок из обработчиков в файл и при необходимости отправляет уведомления об ошибках в Bitrix24 (пользователю или в чат через модуль im).

Модуль не реализует бизнес-логику приложения — он выступает конструктором и реестром обработчиков событий с логированием и уведомлениями.

2. Структура модуля

listevent/
├── config/
│   ├── config.php       # Класс Config: чтение .env и .ini
│   ├── .env             # Идентификация модуля (ID, версия, имя, партнёр)
│   └── .ini             # Настройки по умолчанию (логи, уведомления, версии PHP/Битрикс)
├── install/
│   ├── index.php        # Класс listevent (CModule): установка/удаление
│   └── step.php         # Страница после установки
├── lib/
│   ├── events/
│   │   ├── BaseEvent.php   # Регистрация/снятие обработчиков, генерация файлов, работа с load.ini
│   │   └── EventList.php   # Справочник событий по модулям (main, crm, tasks, sale и др.)
│   ├── exceptions/
│   │   └── handler.php     # Глобальные обработчики ошибок (опционально, по умолчанию не активны)
│   ├── handlers/           # Сгенерированные и кастомные обработчики (в .gitignore)
│   │   └── <module>/       # Например: tasks/, crm/, main/
│   │       └── <Handler>.php
│   ├── im/
│   │   ├── notifier.php   # Отправка уведомлений об ошибках (user/chat)
│   │   └── send.php       # IM: notify(), message(), chat()
│   └── logger/
│       ├── logger.php     # Запись в файл, чтение, очистка лога
│       └── listevent.log  # Файл лога (создаётся при включённом логировании)
├── include.php          # Точка входа: автозагрузка классов модуля
├── options.php          # Админ-страница настроек (вкладки: События, Справочник, Настройки, Лог, О модуле)
├── load.ini             # Создаётся в рантайме: маппинг классов обработчиков → пути к файлам
└── .gitignore           # Исключает lib/handlers/* (обработчики предполагается хранить отдельно)

  • Куда ставится модуль: в каталог модулей Bitrix, например bitrix/local/modules/listevent/.

  • Куда пишутся обработчики: в lib/handlers/<модуль>/<ИмяКласса>.php (путь задаётся в .ini как HANDLER_PATH=lib/handlers).

  • Куда пишется лог: в файл из опции LOG_FILE (по умолчанию listevent.log в каталоге lib/logger/).

3. Предназначение

  • Единый интерфейс — не нужно вручную вызывать RegisterModuleDependences и создавать файлы обработчиков в разных модулях.

  • Меньше ошибок — модуль сам генерирует заготовку класса с try/catch, логированием и неймспейсом Handlers.

  • Прозрачность — в админке видно, какие события зарегистрированы (только модулем listevent или все по выбранному модулю).

  • Безопасность и отладка — логирование ошибок в файл и опциональная отправка в мессенджер Bitrix24 (пользователю или в чат).

4. Устройство

  • Конфиг в .env и .ini — разделение идентификации модуля (.env) и настроек (.ini) упрощает обновление и деплой.

  • load.ini — Bitrix подключает модуль через include.php; автозагрузка классов обработчиков реализована через общий массив в include.php + динамический load.ini, чтобы не хардкодить каждый новый обработчик.

  • Справочник событий в EventList — список событий по модулям хранится в коде для единообразия и подсказок в интерфейсе (название события, описание).

  • Обработчики в .gitignore — предполагается, что сгенерированные и кастомные обработчики хранятся или версионируются отдельно от ядра модуля.

5. Использование

5.1. Установка

  1. Скопировать модуль в bitrix/modules/listevent/.

  2. В админке: «Настройки» → «Настройки продукта» → «Модули» → найти «Обработчики событий» → «Установить».

  3. При установке проверяются версии PHP (≥ 8.0) и Битрикс (≥ 20.0.0). Опции из config/.ini записываются в БД.

  4. После установки выводится сообщение «Модуль успешно установлен» и кнопка «Вернуться в список модулей».

5.2. Админ-страница настроек

Открывается по адресу вида:

/bitrix/admin/settings.php?lang=ru&mid=listevent

Доступ: право на чтение модуля (GetGroupRight($module_id) >= 'R'). Для сохранения настроек и изменений событий нужно право на запись (>= 'W').

Вкладки:

Вкладка

Назначение

События

Выбор модуля, список зарегистрированных обработчиков только модуля listevent, добавление/редактирование/удаление привязок, сортировка.

Справочник

Список всех обработчиков выбранного модуля (от любых модулей). Только просмотр.

Настройки

Включение логирования, путь к файлу лога, включение уведомлений об ошибках, тип (пользователь/чат) и получатель (ID пользователя или ID чата).

Лог ошибок

Просмотр содержимого файла лога. Если логирование выключено — выводится подсказка включить его в настройках.

О модуле

Название, версия, разработчик, описание, список возможностей.

5.3. Добавление обработчика события

  1. Вкладка «События».

  2. Выбрать модуль (например, tasks).

  3. Нажать «Добавить событие».

  4. Указать:

    • Название события — из выпадающего списка (справочник из EventList).

    • Класс-обработчик — имя класса без префикса Handlers\ (например, BeforeUpdate).

    • Метод-обработчик — метод этого класса (например, update).

    • Сортировка — число, порядок вызова среди других обработчиков (по умолчанию 100).

  5. Отправить форму (или кнопка «Добавить» в форме).

В результате:

  • В lib/handlers/<модуль>/<Класс>.php создаётся или дополняется класс в неймспейсе Handlers с методом-заглушкой в try/catch и вызовом Logger::write при ошибке.

  • В load.ini добавляется строка для автозагрузки.

  • Вызывается RegisterModuleDependences(..., listevent, Handlers\<Класс>, <метод>, sort, ...).

Редактирование — по сути снятие старой привязки и регистрация новой (можно изменить сортировку). При удалении вызывается UnRegisterModuleDependences и удаляется запись из load.ini.

5.4. Настройки

Сохраняются через Option::set($module_id, ...) в таблицу опций Bitrix:

Опция

Описание

LOG_ENABLED

Включить логирование (Y/N).

LOG_LEVEL

Уровень логирования (из .ini, в UI не редактируется).

LOG_FILE

Имя/путь файла лога (по умолчанию из .ini).

NOTIFY_ON_ERROR

Отправлять уведомления об ошибках (Y/N).

NOTIFY_TYPE

user или chat.

NOTIFY_TARGET

ID пользователя или ID чата.

MODULE_ACTIVE

Активность модуля (Y/N).

MODULE_SORT

Сортировка модуля.

HANDLER_PATH

Путь к каталогу обработчиков относительно корня модуля.

5.5. Логирование и уведомления

  • Logger — при вызове Logger::write($message, $exception) пишет в файл лога (если LOG_ENABLED = Y) и вызывает Notifier::sendError($exception).

  • Notifier — в зависимости от NOTIFY_TYPE вызывает Send::notify() (уведомление пользователю) или Send::chat() (сообщение в чат). Для этого должен быть доступен модуль im.

6. Внутреннее устройство

  • include.php — подключает config/config.php, объединяет статический список классов с содержимым load.ini и регистрирует автозагрузку через Loader::registerAutoLoadClasses(listevent, $load).

  • BaseEvent::registerModule — формирует путь к файлу обработчика, создаёт или обновляет класс (добавляет метод при необходимости), добавляет запись в load.ini, вызывает RegisterModuleDependences.

  • BaseEvent::unRegisterModule — удаляет запись из load.ini, вызывает UnRegisterModuleDependences.

  • BaseEvent::getEvents — обходит события выбранного модуля из EventList, для каждого вызывает GetModuleEvents; при $all = false возвращает только обработчики с TO_MODULE_ID = listevent, при $all = true — все.

  • EventList — константа EVENTS: массив модулей и их событий с описаниями для UI и выбора события при добавлении.

Собственных таблиц в БД модуль не создаёт. Используются только механизмы ядра: регистрация модуля, опции, RegisterModuleDependences / UnRegisterModuleDependences / GetModuleEvents.

7. Зависимости

  • Ядро Bitrix: CModule, CAdminMessage, CAdminTabControl, Loader, Option, Loc, RegisterModuleDependences, UnRegisterModuleDependences, GetModuleEvents, CheckVersion, сессия (check_bitrix_sessid, bitrix_sessid_post).

  • Модуль im — нужен для отправки уведомлений об ошибках (пользователю или в чат). Без него уведомления работать не будут.

  • PHP: не ниже 8.0 (задаётся в config/.ini, секция [PERMISSIONS]).

  • Версия Битрикс: не ниже 20.0.0 (в том же блоке).

8. Ограничения

  • Количество обработчиков — ограничено только механизмами Bitrix и размером списка событий в EventList. Добавление многих обработчиков на одно и то же событие увеличивает время отработки этого события.

  • Размер лога — ограничен только диском. Очистка лога через код: Logger::clear() (в UI кнопки очистки пока что не быть).

  • Справочник событий — список модулей и событий в EventList::EVENTS фиксированный; добавление новых событий не подразумевается.

9. Удаление модуля

При удалении вызывается только UnRegisterModule($this->MODULE_ID). Таблицы модуль не создаёт, поэтому отдельной очистки БД нет. Файлы модуля (в т.ч. lib/handlers/, load.ini, лог) остаются на диске — при необходимости их нужно удалять вручную.

10. Пример обработчика

При добавлении события с классом BeforeUpdate и методом update для модуля tasks создаётся файл вида:

// lib/handlers/tasks/BeforeUpdate.php
<?php

namespace Handlers;

use Listevent\Lib\Logger;

class BeforeUpdate
{
    public static function update (...$values): void
    {
        try {
            // Весь код писать в этом блоке!!!
        } catch (\Throwable $t) {
            Logger::write($t->getMessage(), $t);
        }
    }
}

Параметры ...$values нужно заменить на реальные аргументы события.

11. Важные замечания

  • load.ini создаётся и изменяется при добавлении/удалении обработчиков. В репозитории его может не быть — он генерируется в рантайме.

  • lib/handlers/ исключён из git — обработчики предполагается хранить или версионировать отдельно.

  • В коде обработчика глобальных ошибок (lib/exceptions/handler.php) в ссылке на настройки может быть указан другой mid — для актуального модуля следует использовать mid=listevent.

  • Для уведомлений об ошибках должен быть установлен и доступен модуль im.

  • Модуль представляет готовое решение для работы, но будет доработан в дальнейшем.