Как выполнить код после отдачи страницы в Bitrix24

В Bitrix24 можно выполнять код уже после того, как страница отдана пользователю. Это особенно полезно, если нужно запустить какую-то логику, которая не критична для ответа, но должна выполниться: логирование, уведомления, работа с API и т.д.

Что делает `addBackgroundJob`

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

Когда выполняется `addBackgroundJob`?

Задачи, добавленные через addBackgroundJob, выполняются при вызове метода CMain::FinalActions(). Это завершающая фаза выполнения текущего запроса, когда основная логика уже завершена, и контент отдан браузеру. При этом задача не блокирует процесс, и пользователь не ждёт её завершения.

\Bitrix\Main\Application::getInstance()->addBackgroundJob(
    function () {
        // код, который выполнится после отдачи страницы
    }
);

Сигнатура метода

addBackgroundJob(callable $job, array $args = [], int $priority = JOB_PRIORITY_NORMAL);

Аргументы:

$job — функция, метод или замыкание, которое нужно вызвать.
$args — массив аргументов для $job.
$priority — приоритет выполнения:

const JOB_PRIORITY_NORMAL = 100;
const JOB_PRIORITY_LOW = 50;

Примеры использования

1. Вызов агента

\Bitrix\Main\Application::getInstance()->addBackgroundJob(
    ['CAgent', 'CheckAgents'],
    [],
    \Bitrix\Main\Application::JOB_PRIORITY_LOW
);

2. Запись в журнал событий (`CEventLog`)

\Bitrix\Main\Application::getInstance()->addBackgroundJob(
    function () {
        \CEventLog::Add([
            "SEVERITY" => "INFO",
            "AUDIT_TYPE_ID" => "CUSTOM_EVENT",
            "MODULE_ID" => "main",
            "ITEM_ID" => "background_job",
            "DESCRIPTION" => "Фоновая задача выполнена после отдачи страницы"
        ]);
    }
);

3. Отдача файла + Push-сообщение пользователю

Допустим, вы генерируете документ и сразу отдаёте пользователю на скачивание. После этого в фоне отправляете push-сообщение — пользователь получит alert с подтверждением.

use Bitrix\Main\Application;
use Bitrix\Main\Engine\Response\File;
use Bitrix\Main\Loader;

$filePath = $_SERVER['DOCUMENT_ROOT'] . '/upload/generated.docx';

Application::getInstance()->addBackgroundJob(
    function ($userId) {
        if (\Bitrix\Main\Loader::includeModule('pull')) {
            \CPullStack::AddByUser($userId, [
                'module_id' => 'main',
                'command' => 'custom_action_complete',
                'params' => [
                    'message' => 'Действие выполнено'
                ]
            ]);
        }
    },
    [$USER->GetID()]
);

$response = new File($filePath);
$response->setFileName("Документ.docx");
$response->send();

А на фронте — ловим сообщение:

BX.addCustomEvent("onPullEvent-main", function(command, params) {
    if (command === "custom_action_complete") {
        alert(params.message);
    }
});

Что важно знать

Работает только при включённой буферизации вывода (в ядре Bitrix включена по умолчанию).
Это не асинхронность в привычном смысле — код всё ещё исполняется в рамках текущего PHP-процесса, но выполняется позже, после отдачи страницы.
В CLI-скриптах метод не имеет смысла — контент там не отдают.

Где это полезно

Логирование событий, ошибок, действий;
Вызовы внешних API, если не критична мгновенная реакция;
Обновление счётчиков, метрик, кэшей;
Отправка сообщений через Push & Pull;
Запуск периодических задач без ручного вызова агента.

Заключение

addBackgroundJob — простой способ выполнить дополнительный код после ответа пользователю, не замедляя отдачу страницы. Этот механизм активируется в момент вызова CMain::FinalActions(), что даёт вам гибкость при организации фоновых задач.

Инструмент встроенный, не требует сторонних библиотек и работает из коробки. Если ещё не использовали — самое время попробовать.

Что делает addBackgroundJob

Когда выполняется addBackgroundJob?