Системные хуки — Документация Webasyst

Для регистрации обработчиков системных событий (хуков) используйте идентификатор приложения webasyst. Подробнее об обработке событий.

backend_assets
backend_before_email_send_test
backend_dashboard_before_action
backend_dispatch_miss
backend_header
backend_login
cli_finished
cli_started
mail_send.after
mail_send.before
search_content
signup
sms_send.after
sms_send.before
view_helper_call
view_helper_read
view_page
view_pages
waid_auth

backend_assets

Позволяет добавлять дополнительное содержимое в секцию <head> страниц панели управления.

Возвращаемое значение

Строка HTML-кода.

Пример кода обработчика

return "<script>console.log('I am executed in the backend.');</script>";

backend_before_email_send_test

Срабатывает перед проверочной отправкой email-сообщения в разделе «Настройки → Email-шаблоны».

Параметры

$params['channel'] waVerificationChannel
Экземпляр класса, с помощью которого выполняется отправка email-сообщения.
$params['data'] array
Информация об отправляемом сообщении.

Возвращаемое значение

Сообщение об ошибке в массиве вида

[
    'errors' => [
        [
            'field' => '...',
            'message' => '...',
        ]
    ],
]

Доступные значения поля field:

'[channel_id]': отображение сообщения об ошибке под полем для ввода адреса получателя проверочного сообщения;
'[recipient]': отображение сообщения об ошибке рядом с полем для ввода адреса получателя проверочного сообщения.

Пример кода обработчика

if (strpos(ifset($params, 'data', 'recipient', ''), 'test@') !== 0) {
    return [
        'errors' => [
            [
                'field' => '[recipient]',
                'message' => _wp('Use only email addresses starting with test@ for email templates testing.'),
            ]
        ],
    ];
}

backend_dashboard_before_action

Срабатывает при выполнении экшенов, описанных в классе webasystBackendActions.

Параметры

$params['action'] string
Идентификатор выполняемого экшена.

Пример кода обработчика

if ($params['action'] == 'default') {
    waLog::log(
        sprintf_wp(
            'Dashboard has been displayed to user %s.',
            wa()->getUser()->getName()
        ),
        'myhandler.log'
    );
}

backend_dispatch_miss

Срабатывает при попытке открыть панель управления несуществующего приложения.

Параметры

$app string
Идентификатор приложения из адреса открытой страницы.

Возвращаемое значение

Флаг, означающий необходимость скрыть сообщение об ошибке «Страница не найдена (404)».

Пример кода обработчика

waLog::log(
    sprintf_wp(
        'User %s attempted to open %s app.',
        wa()->getUser()->getName(), $app_id
    ),
    'myhandler.log'
);

backend_header

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

Параметры

$params['current_app'] string
Идентификатор текущего приложения.
$params['ui_version'] string
Обозначение режима интерфейса: '1.3' или '2.0'.

Возвращаемое значение

Массив со следующими ключами:

header_middle (только в интерфейсе 1.3): содержимое для отображения в средней части панели.
header_bottom: содержимое для отображения в нижней части панели.
notification (только в интерфейсе 2.0): содержимое для отображения в списке всплывающих уведомлений под колокольчиком.
user_area (только в интерфейсе 2.0): содержимое для отображения рядом с иконкой текущего пользователя в виде массива со следующими ключами:
user_area['aux']: содержимое для отображения рядом с элементами управления в правой части панели.

Пример кода обработчика

return [
    // только 1.3
    'header_middle' => '<!-- ... -->',
    'header_bottom' => '<!-- ... -->',
    // только 2.0
    'notification' => '<!-- ... -->',
    // только 2.0
    'user_area' => [
        'aux' => '<!-- ... -->',
    ],
];

backend_login

Срабатывает после авторизации пользователя в панели управления.

Параметры

$params['redirect_url'] string
URL, на который должен быть перенаправлен пользователь после авторизации.

Возвращаемое значение

Массив вида

[
    // Новый URL, на который должен быть перенаправлен пользователь после авторизации
    'redirect_url' => '...',
]

Пример кода обработчика

if (myappHelper::checkRedirectUrl($params['redirect_url'])) {
    return [
        'redirect_url' => 'myapp/redirect/',
    ];
}

cli_finished

Срабатывает после выполнения CLI-контроллера.

Параметры

$params['app'] string
Идентификатор приложения, к которому относится CLI-контроллер.
$params['class'] string
Имя класса CLI-контроллера.
$params['exists'] bool
Флаг, означающий существование указанного класса.
$params['successful_execution'] bool
Флаг, означающий успешное выполнение контроллера — без зарегистрированных исключений.

Пример кода обработчика

if ($params['exists'] && !$params['successful_execution']) {
    waLog::log(
        sprintf_wp(
            'Execution of CLI class %s of %s app could not be completed.',
            $params['class'], $params['app']
        ),
        'myhandler.log'
    );
}

cli_started

Срабатывает перед выполнением CLI-контроллера.

Параметры

