IronBot: [IronBot] Sync EN/UK localization from RU

2026-05-23T17:44:26Z

[IronBot] Sync EN/UK localization from RU

Новая страница

'''en''' | [[Internal_API_UK|uk]] | [[Internal_API|ru]]

Custom Events v2 - это локальная система внутренних событий ERP. Она выполняет клиентский PHP-код внутри текущего PHP-процесса ERP без HTTP-запросов, веб-хуков и внешних очередей.

Старый механизм <code>legacy/Config/custom_api.txt</code> с функцией <code>api_function(...)</code> остается legacy-контрактом. В v2 старые названия используются только для карты совместимости. Новый клиентский код должен использовать константы <code>CustomEvent::...</code>.

== Файлы ==

Рабочий клиентский файл один:

<pre>evolution/CustomEvents/v2/handlers.php</pre>

Пример:

<pre>evolution/CustomEvents/v2/handlers.example.php</pre>

Список всех констант:

<pre>evolution/CustomEvents/Runtime/v2/CustomEvent.php</pre>

Карта старых имен в новые события:

<pre>evolution/CustomEvents/Runtime/v2/CustomEventLegacyEventMap.php</pre>

Кеш:

<pre>var/cache/CustomEvents/handlers.v2.cache.php</pre>

Лог:

<pre>var/log/custom-events-v2.log</pre>

== Как писать обработчики ==

Используется одна функция регистрации: <code>internal_event(...)</code>.

В одном файле можно зарегистрировать несколько обработчиков подряд:

<syntaxhighlight lang="php">
internal_event(
CustomEvent::TASK_CREATED,
static function ($event): bool {
$taskId = $event->get('task_id');

return true;
},
);

internal_event(
CustomEvent::CUSTOMER_STATUS_CHANGE_BEFORE,
static function ($event): bool|string {
if ((int)$event->get('new_status_id') === 0) {
return 'Запрещено переводить абонента в этот статус';
}

return true;
},
);

internal_event(
CustomEvent::CUSTOMER_CARD_PRIMARY_CONTENT_RENDER,
static function ($event): string {
$customerId = (int)$event->get('customer_id');

return '<div>Дополнительная информация по абоненту #' . $customerId . '</div>';
},
);
</syntaxhighlight>

В обработчик всегда приходит один параметр <code>$event</code>.

Данные читаются без типовых оберток:

<syntaxhighlight lang="php">
$taskId = $event->get('task_id');
$customerId = $event->get('customer_id');
$data = $event->all();
</syntaxhighlight>

Если нужен конкретный тип, приводите значение в своем коде:

<syntaxhighlight lang="php">
$taskId = (int)$event->get('task_id');
$comment = (string)$event->get('comment');
</syntaxhighlight>

== Результат обработчика ==

Обработчик возвращает простое значение:

{| class="wikitable"
! Возврат
! Значение
|-
| <code>true</code>
| Обработчик выполнен успешно
|-
| <code>false</code>
| Для события <code>*.before</code> запретить штатную операцию
|-
| <code>null</code>
| Ничего не менять
|-
| строка
| Для <code>*.before</code> запретить операцию с текстом причины; для <code>*.render</code> вывести строку/HTML
|}

События <code>*.before</code> могут отменять штатную операцию. Остальные события не должны отменять уже выполненное действие.

== Пример запрета операции ==

<syntaxhighlight lang="php">
internal_event(
CustomEvent::CUSTOMER_STATUS_CHANGE_BEFORE,
static function ($event): bool|string {
if ((int)$event->get('new_status_id') === 0) {
return 'Запрещено переводить абонента в этот статус';
}

return true;
},
);
</syntaxhighlight>

== Пример вывода HTML ==

<syntaxhighlight lang="php">
internal_event(
CustomEvent::CUSTOMER_CARD_PRIMARY_CONTENT_RENDER,
static function ($event): string {
$customerId = (int)$event->get('customer_id');

return '<div>Дополнительная информация по абоненту #' . $customerId . '</div>';
},
);
</syntaxhighlight>

== Проверка, кеш и лог ==

При изменении <code>evolution/CustomEvents/v2/handlers.php</code> ERP проверяет синтаксис через <code>php -l</code>. Если синтаксис корректный, файл копируется в <code>var/cache/CustomEvents/handlers.v2.cache.php</code>.

Runtime-лог пишется в JSON Lines в <code>var/log/custom-events-v2.log</code>. Одна строка - один вызов обработчика, ошибка или факт отсутствия обработчиков.

Пример строки:

<syntaxhighlight lang="json">
{"ts":"2026-05-10T12:01:03+03:00","event":"task.created","has_handlers":true,"handlers":1,"handler_index":0,"duration_ms":2.341,"memory_kb":18,"result":"allow","message":null}
</syntaxhighlight>

