HLEB v1 : PHP Микрофреймворк | Официальная инструкция Api

Создание API

Для реализации API на фреймворке HLEB предусмотрен набор трейтов, упрощающих валидацию и обработку данных в контроллерах (там, где эти трейты применены).

Установка библиотеки github.com/phphleb/api-multitool через Composer:
$ composer require phphleb/api-multitool
или скачать библиотеку в папку vendor/phphleb/api-multitool.

Подключение трейта BaseApiTrait (представляющего собой набор трейтов)

Сначала нужно создать родительский класс BaseApiActions для контроллеров с API:

<?php // Файл /app/Controllers/Api/BaseApiActions.php namespace App\Controllers\Api; use Phphleb\ApiMultitool\BaseApiTrait; class BaseApiActions extends \MainController { /* Подключение набора трейтов для API */ use BaseApiTrait; function __construct(array $data = null) { parent::__construct($data);
/* Передача в конструктор API значения режима отладки. */ $this->setApiBoxDebug(HLEB_PROJECT_DEBUG); } }

Bсе вспомогательные трейты собраны в трейте BaseApiTrait как набор. Поэтому достаточно подключить его к контроллеру и получить полную реализацию. Если необходим другой набор из этих трейтов, то нужно или использовать их группой или соединить в собственный набор.
После этого во всех наследуемых от этого класса контроллерах появятся методы от каждого трейта в наборе:

ApiHandlersTrait

Трейт ApiHandlersTrait содержит несколько методов, которые могут пригодиться для обработки возвращаемых данных API. Это не значит, что его методы 'present' и 'error' формируют окончательный ответ, они возвращают именованные массивы, которые можно использовать по собственному более сложному стандарту. Пример в методе контроллера:

<?php // Файл /app/Controllers/Api/UserController.php namespace App\Controllers\Api; use App\Models\UserModel; use Hleb\Constructor\Handlers\Request; class UserController extends BaseApiActions { public function actionGetOne() { $id = Request::getInt('id'); if (!$id) { return $this->error('Invalid request data: id', 400); } $data = UserModel::getOne($id); return array_merge( $this->present($data ?: []), ['error_cells' => $this->getErrorCells()] ); } }

Во фреймворке HLEB при возвращении массива из контроллера он автоматически преобразуется в JSON. При выводе отформатированного массива к нему добавлено значение 'error_cells' с перечнем полей, в которых произошли ошибки (при наличии таковых).

ApiMethodWrapperTrait

Осуществляет перехват системных ошибок и вывод их в метод 'error' предыдущего трейта ApiHandlersTrait или иного, предназначенного для этой цели (если упомянутый трейт не используется). Если вызван метод контроллера, то для правильной обработки его ошибок необходимо добавить префикс 'action', как, например, для предыдущего примера контроллера роутинг будет примерно таким:

Route::get('/api/users/{id}')->controller('Api\UserController@getOne');

Здесь нужно заметить, что в оригинале вызов идёт к методу 'getOne' контроллера, а в самом контроллере метод 'actionGetOne'.

ApiPageManagerTrait

Реализует довольно частно необходимую функцию пагинации выводимых данных. Добавляет метод 'getPageInterval', который преобразует данные пагинации в более удобный вид. При этом вычисляется начальное значение выборки, что удобно для работы с базой данных.

ApiRequestDataManagerTrait

Добавляет метод 'check', при помощи которого можно проверить данные одного массива при помощи условий проверки из другого. Использование этого трейта добавляет возможность проверить любые входящие данные, преобразованные в массив, будь это параметры POST-запроса или JSON Body. Существует перечень возможных условий, при помощи которых можно проверить данные, они составляются разработчиком. Например (Request::getJsonBodyList для фреймворка HLEB возвращает массив JSON Body):

$data = Request::getJsonBodyList() ?: []; $result = $this->check($data, // $result - булево значение, показывающее прошли проверки успешно или нет. [ 'id' => 'required|type:int|min:1', // Обязательное поле, тип integer, минимальное значение 1. 'email' => 'required|type:string', // Обязательное поле, тип string. 'name' => 'type:string,null', // Необязательное поле, но будет проверен тип string или NULL, если найдено. 'password' => 'required|type:string|minlength:6' // Обязательное поле, тип string, минимальное кол-во символов 6. ]); $errorCells = $this->getErrorCells(); // Массив со списком полей не прошедших проверку. $errorMessage = $this->getErrorMessage(); // Массив с сообщениями о произошедших ошибках валидации.

required - обязательное поле, располагается строго в начале.

Список возможных типов ('type' - обязательно на первом месте или после required):
string - проверяет наличие строкового значения, ограничения могут быть minlength и maxlength.
float - проверка на тип float(double), ограничения могут быть max и min.
int - проверка на тип int(integer), ограничения могут быть max и min.
regex - проверка по регулярному выражению, например 'regex:[0-9]+'.
fullregex - проверка по полному регулярному выражению, аналогично 'fullregex:/^[0-9]+$/i', обязательно обрамлённое слешами, может содержать символы : и |, в отличие от более простого regex.
bool - проверка на булево значение, только true или false.
null - проверка на null как правильное значение.
void - проверка на пустую строку как правильное значение.

Тип для перечислений:
enum - поиск среди возможных значений, например 'enum:1,2,3,4,south,east,north,west'. Проверка на равенство не строгая, поэтому правильно будет как 4, так и '4', для точного соответствия лучше сопроводить проверкой на тип.

Можно добавить два и более типов, они будут проверены на все общие условия включительно, например type:string,null,void|minlen:5 - будет означать, что проверяется строка, минимум 5 символов или пустая, или же значение null, во всех остальных случаях возвращает false как результат не пройденной проверки валидации.

Также можно проверить массив в поле со списком стандартных полей массива (будут проверяться по единому шаблону):

$result = $this->check($data, [ 'users' => ['id' => 'required|type:int', 'name' => 'required|type:string'], // Необязательное поле, массив с перечислением (в каждом проверяется два поля). 'images' => ['required', ['id' => 'required|type:int', 'width' => 'required|type:int', 'height' => 'required|type:int']] // Обязательное поле, массив с перечислением (в каждом проверяется три поля). ]);

Для проверки значений вложенных массивов в проверочном массиве название указывается в квадратных скобках.

$result = $this->check( [ ['name1' => ['name2' => ['name3' => 'text']]], // Данные ['[name1][name2][name3]' => 'required|type:string'] // Массив с условиями ]);

Приведённое выше условие вернёт успешную проверку с учётом вложенности.

Тестирование

Трейты API проверены при помощи github.com/phphleb/api-tests