Розробка AJAX-контролерів 1С-Бітрікс

Розробка AJAX-контролерів 1С-Бітрікс

Компонент Бітрікс виводить список товарів з кнопкою «Показати ще». При кліку сторінка перезавантажується повністю — або розробник прикрутив jQuery-запит на /ajax.php?action=load_more, який приймає POST-дані та повертає HTML з буфера компонента. Це робочий, але архаїчний підхід. Бітрікс D7 надає контролери — \Bitrix\Main\Engine\Controller — які дають структурований спосіб створення AJAX-ендпоінтів з авторизацією, CSRF-захистом та стандартним форматом відповіді.

Чим контролер D7 кращий за саморобний ajax.php

Саморобний ajax.php — концентрація ризиків: немає централізованої CSRF-перевірки, немає стандартної обробки помилок, немає автоматичної авторизації, код розкиданий по файлах. Контролер D7 вирішує все це з коробки:

namespace MyVendor\Catalog\Controller;

use Bitrix\Main\Engine\Controller;
use Bitrix\Main\Engine\ActionFilter;

class Product extends Controller
{
    public function configureActions(): array
    {
        return [
            'getList' => [
                'prefilters' => [
                    new ActionFilter\Authentication(),   // перевірка авторизації
                    new ActionFilter\Csrf(),             // CSRF-токен
                ],
            ],
        ];
    }

    public function getListAction(int $sectionId, int $page = 1): array
    {
        // Повертаємо масив — Бітрікс сам обгорне в {"status":"success","data":{...}}
        return [
            'items' => $this->loadProducts($sectionId, $page),
            'total' => $this->countProducts($sectionId),
        ];
    }
}

Фреймворк автоматично обгортає значення, що повертається, в JSON-конверт {"status": "success", "data": {...}} або {"status": "error", "errors": [...]} при кинутому виключенні.

Реєстрація контролера

Контролер реєструється у файлі роутингу модуля routes.php:

// У .settings.php модуля або через метод Application::getInstance()->getRouter()
\Bitrix\Main\Routing\RoutingConfigurator::registerRoutes(function($routes) {
    $routes->post('/api/catalog/product/get-list/', 'MyVendor\Catalog\Controller\Product::getListAction');
});

Альтернативний спосіб — через стандартний механізм компонентів: контролер викликається через /bitrix/services/main/ajax.php?action=myvendor:catalog.product.getList.

Детально: фільтри та middleware

Контролер підтримує ланцюжок фільтрів до та після виконання дії. Це аналог middleware в Laravel.

Стандартні prefilters:

• ActionFilter\Authentication — вимагає авторизації
• ActionFilter\Csrf — перевіряє CSRF-токен (bitrix_sessid)
• ActionFilter\HttpMethod — обмежує методи (GET/POST)
• ActionFilter\Scope — обмежує контекст (тільки веб, тільки REST, тільки CLI)

Кастомний фільтр — наприклад, перевірка прав на конкретний ресурс:

class ResourceAccessFilter extends \Bitrix\Main\Engine\ActionFilter\Base
{
    public function onBeforeAction(Event $event): ?EventResult
    {
        $action = $event->getParameter('action');
        $sectionId = $action->getController()->getRequest()->getPost('sectionId');

        if (!SectionAccessChecker::canRead((int)$sectionId)) {
            $this->addError(new \Bitrix\Main\Error('Access denied', 403));
            return new EventResult(EventResult::ERROR, null, null, $this);
        }
        return null;
    }
}

Обробка файлів та складних даних

Контролер автоматично десеріалізує вхідні дані. Для завантаження файлів — через $this->getRequest()->getFile('image'), результат — об'єкт \Bitrix\Main\Web\Upload\UploadedFile з методами валідації типу та розміру.

Для пагінації використовується вбудований об'єкт \Bitrix\Main\Engine\Response\DataType\Page:

public function getListAction(int $page): \Bitrix\Main\Engine\Response\DataType\Page
{
    $pageSize = 20;
    $items = ProductTable::getList([
        'limit'  => $pageSize,
        'offset' => ($page - 1) * $pageSize,
    ])->fetchAll();

    return new \Bitrix\Main\Engine\Response\DataType\Page('items', $items, fn() => ProductTable::getCount());
}

Тестування контролерів

Контролери D7 можна тестувати через PHPUnit без HTTP-запиту: створюється екземпляр контролера, підміняється Request, викликається run(). Це великий плюс порівняно з саморобними ajax.php, які тестувати складно.

Терміни розробки

Якщо на проекті вже є саморобні ajax.php, їх варто мігрувати на контролери поступово, починаючи з найбільш навантажених або проблемних ендпоінтів.