Query — построение и выполнение запросов¶
SMF\API\Query — небольшой fluent-построитель. FROM/WHERE пишется один раз и переиспользуется всеми режимами выборки; LIMIT, COUNT и пагинация достраиваются автоматически.
Сборка запроса¶
->from()(с JOIN'ами)->where()->columns()(по умолчанию*)->orderBy()->params()(плейсхолдеры{int:...},{query_see_board}и т.п.)
Сам построитель тоже умеет выполнять запрос: first(), exists(), fetchAll() и fetchPage($limit, $offset) — последний возвращает строки страницы вместе с общим числом строк.
Запуск через хелперы контроллера¶
$this->paginate($query)— коллекция с мета-пагинацией; каждая строка идёт черезtransform().$this->first($query)— одна строка илиnull(дляshowи проверок).$this->exists($query)—bool(для валидации вstore).$this->fetchAll($query)— все строки без пагинации (сырые массивы).
Что доступно в контроллере¶
$this->request— объектRequest. К нему обращаются через аксессоры, а не через публичные свойства:getMethod(),getSegments(),segment($index),header($name),query($name),input($name)иall()(всё разобранное тело).$this->response()— новыйResponse(->data(),->collection(),->status(),->header(),->error()).$this->paginate($query)/$this->first($query)/$this->exists($query)/$this->fetchAll($query)— запускQuery.$this->transform($row)— форма строки для вывода; переопределяйте под свой ресурс (по умолчанию возвращает строку как есть).$this->id($params)— целочисленный{id}с проверкой; вторым аргументом читается другой параметр пути, например$this->id($params, 'parent_id').$this->pagination()—[limit, offset]с разумными границами (limit1–100, по умолчанию 25;offsetпо умолчанию 0).$this->cleanString($value)— безопасная строка из тела запроса.$this->writableColumns($schema, $full, $aliases)— сбор изменяемых полей из тела: при$full = true(PUT) требует все поля из$schema, не помеченныеoptional, приfalse(PATCH) оставляет только присланные (пустой PATCH → 400).$this->boolean($value)— приведение значения тела кbool(принимаетtrue/false,1/0,"yes"/"no","on"/"off").$this->noContent()— пустой ответ204для успешных операций без тела (обычноDELETE).- личность и права — из глобального
$user_info(его настраиваетAuthenticator), проверки — штатнымallowedTo()/$user_info['is_admin'].
Схема изменяемых полей¶
writableColumns() сопоставляет тело запроса с колонками SMF через схему — имя поля => описание. Ниже схема встроенного ресурса categories, её можно сравнить с CategoryController:
<?php declare(strict_types=1);
private const WRITABLE = [
'name' => ['type' => 'string', 'column' => 'name', 'length' => 255],
'description' => ['type' => 'raw', 'column' => 'description'],
'order' => ['type' => 'int', 'column' => 'cat_order', 'optional' => true],
'can_collapse' => ['type' => 'bool', 'column' => 'can_collapse', 'optional' => true],
];
| Ключ | Значение |
|---|---|
type |
string, raw, int, float, bool, email, date или int_list |
column |
Колонка SMF, в которую пишем; по умолчанию совпадает с именем поля |
min, max |
Границы для целочисленных полей; нижняя граница по умолчанию 0, отрицательная нижняя граница разрешает отрицательные значения |
clamp |
Прижимает значение к границе вместо отказа (SMF трактует min_posts = -1 как «не по пост-критерию») |
length |
Максимальная длина в символах для полей string и raw |
optional |
Поле принимается, но не обязательно при полной замене |
Поведение типов:
string— обрезается и экранируется черезhtmlspecialchars();raw— обрезается, но сохраняется как есть (тексты сообщений, подписи, описания);int— целое число в заданных границах; дробные значения, ведущие нули (01) и значения с посторонними символами отклоняются;float— число, округлённое до двух знаков (SMF хранит смещения времени как float);bool—true,1,"yes"и"on"считаются истиной, всё остальное ложью;email— проверяется как адрес электронной почты;date—YYYY-MM-DD; пустое значение превращается в служебную дату SMF «не задано»1004-01-01;int_list— список id, заданный как"2,7"или[2, 7], хранится как"2,7".
Третий аргумент writableColumns() — список псевдонимов: имена колонок SMF, которые клиент может использовать вместо имён полей, например ['id_cat' => 'category']. Псевдоним используется, только если само поле не прислано.
Запись — через штатные функции SMF
Для изменяющих действий (PUT / PATCH / DELETE) выполняйте запись через штатные функции SMF (modifyBoard, deleteMembers, modifyPost и т.п.) — Query предназначен только для чтения. Права проверяйте сами через allowedTo() до вызова этих функций и бросайте ApiException: многие функции ядра при отказе завершают запрос фатальной HTML-ошибкой, а не JSON.
Пример: форма transform¶
Переопределите transform(), чтобы задать внешний вид ресурса — paginate() вызывает его для каждой строки:
<?php declare(strict_types=1);
protected function transform(array $row): array
{
return [
'id' => (int) $row['id_widget'],
'name' => $row['name'],
];
}
См. также Добавление ресурса с полным примером контроллера.