$params['app'] string
Идентификатор приложения, к которому относится CLI-контроллер.
$params['class'] string
Имя класса CLI-контроллера.
$params['exists'] bool
Флаг, означающий существование указанного класса.

Пример кода обработчика

if (!$params['exists']) {
    waLog::log(
        sprintf_wp(
            'Execution of non-existent CLI class %s of %s app was attempted.',
            $params['class'], $params['app']
        ),
        'myhandler.log'
    );
}

mail_send.after

Срабатывает после отправки email-сообщения классом waMail.

Параметры

$params['message'] Swift_Mime_Message
Объект email-сообщения.
$params['result'] int
Количество отправленных сообщений с учётом всех указанных адресатов.
$params['exception'] string
Текст зарегистрированного исключения.

Пример кода обработчика

waLog::log(
    sprintf_wp(
        'Email message has been sent to %s.',
        implode(', ', array_keys($params['message']->getTo()))
    ),
    'myhandler.log'
);

mail_send.before

Срабатывает перед отправкой email-сообщения классом waMail.

Параметры

$params['message'] Swift_Mime_Message
Объект email-сообщения.

Пример кода обработчика

waLog::log(
    sprintf_wp(
        'Attempting to send email message to %s...',
        implode(', ', array_keys($params['message']->getTo()))
    ),
    'myhandler.log'
);

search_content

Позволяет учитывать в системном механизме поиска (например, при обращении к сервису Webasyst AI) содержимое страниц сайта, формируемое вашим плагином или приложением.

Параметры

$params['links'] array
Список ссылок на страницы сайта, соответствующих поисковому запросу пользователя. Каждый элемент списка — массив со следующими ключами:
- $params['links'][]['handle'] string Идентификатор правила маршрутизации, которому соответствует найденная страница, построенный по шаблону [app_id]/[module_id]/[action_id]. Если страница доступна на сайте благодаря использованию собственной маршрутизации плагина, то в этом значении будут указаны module_id и action_id плагина, а не приложения.
- $params['links'][]['url'] string Абсолютный URL страницы.
- $params['links'][]['domain'] string Доменное имя сайта.
- $params['links'][]['settlement'] array|null Параметры маршрутизации раздела сайта, в пределах которого доступна страница, — запись из системного конфигурационного файла wa-config/routing.php.
- $params['links'][]['app_route'] array|null Параметры маршрутизации — из конфигурационного файла lib/config/routing.php — приложения или плагина с ключами 'url' (шаблон правила маршрутизации), 'module' (идентификатор модуля), 'action' (идентификатор экшена), 'app' (идентификатор приложения), 'plugin' (идентификатор плагина — доступен, если страница сформирована с использованием правила маршрутизации плагина).
- $params['links'][]['url_params'] array|null Значения, используемые для маршрутизации HTTP-запросов к данной странице и необходимые для построения её URL.
- $params['links'][]['result'] string|null Текстовое содержимое страницы, которое может заполнить обработчик хука в вашем приложении или плагине. Если в этом поле уже хранится значение, отличное от null, значит, оно уже заполнено другим приложением или плагином при обработке хука. В этом случае либо пропускайте заполнение этого поля, либо при необходимости аккуратно измените (например, можно дополнить его, если ваш плагин добавляет полезное содержимое на стандартную страницу приложения — страницу товара или категории на витрине онлайн-магазина).

Пример кода обработчика

// выбираем из всех полученных ссылок на страницы только те,
// на содержимое которых может влиять данный плагин
$plugin_links_by_handle = [];

foreach ($params['links'] as &$link) {
    if (!empty($link['result'])) {
        // поле 'result' в свойствах страницы уже заполнено другим обработчиком — пропускаем
        continue;
    }

    if (
        $link['settlement']['app'] != wa()->getApp()
        || ($link['app_route']['plugin'] ?? null) != $this->id
    ) {
        // страница не относится к данному плагину — пропускаем
        continue;
    }

    // группируем оставшиеся ссылки (относящиеся к данному плагину) по значению ключа 'handle';
    // это особенно актуально, если плагин показывает на сайте полезное для поиска содержимое на разных видах страниц
    $links_by_handle[$link['handle']][] = &$link;
}

unset($link);

// проверяем, переданы ли в обработчик хука адреса страниц плагина,
// которые генерируются каким-то конкретным сочетанием module_id/action_id, например, 'frontend/custom'
$custom_page_links = &$plugin_links_by_handle[sprintf('%s/frontend/custom', wa()->getApp())] ?? [];

if ($custom_page_links) {
    // получаем значения параметров маршрутизации, соответствующие адресам конкретных страниц
    $page_urls = array_filter(array_map(function ($link) {
        // например, в маршрутизации страниц плагина может использоваться некий параметр 'url'
        return $link['url_params']['url'] ?? null;
    }, $custom_page_links));

    if ($page_urls) {
        // получаем содержимое для этих страниц из таблицы плагина в базе данных
        $pages = (new someappMyPluginModel())
            ->select('url, content')
            ->where('url IN (?)', $page_urls)
            ->fetchAll('url', true);
    }

    if (!empty($pages)) {
        array_walk($page_links, function (&$link) use ($pages) {
            $page_content = $pages[$link['url_params']['url']] ?? null;

            if ($page_content) {
                // заполняем поле 'result' для найденной страницы текстовым содержимым из базы данных
                $link['result'] = _wp('Some custom content') . ': ' . $page_content;
            }
        });
    }
}

