Где лежат контроллеры и роутеры
Все контроллеры и роутеры для вашего проекта нужно создавать в следующих директориях:
- Контроллеры: /local/bik.rest/controllers/
- Роутеры: /local/bik.rest/routers/
Создание контроллера
- Создать директорию /local/bik.rest/controllers/.
- Создать новый PHP-файл с именем, отражающим назначение вашего контроллера (например,
CustomController.php). - Откройте созданный файл и определите класс контроллера, который должен наследовать от
AbstractController. - Создайте свой первый контроллер, основываясь на приведенном ниже примере.
Пример контроллера
<?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 / DELETE | POST / 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 | собранный элемент (для каждого элемента ответа, вне кеша) |
OnAfterIblockElementSeo | SEO элемента и каждого предложения; args: ID, IBLOCK_ID, NAME, CODE, BASE_PRICE, IS_OFFER, PRODUCT_ID |
OnAfterIblockSectionSeo | SEO раздела; 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 (или в файле, подключаемом из него):
\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-запросов на ваши контроллеры.
Создание роутера
- Перейдите в папку
/local/bik.rest/routers/. - Создайте новый PHP-файл для роутера (например,
CustomRouter.php). - Определите класс роутера, который должен наследовать от
AbstractRouter. - Создайте роутер, основываясь на приведенном ниже примере.
Пример роутера
<?php
namespace BIK\Rest\Routers;
class CustomRouter extends AbstractRouter
{
public static $name = 'Custom'; # Название роутера в Swagger
public static $description = 'Описание'; # Описание роутера в Swagger
public function run()
{
}
}