Лог ротируется в:

<pre>var/log/custom-events-v2.log.1</pre>

== Ошибки ==

Если в обработчике возникнет ошибка, ERP запишет ее в лог и продолжит работу по правилам конкретного события.

Обработчик выполняется внутри того же PHP-процесса, что и ядро ERP. Через ядро проходят тысячи операций, и медленный или ошибочный клиентский код может остановить или дестабилизировать работу всей системы. Не используйте <code>exit</code>, <code>die</code>, бесконечные циклы, тяжелые SQL-запросы без ограничений и долгие внешние операции. Держите обработчики короткими и предсказуемыми.

== Рекомендации ==

* Используйте только константы <code>CustomEvent::...</code>.
* Не пишите строку события вручную.
* Делайте обработчики короткими.
* Не вызывайте HTTP/webhook из высокочастотных событий.
* Не используйте <code>exit</code>, <code>die</code>, бесконечные циклы и тяжелые выборки без ограничений.
* Возвращайте <code>true</code>, <code>false</code>, <code>null</code> или строку.

== Все события ==

Ниже перечислены все события v2. Полный технический список констант находится в <code>evolution/CustomEvents/Runtime/v2/CustomEvent.php</code>.

Поля <code>event</code> указаны как текущий контракт данных.

=== Здания ===

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::BUILDING_CREATED</code>
| После создания здания
| <code>building_id</code>, <code>data</code>
|-
| <code>CustomEvent::BUILDING_CHANGED</code>
| После редактирования здания
| <code>building_id</code>, <code>data</code>
|}

=== Коммутация ===

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::COMMUTATION_CREATE_BEFORE</code>
| Перед созданием коммутации между объектами
| <code>source_type</code>, <code>source_id</code>, <code>target_type</code>, <code>target_id</code>, <code>data</code>
|-
| <code>CustomEvent::COMMUTATION_DELETE_BEFORE</code>
| Перед удалением коммутации между объектами
| <code>source_type</code>, <code>source_id</code>, <code>target_type</code>, <code>target_id</code>, <code>data</code>
|}

=== Главная страница ===

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::DASHBOARD_TOP_CONTENT_RENDER</code>
| При выводе текста в начальной части главной страницы
| <code>employee_id</code>, <code>data</code>
|}

=== Оборудование ===

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::DEVICE_CHANGED</code>
| После редактирования оборудования
| <code>device_id</code>, <code>device_type</code>, <code>data</code>
|-
| <code>CustomEvent::DEVICE_NOTIFICATION_DOWN</code>
| При фиксации недоступности оборудования
| <code>device_id</code>, <code>device_type</code>, <code>ip</code>, <code>data</code>
|-
| <code>CustomEvent::DEVICE_NOTIFICATION_UP</code>
| При восстановлении доступности оборудования
| <code>device_id</code>, <code>device_type</code>, <code>ip</code>, <code>data</code>
|-
| <code>CustomEvent::DEVICE_INTERFACE_PORT_NUMBER_RENDER</code>
| При выводе номера порта в таблице интерфейсов
| <code>device_id</code>, <code>interface_id</code>, <code>port_number</code>, <code>data</code>
|-
| <code>CustomEvent::DEVICE_INTERFACE_ADDITIONAL_DATA_RENDER</code>
| При выводе дополнительного содержимого в карточке оборудования
| <code>device_id</code>, <code>data</code>
|}

=== Абоненты ===

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::CUSTOMER_CREATED</code>
| После создания абонента
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_CHANGE_BEFORE</code>
| Перед редактированием абонента
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_CHANGED</code>
| После редактирования абонента
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_MERGED</code>
| После объединения абонентов
| <code>customer_id</code>, <code>target_customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_STATUS_CHANGE_BEFORE</code>
| Перед изменением статуса абонента
| <code>customer_id</code>, <code>new_status_id</code>, <code>old_status_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_STATUS_CHANGED</code>
| После изменения статуса абонента
| <code>customer_id</code>, <code>new_status_id</code>, <code>old_status_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_TARIFF_CHANGE_BEFORE</code>
| Перед изменением тарифа абонента
| <code>customer_id</code>, <code>billing_id</code>, <code>new_tariff_id</code>, <code>old_tariff_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_TARIFF_CHANGED</code>
| После изменения тарифа абонента
| <code>customer_id</code>, <code>billing_id</code>, <code>new_tariff_id</code>, <code>old_tariff_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_BALANCE_CHANGED</code>
| При изменении баланса абонента
| <code>customer_id</code>, <code>amount</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_FORMER_TRANSFER_BEFORE</code>
| Перед переводом абонента в бывшие абоненты
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_FORMER_TRANSFERRED</code>
| После перевода абонента в бывшие абоненты
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_FORMER_RESTORE_BEFORE</code>
| Перед восстановлением абонента из бывших абонентов
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_FORMER_RESTORED</code>
| После восстановления абонента из бывших абонентов
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_DISCONNECT_PLAN_BEFORE</code>
| Перед постановкой абонента на отключение
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_DISCONNECT_PLANNED</code>
| После постановки абонента на отключение
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_DISCONNECT_BEFORE</code>
| Перед отключением абонента
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_DISCONNECTED</code>
| После отключения абонента
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_DISCONNECT_CANCEL_BEFORE</code>
| Перед отменой отключения абонента
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_DISCONNECT_CANCELLED</code>
| После отмены отключения абонента
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_SERVICE_ENABLE_BEFORE</code>
| Перед подключением услуги абоненту
| <code>customer_id</code>, <code>service_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_SERVICE_ENABLED</code>
| После подключения услуги абоненту
| <code>customer_id</code>, <code>service_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_SERVICE_DISABLE_BEFORE</code>
| Перед отключением услуги абоненту
| <code>customer_id</code>, <code>service_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_SERVICE_DISABLED</code>
| После отключения услуги абоненту
| <code>customer_id</code>, <code>service_id</code>, <code>data</code>
|}

