Расширение модуля тема 25 из 27

Контроллер: свой метод API

В данном руководстве будет описано, как создать собственный контроллер и соответствующий роутер. Это позволит вам расширить функциональность вашего проекта и интегрировать бизнес-логику в REST API.

в этой теме 6
  1. Где лежат контроллеры и роутеры
  2. Создание контроллера
  3. Пример контроллера
  4. Откуда метод получает аргументы
  5. События «до / после»
  6. Роутер

Где лежат контроллеры и роутеры

Все контроллеры и роутеры для вашего проекта нужно создавать в следующих директориях:

  • Контроллеры: /local/bik.rest/controllers/
  • Роутеры: /local/bik.rest/routers/

Создание контроллера

  1. Создать директорию /local/bik.rest/controllers/.
  2. Создать новый PHP-файл с именем, отражающим назначение вашего контроллера (например, CustomController.php).
  3. Откройте созданный файл и определите класс контроллера, который должен наследовать от AbstractController.
  4. Создайте свой первый контроллер, основываясь на приведенном ниже примере.

Пример контроллера

php
<?php

namespace BIK\Rest\Controllers;

use BIK\Rest\ORM\Resource\BasketResource;
use BIK\Rest\ORM\Resource\OrderResource;
use Bitrix\Main\Loader;
use Bitrix\Sale\Order;
use Bitrix\Main\ORM\Query\Query;
use Bitrix\Sale\Internals\OrderTable;
use Bitrix\Sale\Internals\BasketTable;
use Bitrix\Sale\Internals\OrderPropsValueTable;
use Bitrix\Sale\Delivery\Services\Manager;
use Bitrix\Iblock\ElementTable;

class CustomController extends AbstractController
{

    /*
     * Описание эндпоинтов для Swagger
     *
     * Данный метод может быть переопределён из класса AbstractController при необходимости
     */
    protected static function methodDocMap (): array
    {
        return [
            'post_cancel_order' => [
                'summary' => 'Отмена заказа',
                'description' => 'Отмена заказа по ID для текущего пользователя',
            ],
            'get_order' => [
                'summary' => 'Получение заказа',
                'description' => 'Получение заказа по ID для текущего пользователя'
            ],
        ];

    }

    /*
     * Описание параметров конкретного эндпоинта для Swagger
     *
     * Данный метод может быть переопределён из класса AbstractController при необходимости
     */
    protected static function parametersDocMap ()
    {
        $return = parent::parametersDocMap();

        // Тип, обязательность и место параметра (путь, строка запроса, тело) Swagger берёт из сигнатуры метода,
        // здесь - только описание и примеры
        $return['post_cancel_order'] = [
            'orderID' => [
                'description' => 'ID заказа',
            ]
        ];

        // Схема и пример всего тела для метода со служебным аргументом $requestBody
        $return['put_example_id'] = [
            'requestBody' => [
                'description' => 'Новые данные',
                'example' => ['name' => 'Дом', 'comment' => 'Домофон 123'],
            ]
        ];

        return $return;
    }

    /*
     * Пример эндпоинта для POST запроса
     * В этом случае запрос должен осуществляться по адресу {домен}/api/custom/cancel/order
     *
     * $this->responseData используется, чтобы указать ответ от эндпоинта, необязательный
     * $this->responseCode используется, чтобы указать HTTP код ответа, по умолчанию - 200, необязательный
     */
    public function post_cancel_order($orderID)
    {
        Loader::includeModule("sale");

        global $USER;

        $order = Order::load($orderID);

        if ($order->getUserId() == $USER->getId()) {
            $oldOrderObject = new \CSaleOrder();
            $oldOrderObject->CancelOrder($order->getId(), "Y", 'Отменено пользователем');
            $order->setField("STATUS_ID","C");
            $result = $order->save();

            if($result->isSuccess()) {
                $this->responseData['success'] = 'Заказ успешно отменен';
            } else {
                $this->responseData['error'] = 'При отмене произошла ошибка';
                $this->responseCode = 400;
            }
        } else {
            $this->responseData['error'] = 'Это заказ не текущего пользователя';
            $this->responseCode = 400;
        }
    }

    /*
     * Пример эндпоинта для DELETE запроса
     * В этом случае запрос должен осуществляться по адресу {домен}/api/custom/example
     */
    public function delete_example()
    {
        $this->responseData['data'] = 'DELETE request';
    }

    /*
     * Пример эндпоинта для PUT запроса с параметром пути и телом целиком
     * В этом случае запрос должен осуществляться по адресу {домен}/api/custom/example/{id}
     * $id - из пути, $requestBody - всё тело запроса (JSON или поля формы) массивом
     */
    public function put_example_id(int $id, array $requestBody)
    {
        $this->responseData['data'] = ['id' => $id, 'body' => $requestBody];
    }

    /*
     * Пример эндпоинта для GET запроса
     * В этом случае запрос должен осуществляться по адресу {домен}/api/custom/order
     */
    public function get_order($orderID)
    {
        Loader::includeModule("sale");

        global $USER;

        if ($USER->IsAuthorized()) {
            $order = Order::load($orderID);

            if ($order)
                $this->responseData['data'] = [
                    'id' => $order->getId(),
                    'price' => $order->getPrice(),
                    'paid_sum' => $order->getSumPaid(),
                    'is_paid' => $order->isPaid()
                ];
            else
                $this->responseData['error'] = 'Заказ не найден';
        }
    }
}

