CRUD операции IO7

Внимание

Данная статья документации написана нейросетью. Возможны некоторые расхождения и неточность информации!

IO7 предоставляет два уровня CRUD: статические методы SqlClass для прямого доступа к БД и ** CrudApi** для построения REST-like API.

IO\SqlClass — статические методы

search()

Поиск записей с фильтрами, сортировкой, пагинацией.

public static function search(array $params): array

Параметры ($params):

Ключ	Тип	Значение по умолчанию	Обязателен	Описание
`filter`	`array<string, mixed>`	`[]`	Нет	Фильтры WHERE
`out`	`string`	`'object'`	Нет	Формат вывода: `'object'` или `'array'`
`limit`	`int`	`1000`	Нет	Максимум записей
`start`	`int`	`0`	Нет	Смещение (OFFSET)
`order`	`array<string, string>`	`[]`	Нет	Сортировка `['field' => 'asc'\|'desc']`
`fields`	`string[]`	`[]`	Нет	Список полей для SELECT
`join`	`string\|string[]`	`[]`	Нет	JOIN выражения
`groupby`	`string[]`	`[]`	Нет	GROUP BY поля
`distinct`	`int`	`0`	Нет	DISTINCT (1 или 0)

Возвращает: array{error_str: string, error_code: int, res: array, count: int, time: int}

$result = \IO\Unit::search([
    'filter' => ['is_active' => 1],
    'out'    => 'array',
    'limit'  => 50,
    'order'  => ['pkid' => 'asc'],
]);

// $result['res']     — массив записей
// $result['count']   — общее количество
// $result['error_code'] — EIO_OK при успехе

findItem()

Поиск одной записи.

public static function findItem(array $params): ?array

$item = \IO\Unit::findItem([
    'filter' => ['pkid' => 42],
]);
// ['pkid' => 42, 'name' => '...', ...] или null

getByPkid()

Поиск по первичному ключу.

public static function getByPkid($pkids, string $out = 'object'): array

Параметры:

Параметр	Тип	Значение по умолчанию	Обязателен	Описание
`$pkids`	`int\|int[]`	—	Да	ID или массив ID
`$out`	`string`	`'object'`	Нет	`'object'` или `'array'`

$result = \IO\Unit::getByPkid(42);
$result = \IO\Unit::getByPkid([1, 2, 3], 'array');

updateByFilter()

Массовое обновление по фильтру.

public static function updateByFilter(array $filter, array $data): int

Возвращает: 1 при успехе, -1 при ошибке.

$ok = \IO\Unit::updateByFilter(
    ['pkid' => 5],
    ['is_deleted' => 1, 'gmtimeChange' => iogetdbtimeutc(time())]
);

tablename()

Возвращает имя таблицы.

public static function tablename(): string

$name = \IO\Unit::tablename(); // 'lib_units'

rules()

Разрешения для IO\Core::call().

public static function rules(): array

$perms = \IO\Unit::rules();
// ['static' => [], 'object' => []]

IO\Api\CrudApi — CRUD через API

CrudApi расширяет CoreApi и предоставляет готовые CRUD-действия.

struct()

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

public static function struct(): array

class UserApi extends \IO\Api\CrudApi
{
    public static function struct(): array
    {
        return [
            'class' => \IO\Classes\User::class,
            'fields' => [
                'pkid'    => ['type' => 'int'],
                'name'    => ['type' => 'string', 'label' => 'Имя'],
                'email'   => ['type' => 'string', 'label' => 'Email'],
                'is_deleted' => ['type' => 'int', 'virtual' => true],
            ],
            'primary' => ['pkid'],
        ];
    }
}

doSearch()

Поиск записей. Вызывается через IO\Core::callAction().

public function doSearch(ApiResult $result, array $params): ApiResult

$response = \IO\Core::callAction('app.model.user.search', [
    'filter' => ['status' => 'active'],
    'start'  => 0,
    'limit'  => 20,
]);
// $response['items']  — записи
// $response['total']  — общее количество

doGetByID()

Получение записи по ID.

public function doGetByID(ApiResult $result, array $params): ApiResult

$response = \IO\Core::callAction('app.model.user.getByID', ['pkid' => 42]);
// $response['item'] — найденная запись или null

doCreate()

Создание новой записи.

public function doCreate(ApiResult $result, array $params): ApiResult