==== IP/MAC абонента ====

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::CUSTOMER_IP_ADD_BEFORE</code>
| Перед добавлением IP/MAC-адреса
| <code>customer_id</code>, <code>ip</code>, <code>mac</code>, <code>subnet_property</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_IP_ADDED</code>
| После добавления IP/MAC-адреса
| <code>customer_id</code>, <code>ip</code>, <code>mac</code>, <code>subnet_property</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_IP_DELETE_BEFORE</code>
| Перед удалением IP/MAC-адреса
| <code>customer_id</code>, <code>ip</code>, <code>mac</code>, <code>subnet_property</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_IP_DELETED</code>
| После удаления IP/MAC-адреса
| <code>customer_id</code>, <code>ip</code>, <code>mac</code>, <code>subnet_property</code>, <code>data</code>
|}

==== Метки абонента ====

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::CUSTOMER_TAG_ADD_BEFORE</code>
| Перед добавлением метки абоненту
| <code>customer_id</code>, <code>tag_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_TAG_ADDED</code>
| После добавления метки абоненту
| <code>customer_id</code>, <code>tag_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_TAG_DELETE_BEFORE</code>
| Перед удалением метки абонента
| <code>customer_id</code>, <code>tag_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_TAG_DELETED</code>
| После удаления метки абонента
| <code>customer_id</code>, <code>tag_id</code>, <code>data</code>
|}

==== Личный кабинет абонента ====

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::CUSTOMER_PORTAL_REGISTRATION_BEFORE</code>
| Перед регистрацией абонента в личном кабинете
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_PORTAL_REGISTERED</code>
| После регистрации абонента в личном кабинете
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_PORTAL_LOGIN_BEFORE</code>
| Перед входом абонента в личный кабинет
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_PORTAL_DASHBOARD_RENDER</code>
| При выводе содержимого на главной странице личного кабинета
| <code>customer_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_PORTAL_PAGE_RENDER</code>
| При выводе содержимого на страницах личного кабинета
| <code>customer_id</code>, <code>page_mode</code>, <code>page_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_PORTAL_HEAD_RENDER</code>
| При выводе содержимого после <code>head</code> в личном кабинете
| <code>customer_id</code>, <code>data</code>
|}

==== Карточка абонента ====

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::CUSTOMER_CARD_PRIMARY_CONTENT_RENDER</code>
| При выводе основного содержимого в карточке абонента
| <code>customer_id</code>, <code>mode</code>, <code>employee_id</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_CARD_SECONDARY_CONTENT_RENDER</code>
| При выводе дополнительного содержимого в карточке абонента
| <code>customer_id</code>, <code>mode</code>, <code>employee_id</code>, <code>ip_mac</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_CARD_IP_MAC_CONTENT_RENDER</code>
| При выводе информации возле IP/MAC-адресов абонента
| <code>customer_id</code>, <code>ip</code>, <code>mac</code>, <code>data</code>
|-
| <code>CustomEvent::CUSTOMER_CARD_SMS_CONTENT_RENDER</code>
| При выводе содержимого отправки SMS в карточке абонента
| <code>customer_id</code>, <code>data</code>
|}

=== Сотрудники ===

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::EMPLOYEE_MESSAGE_CREATED</code>
| После создания сообщения сотруднику
| <code>receiver_employee_id</code>, <code>message_id</code>, <code>data</code>
|-
| <code>CustomEvent::EMPLOYEE_CHANGED</code>
| После редактирования сотрудника
| <code>employee_id</code>, <code>data</code>
|-
| <code>CustomEvent::EMPLOYEE_PERSONAL_SECTION_CONTENT_RENDER</code>
| При выводе информации в персональном разделе сотрудника
| <code>employee_id</code>, <code>data</code>
|}