Примечания

Для тестирования обработчика хука можно запускать в «песочнице» код следующего вида:

(new waServicesSearch())->getDocumentsByLinks([
    [
        'domain' => 'localhost',
        'url' => 'http://localhost/some/page/url/',
        'title' => '',
        'passages' => [],
    ],
]);

signup

Срабатывает после регистрации нового посетителя сайта.

Параметры

$contact waContact
Новый зарегистрированный контакт с заполненным полем 'password'.

Пример кода обработчика

waLog::log(
    sprintf_wp(
        'Contact %s has just signed up.',
        $contact->getName()
    ),
    'myhandler.log'
);

sms_send.after

Срабатывает после отправки SMS-сообщения классом waSMS.

Параметры

$params['to'] int
Номер телефона получателя.
$params['text'] string
Текст сообщения.
$params['from'] string
Обозначение отправителя.
$params['adapter'] waSMS
Экземпляр класса SMS-плагина, используемого для отправки сообщения.
$params['result'] bool
Флаг, означающий успешную отправку сообщения.

Пример кода обработчика

if (empty($params['result'])) {
    waLog::log(
        sprintf_wp(
            'SMS message could not be sent to %s by %s class.',
            $params['to'], get_class($params['adapter'])
        ),
        'myhandler.log'
    );
}

sms_send.before

Срабатывает перед отправкой SMS-сообщения классом waSMS.

Параметры

$params['to'] int
Номер телефона получателя.
$params['text'] string
Текст сообщения.
$params['from'] string
Обозначение отправителя.
$params['adapter'] waSMS
Экземпляр класса SMS-плагина, используемого для отправки сообщения.

Пример кода обработчика

waLog::log(
    sprintf_wp(
        'Attempting to send SMS message to %s by %s class.',
        $params['to'], get_class($params['adapter'])
    ),
    'myhandler.log'
);

view_helper_call

Срабатывает при попытке вызвать несуществующий метод хелпера шаблона.

Параметры

$params['name'] string
Наименование метода хелпера.
$params['arguments'] array
Массив параметров, переданных при вызове метода.

Возвращаемое значение

Произвольное непустое значение, которое необходимо вернуть в шаблон.

Пример кода обработчика

return sprintf_wp(
    'Registered call of an unknown method with parameters "%s"',
    var_export($params, true)
);

view_helper_read

Срабатывает при попытке получить значение несуществующего свойства хелпера шаблона.

Параметры

$params['name'] string
Наименование свойства хелпера.

Возвращаемое значение

Произвольное непустое значение, которое необходимо вернуть в шаблон.

Пример кода обработчика

return sprintf_wp(
    'Registered attempt to read unknown property "%s"',
    $params['name']
);

view_page

Срабатывает при выполнении метода хелпера шаблона {$wa->app_id->page()}.

Параметры

$page array
Свойства страницы приложения.

Пример кода обработчика

public function viewPage(&$page)
{
    $page['content'] = preg_replace('~\s+~', ' ', $page['content']);
}

view_pages

Срабатывает при выполнении метода хелпера шаблона {$wa->app_id->pages()}.

Параметры

$pages array
Свойства страниц приложения.

Пример кода обработчика

public function viewPages(&$pages)
{
    array_walk($pages, function(&$page) {
        $page['title'] = preg_replace('~\s+~', ' ', $page['title']);
    });
}

waid_auth

Срабатывает после авторизации пользователя в панели управления с Webasyst ID. Позволяет перенаправить пользователя на указанный URL или показать сообщение об ошибке.

Параметры

$params['type'] string
Фиксированное значение 'backend'.
$params['dispatch'] array
Значения из раскодированного GET-параметра 'dispatch'.

Возвращаемое значение

Для режима интерфейса 1.3

Вариант 1

Массив вида

[
    'header_top' => '...', // содержимое в верхней части страницы
    'header_middle' => '...', // содержимое под главным меню
    'header_bottom' => '...', // содержимое над основной частью страницы
]

Вариант 2

Строковое значение, используемое в качестве дополнительного содержимого под главным меню (только для режима интерфейса 1.3).

Для режима интерфейса 2.0

Массив вида

[
    'header_top' => '...', // содержимое в верхней части страницы
    'notification' => '...', // содержимое рядом с иконкой уведомлений
    'user_area' => [ // содержимое в главном меню
        'main' => '...', // основное
        'aux' => '...', // вспомогательное
    ],
]

Пример кода обработчика

if ($params['current_app'] == 'myapp') {
    return [
        'header_top' => myappHelper::getTopBannerHtml(),
    ];
}