ave-cms/help/database/README.md

Работа с базой данных

Движок работает с MySQL/MariaDB через тонкий фасад DB (обёртка над mysqli). Класс — App\Common\Db\DB, но везде используется короткий глобальный алиас DB. Результат запроса возвращается объектом DB_Result.

$doc = DB::query('SELECT * FROM ' . $t . ' WHERE Id = %i', 42)->getAssoc();

Карта раздела

Страница	О чём
Имена таблиц (резолверы)	Как правильно получать имя таблицы (ContentTables, SystemTables, …) вместо хардкода.
Плейсхолдеры	Полный разбор %i %s %ss %li %hc … с примерами каждого.
Запросы	DB::query() и варианты (queryAssoc, queryOneColumn …), отладка.
Чтение результата (DB_Result)	getAll / getAssoc / getValue / getOne …, семантика и подводные камни.
CRUD-хелперы	Insert / Update / Delete / Replace / insertUpdate, insertId, affectedRows.
Транзакции	startTransaction / commit / rollback.
Кеш запросов	setTtl / setCache / setTags / clearTags.
Безопасность и экранирование	Защита от инъекций, escape / quote / safe.

---

Подключение

Соединение поднимается один раз в system/bootstrap.php (DB::getInstance($config)), поэтому в контроллерах/моделях ничего инициализировать не нужно — сразу DB::query(...).

DB::connection('default');   // именованное соединение
DB::setPrefix('marketplace'); // префикс (обычно из настроек)
DB::mysqli();                 // «сырой» mysqli при необходимости
DB::version();                // версия сервера
DB::getDatabase();            // имя текущей БД

---

Быстрый старт

use App\Content\ContentTables;
$t = ContentTables::table('documents');   // например, 'ave_documents'

// список (массив ассоц. строк; на пустой выборке — false)
$items = DB::query('SELECT * FROM ' . $t . ' WHERE rubric_id = %i ORDER BY Id DESC', 5)->getAll() ?: array();

// одна строка
$doc = DB::query('SELECT * FROM ' . $t . ' WHERE Id = %i', 42)->getAssoc();

// один скаляр
$count = (int) DB::query('SELECT COUNT(*) FROM ' . $t)->getValue();

// вставка
DB::Insert($t, array('document_title' => 'Тест', 'rubric_id' => 5));
$id = (int) DB::insertId();

// обновление / удаление
DB::Update($t, array('document_title' => 'Новый'), 'Id = %i', $id);
DB::Delete($t, 'Id = %i', $id);

---

Три правила

1. Имя таблицы — через резолвер (ContentTables::table('documents')), не строкой. → tables.md
2. Значения — только через плейсхолдеры (%i, %s, …), никогда не склеивать пользовательский ввод в SQL. → placeholders.md, security.md
3. getAll() на пустой выборке возвращает false, а не [] — пишите ?: array(). → results.md