==== Табель работ ====

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::EMPLOYEE_TIMESHEET_PRINT_HEADER_RENDER</code>
| При выводе шапки печатного табеля
| <code>employee_id</code>, <code>period</code>, <code>data</code>
|-
| <code>CustomEvent::EMPLOYEE_TIMESHEET_PRINT_FOOTER_RENDER</code>
| При выводе подвала печатного табеля
| <code>employee_id</code>, <code>period</code>, <code>data</code>
|}

=== Склад ===

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::INVENTORY_TRANSFER_BEFORE</code>
| Перед перемещением ТМЦ
| <code>inventory_id</code>, <code>operation_id</code>, <code>data</code>
|-
| <code>CustomEvent::INVENTORY_TRANSFERRED</code>
| После перемещения ТМЦ
| <code>inventory_id</code>, <code>operation_id</code>, <code>data</code>
|}

=== Задания ===

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::TASK_CARD_RENDER</code>
| При выводе содержимого в карточке задания
| <code>task_type_id</code>, <code>task_id</code>, <code>employee_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_WORK_DATE_RENDER</code>
| При выводе содержимого возле даты работ
| <code>task_type_id</code>, <code>task_id</code>, <code>employee_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_CREATE_BEFORE</code>
| Перед созданием задания
| <code>task_type_id</code>, <code>author_employee_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_CREATED</code>
| После создания задания
| <code>task_id</code>, <code>task_type_id</code>, <code>author_employee_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_DELETE_BEFORE</code>
| Перед удалением задания
| <code>task_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_CHANGE_BEFORE</code>
| Перед редактированием задания
| <code>task_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_CHANGED</code>
| После редактирования задания
| <code>task_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_COMMENT_CREATE_BEFORE</code>
| Перед добавлением комментария к заданию
| <code>task_id</code>, <code>comment</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_COMMENT_CREATED</code>
| После добавления комментария к заданию
| <code>task_id</code>, <code>comment_id</code>, <code>comment</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_COMMENT_CHANGED</code>
| После редактирования комментария к заданию
| <code>task_id</code>, <code>comment_id</code>, <code>comment</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_COMMENT_TEXT_RENDER</code>
| При выводе текста комментария задания
| <code>task_id</code>, <code>comment_id</code>, <code>comment</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_DIVISION_ASSIGN_BEFORE</code>
| Перед добавлением подразделения к заданию
| <code>task_id</code>, <code>division_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_DIVISION_REMOVE_BEFORE</code>
| Перед исключением подразделения из задания
| <code>task_id</code>, <code>division_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_EMPLOYEE_ASSIGN_BEFORE</code>
| Перед добавлением исполнителя к заданию
| <code>task_id</code>, <code>employee_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_EMPLOYEE_REMOVE_BEFORE</code>
| Перед исключением исполнителя из задания
| <code>task_id</code>, <code>employee_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_WATCHER_DIVISION_ASSIGN_BEFORE</code>
| Перед добавлением подразделения наблюдателем
| <code>task_id</code>, <code>division_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_WATCHER_EMPLOYEE_ASSIGN_BEFORE</code>
| Перед добавлением сотрудника наблюдателем
| <code>task_id</code>, <code>employee_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_OBJECT_ATTACHED</code>
| После добавления объекта к заданию
| <code>task_id</code>, <code>object_type</code>, <code>object_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_OBJECT_DETACHED</code>
| После исключения объекта из задания
| <code>task_id</code>, <code>object_type</code>, <code>object_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_RETURNED_TO_AUTHOR</code>
| После возврата задания автору
| <code>task_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_STATE_CHANGE_BEFORE</code>
| Перед изменением статуса задания
| <code>task_id</code>, <code>old_state_id</code>, <code>new_state_id</code>, <code>data</code>
|-
| <code>CustomEvent::TASK_STATE_CHANGED</code>
| После изменения статуса задания
| <code>task_id</code>, <code>old_state_id</code>, <code>new_state_id</code>, <code>data</code>
|}

=== Сооружения связи ===

{| class="wikitable"
! Константа
! Когда вызывается
! Данные <code>$event</code>
|-
| <code>CustomEvent::NODE_CARD_ADDITIONAL_DATA_RENDER</code>
| При выводе дополнительного содержимого в карточке сооружения связи
| <code>node_id</code>, <code>data</code>
|-
| <code>CustomEvent::NODE_CARD_PRIMARY_CONTENT_RENDER</code>
| При выводе основного содержимого в карточке сооружения связи
| <code>node_id</code>, <code>data</code>
|}

Internal API EN - История изменений

IronBot: [IronBot] Fix EN localization text

IronBot: [IronBot] Sync EN/UK localization from RU