Событие onBeforeResultAdd в 1С-Битрикс: перехват и обработка данных веб-форм<

При разработке сайтов на 1С-Битрикс часто возникает необходимость вмешаться в процесс сохранения веб-формы: проверить введённые данные, изменить их перед записью, отправить копию заявки в сторонний сервис или добавить пользователя в группу. Для этих задач платформа предоставляет мощный инструмент — событие onBeforeResultAdd модуля «Веб-формы».

Что такое onBeforeResultAdd?

Это событие вызывается непосредственно перед добавлением нового результата веб-формы в базу данных. Оно позволяет разработчику получить доступ к отправленным данным, изменить их или полностью заблокировать сохранение, если данные не удовлетворяют определённым условиям.

Синтаксис и параметры

Обработчик события регистрируется через функцию AddEventHandler и должен иметь следующую сигнатуру:

function НазваниеОбработчика($WEB_FORM_ID, &$arFields, &$arrVALUES)
{
    // логика обработки
}

AddEventHandler('form', 'onBeforeResultAdd', 'НазваниеОбработчика');

Параметры:

• $WEB_FORM_ID — идентификатор веб-формы (число). Позволяет применить обработчик только к конкретной форме.
• &$arFields — массив полей результата для записи в БД (передаётся по ссылке).
• &$arrVALUES — массив значений ответов, отправленных пользователем. Ключи имеют вид form_ТИП_ЧИСЛО, например form_text_29 или form_textarea_30.

Оба массива передаются по ссылке, поэтому изменения, внесённые в обработчике, повлияют на сохраняемые данные.

Типичные сценарии использования

1. Проверка и модификация данных

Событие позволяет реализовать кастомную валидацию, выходящую за рамки стандартных настроек формы. Если данные некорректны, можно прервать сохранение с выводом сообщения об ошибке:

AddEventHandler('form', 'onBeforeResultAdd', 'validateFormData');

function validateFormData($WEB_FORM_ID, &$arFields, &$arrVALUES)
{
    global $APPLICATION;

    // применяем только к форме с ID = 5
    if ($WEB_FORM_ID == 5) {
        $phone = $arrVALUES['form_text_12'];
        // проверяем формат телефона
        if (!preg_match('/^\+7 \(\d{3}\) \d{3}-\d{2}-\d{2}$/', $phone)) {
            $APPLICATION->ThrowException('Введите телефон в формате +7 (XXX) XXX-XX-XX');
            return false; // прерываем сохранение
        }
    }
}

Для возврата ошибки используется метод ThrowException() глобального объекта $APPLICATION. Система покажет это сообщение пользователю.

2. Интеграция с внешними сервисами

Частая задача — автоматическая передача заявок в CRM-систему. В обработчике события можно отправить данные по API во внешний сервис:

AddEventHandler('form', 'onBeforeResultAdd', 'sendToExternalCRM');

function sendToExternalCRM($WEB_FORM_ID, &$arFields, &$arrVALUES)
{
    if ($WEB_FORM_ID == 7) {
        $data = [
            'name' => $arrVALUES['form_text_23'],
            'phone' => $arrVALUES['form_text_24'],
            'comment' => $arrVALUES['form_textarea_22']
        ];

        // curl-запрос к внешнему API
        $ch = curl_init('https://crm.example.com/api/leads');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_exec($ch);
        curl_close($ch);
    }
}

Важно: выполнение запросов в обработчике события должно быть быстрым, чтобы не задерживать ответ пользователю.

3. Защита от спама с использованием honeypot

Метод «honeypot» (скрытое поле, заполняемое только ботами) эффективно блокирует автоматическую отправку форм:

AddEventHandler('form', 'onBeforeResultAdd', 'honeypotSpamProtection');

function honeypotSpamProtection($WEB_FORM_ID, &$arFields, &$arrVALUES)
{
    global $APPLICATION;

    // формы, которые нужно защищать
    $protectedForms = [4, 9];

    if (in_array($WEB_FORM_ID, $protectedForms) && !empty($arrVALUES['form_text_46'])) {
        $APPLICATION->ThrowException('Обнаружена подозрительная активность');
        return false;
    }
}

В самой форме создаётся скрытое CSS-поле, которое не видно человеку, но заполняется ботами.

4. Добавление пользователя в группу

Можно автоматически регистрировать пользователя и добавлять его в определённую группу при заполнении формы:

AddEventHandler('form', 'onBeforeResultAdd', 'addUserToGroup');

function addUserToGroup($WEB_FORM_ID, &$arFields, &$arrVALUES)
{
    if ($WEB_FORM_ID == 19) {
        $user = new CUser;
        $userFields = [
            'NAME' => $arrVALUES['form_text_236'],
            'EMAIL' => $arrVALUES['form_text_227'],
            'LOGIN' => $arrVALUES['form_text_238'],
            'PASSWORD' => $arrVALUES['form_password_239'],
            'CONFIRM_PASSWORD' => $arrVALUES['form_password_239'],
            'GROUP_ID' => [6, 8], // ID групп
            'ACTIVE' => 'Y'
        ];

        $userId = $user->Add($userFields);
        if ($userId) {
            // можно сохранить ID пользователя в скрытое поле формы
            $arrVALUES['form_hidden_50'] = $userId;
        }
    }
}

При таком подходе важно не переопределять переменную $arFields, если она требуется для дальнейшей обработки самой формой.

Обработка ошибок

Для прерывания сохранения формы с выводом сообщения используется комбинация:

$APPLICATION->ThrowException('Текст ошибки');
return false;

Важно: просто вернуть false недостаточно — необходимо вызвать ThrowException, иначе пользователь не увидит причину отказа.

Где размещать код?

Обработчики событий рекомендуется добавлять в файл /bitrix/php_interface/init.php. Если этого файла нет, его нужно создать. Для более сложной структуры можно подключать внешние файлы через require_once.

Для проектов с высокой нагрузкой обработчики можно выносить в отдельные классы, соответствующие стандартам D7, но простые сценарии успешно работают и с функциями в init.php.

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

• Всегда проверяйте $WEB_FORM_ID, чтобы обработчик не влиял на другие формы.
• Изучите структуру $arrVALUES, предварительно выведя её через var_dump, чтобы точно знать имена полей.
• При внесении изменений в массивы убедитесь, что они соответствуют ожидаемым типам данных (например, form_date_... должен содержать дату в правильном формате).
• Для длительных операций (отправка писем, запросы к API) используйте асинхронные механизмы или ставьте задачу в очередь, чтобы не задерживать ответ пользователя.

Событие onBeforeResultAdd — один из ключевых инструментов для расширения функциональности веб-форм в Битрикс. Оно даёт полный контроль над данными до их сохранения и открывает широкие возможности для интеграции и кастомизации.