Откуда метод получает аргументы

Роутер раскладывает аргументы метода по одному правилу:

АргументGET / DELETEPOST / PUT
совпадает с сегментом пути (put_example_id($id, ...) → {id})из путииз пути
служебный $requestBody—всё тело запроса массивом
остальные именованныеиз строки запросаиз полей тела запроса
  • Тело запроса — JSON (Content-Type: application/json) или поля формы (x-www-form-urlencoded, multipart/form-data). Файлы — в $_FILES.
  • Значения приводятся к типу аргумента: int, float, string, bool (только Y / N, строго заглавными: параметр не передан — значение по умолчанию, любое другое значение, в том числе true, 1, y, — 400 «Параметр <имя>: ожидается Y или N»), array (строка JSON декодируется).
  • Параметры пути могут стоять в любом месте сигнатуры, их может быть несколько.
  • Читать $_POST, $_GET и php://input в методах не нужно. Если штатному компоненту Битрикса нужен свой формат $_POST, его собирает отдельный адаптер (пример — SaleController::runOrderComponent()).
  • В Swagger тело запроса описывается автоматически по аргументам метода, по умолчанию — в JSON.
  • Таблица роутов кешируется: после добавления или переименования метода сбросьте кеш.

События «до / после»

У каждого метода два события: OnBefore<Роутер><Метод> и OnAfter<Роутер><Метод> (SaleController::get_basket — OnBeforeSaleGetBasket / OnAfterSaleGetBasket), плюс общая пара OnBeforeApiRequest / OnAfterApiRequest. Обработчик получает объект BIK\Rest\Events\ApiEvent: в «до» — параметры (getParams(), setParam()), stop($текст, $код) и respond($данные); в «после» — ответ (getResponse(), setResponse()). Имя события метода вычисляется по имени метода при сборке маршрута, явное имя — methodDocMap()[метод]['event']. Полный перечень — ApiEvents::catalog().

События внутри сборки ответа получают BIK\Rest\Events\ApiBuildEvent (getItem() / setItem()):

СобытиеЧто правит обработчик
OnAfterIblockElementBuildсобранный элемент (для каждого элемента ответа, вне кеша)
OnAfterIblockElementSeoSEO элемента и каждого предложения; args: ID, IBLOCK_ID, NAME, CODE, BASE_PRICE, IS_OFFER, PRODUCT_ID
OnAfterIblockSectionSeoSEO раздела; args: ID, IBLOCK_ID, NAME, CODE
OnBeforeIblockOffersBuildрежим предложений (full, lite, min, selected, none); args: productId
OnAfterSaleOrderBuildответ заказа (context — order: ответ post_order_refresh, sale: данные GET /api/sale)
OnBeforeSaleBonusWithdraw / OnAfterSaleBonusWithdrawсумма списания бонусов; args: order

Регистрация в /local/php_interface/init.php (или в файле, подключаемом из него):

php
\Bitrix\Main\EventManager::getInstance()->addEventHandler('bik.rest', 'OnAfterSaleOrderBuild', function (\BIK\Rest\Events\ApiBuildEvent $event) {
    $item = $event->getItem();
    $item['LOCATION']['IS_CAPITAL'] = ($item['LOCATION']['CITY']['ID'] ?? null) == 1;
    $event->setItem($item);
});

\Bitrix\Main\EventManager::getInstance()->addEventHandler('bik.rest', 'OnAfterIblockElementSeo', function (\BIK\Rest\Events\ApiBuildEvent $event) {
    $seo = $event->getItem();
    $seo['title'] = $event->getArg('NAME') . ($event->getArg('IS_OFFER') ? ' (вариант)' : '') . ' - купить';
    $event->setItem($seo);
});

Ошибка, которую обработчик возвращает намеренно (stop(), исключение с кодом 4xx), уходит клиенту как есть; прочие исключения дают «Внутренняя ошибка» и запись в журнал.

Роутер

Каждый контроллер должен иметь свой роутер. Это необходимо для корректной маршрутизации HTTP-запросов на ваши контроллеры.

Создание роутера

  1. Перейдите в папку /local/bik.rest/routers/.
  2. Создайте новый PHP-файл для роутера (например, CustomRouter.php).
  3. Определите класс роутера, который должен наследовать от AbstractRouter.
  4. Создайте роутер, основываясь на приведенном ниже примере.

Пример роутера

php
<?php

namespace BIK\Rest\Routers;

class CustomRouter extends AbstractRouter
{
    public static $name = 'Custom';             # Название роутера в Swagger
    public static $description = 'Описание';    # Описание роутера в Swagger

    public function run()
    {

    }
}

Подключим BIK.REST-API к вашему сайту

Оставьте заявку — установим и настроим модуль, ответим на вопросы по API.

c заботой о вас, мы используем cookie на своем сайте, чтобы интернет был чистым и прекрасным