$response = \IO\Core::callAction('app.model.user.create', [
    'item' => [
        'name'  => 'Иван',
        'email' => 'ivan@example.com',
    ],
]);
// $response['pkid'] — ID новой записи

doSave()

Обновление существующей записи.

public function doSave(ApiResult $result, array $params): ApiResult

$response = \IO\Core::callAction('app.model.user.save', [
    'pkid' => 42,
    'item' => [
        'name' => 'Иван Петров',
    ],
]);

doDelete()

Мягкое удаление (установка is_deleted = 1).

public function doDelete(ApiResult $result, array $params): ApiResult

$response = \IO\Core::callAction('app.model.user.delete', ['pkid' => 42]);

Хуки CrudApi

Метод	Описание
`onSearchFilter(array $filter): array`	Модификация фильтра перед запросом
`onSearchParams(array $params): array`	Модификация параметров поиска
`onUpdateData(array $save, array $update): array`	Модификация данных перед сохранением
`onUpdateItem(array $save, array $update): void`	Побочные эффекты после обновления

class UserApi extends \IO\Api\CrudApi
{
    public function onSearchFilter(array $filter): array
    {
        $filter['is_deleted'] = 0;
        return $filter;
    }

    public function onUpdateData(array $save_data, array $update_data): array
    {
        $update_data['modified_by'] = $this->user->id;
        return $update_data;
    }
}

Получение текущего элемента

Внутри методов doSave() и doCreate() доступны:

$this->item       // текущий объект модели (Eloquent)
$this->item_pkid  // ID текущего элемента

saveItem()

Сохранение данных в БД с учётом структуры полей.

public function saveItem(array $save_data): void

Метод автоматически:

Исключает виртуальные и readonly поля
Вызывает onUpdateData() для трансформации
Вызывает onUpdateItem() для побочных эффектов
Вызывает $item->save()

Фильтры API

CrudApi поддерживает операторы в ключах фильтра:

Оператор	Пример	Описание
(нет)	`status`	Равно (=)
`=`	`=status`	Равно (явно)
`!=`	`!=status`	Не равно
`>`	`age>25`	Больше
`<`	`age<50`	Меньше
`>=`	`age>=25`	Больше или равно
`<=`	`age<=50`	Меньше или равно
`%`	`%name`	Содержит (LIKE)
`$or`	`$or`	Логическое ИЛИ
`$and`	`$and`	Логическое И

$response = \IO\Core::callAction('app.model.user.search', [
    'filter' => [
        '!=status' => 'deleted',
        'age>25'   => null,
        '%name'    => 'Иван',
    ],
]);

См. также

soft_delete и doRestore

soft_delete флаг

В struct() можно указать soft_delete => true для мягкого удаления:

public static function struct(): array
{
    return [
        'class' => Role::class,
        'fields' => [...],
        'soft_delete' => true,   // is_deleted = 1 (мягкое удаление)
    ];
}

Значение	`doDelete()` поведение
`true`	Устанавливает `is_deleted = 1`, `gmtimeChange = now()`
`false` (по умолчанию)	`DELETE FROM table WHERE pkid = ?`

doRestore()

Восстановление мягко удалённой записи (только при soft_delete = true).

public function doRestore(ApiResult $result, array $params): ApiResult

$response = \IO\Core::callAction('app.model.user.restore', ['pkid' => 42]);

Условие	Результат
`soft_delete = true`	`UPDATE table SET is_deleted = 0 WHERE pkid = ?`
`soft_delete = false`	Возвращает ошибку "Restore not supported"

struct() — class обязателен

Поле class в struct() обязательно. Если не указано — выбрасывается RuntimeException.

// ✅ Правильно
public static function struct(): array
{
    return [
        'class' => Role::class,     // обязательно
        'fields' => [...],
        'primary' => ['pkid'],
        'soft_delete' => true,
    ];
}

// ❌ Ошибка — RuntimeException
public static function struct(): array
{
    return [
        'fields' => [...],
    ];
}

Ошибка:

RuntimeException: CrudApi: 'class' is required in struct().
Define it in your API class: struct()['class'] = YourModel::class

getSqlClass()

Внутренний метод, вызывается автоматически. Возвращает имя класса модели или выбрасывает RuntimeException.

protected static function getSqlClass(): string

Используется во всех CRUD-методах: doSearch, doGetByID, doCreate, doSave, doDelete, doRestore.