ave-cms/help/database/placeholders.md

Плейсхолдеры запросов

← Назад к разделу БД

Значения в запрос подставляются только через плейсхолдеры — так QueryBuilder сам экранирует данные и защищает от SQL-инъекций. Значения передаются позиционными аргументами (вариадик), в порядке следования плейсхолдеров.

DB::query('SELECT * FROM users WHERE id = %i AND status = %s', 10, 'active');

---

Скалярные

Плейсхолдер	Значение	Пример подстановки
%s	Экранированная строка (точное сравнение)	... = 'active'
%i	Целое число	... = 10
%d	Дробное число	... = 12.50
%b	Имя таблицы/поля (в обратных кавычках)	`documents`
%t	Timestamp → 'Y-m-d H:i:s'	'2026-07-14 12:30:00'
%l	Сырое значение без экранирования	как есть — осторожно

DB::query('SELECT * FROM p WHERE title = %s', 'Кресло');   // точное совпадение
DB::query('SELECT * FROM p WHERE price >= %d', 1000.0);
DB::query('SELECT * FROM %b WHERE id = %i', 'products', 5); // %b — имя таблицы

---

LIKE-строки

Плейсхолдер	Оборачивает	Для
%ss	%value%	поиск по вхождению
%ssb	value%	начинается с
%sse	%value	заканчивается на

DB::query('SELECT * FROM p WHERE title LIKE %ss', $q);   // '%кресло%'
DB::query('SELECT * FROM p WHERE alias LIKE %ssb', 'ek'); // 'ek%'

⚠️ Частая ошибка: %s — это точное сравнение (= 'x'), а %ss — оборачивает в %...% для LIKE. Перепутаете — =-запрос ничего не найдёт.

---

Массивы (для IN (...) и не только)

Плейсхолдер	Значение
%ls	Массив строк (экранированных)
%li	Массив целых чисел
%ld	Массив дробных
%lb	Массив имён таблиц/полей
%ll	Массив сырых значений
%lt	Массив timestamps

DB::query('SELECT * FROM p WHERE id IN (%li)', array(1, 2, 3));        // IN (1,2,3)
DB::query('SELECT * FROM p WHERE alias IN (%ls)', array('a', 'b'));    // IN ('a','b')

---

Hash (ключ → значение)

Плейсхолдер	Склейка	Для
%hc	k=v, k=v через запятую	SET в UPDATE
%ha	k=v AND k=v	условия по AND
%ho	k=v OR k=v	условия по OR

DB::query('UPDATE p SET %hc WHERE id = %i', array('title' => 'X', 'qty' => 5), 42);
DB::query('SELECT * FROM p WHERE %ha', array('rubric_id' => 5, 'active' => 1));
// ... WHERE `rubric_id`=5 AND `active`=1

На практике %hc руками писать не нужно — его использует DB::Update().

---

Санитизированные (basic-режим)

Плейсхолдер	Значение
%?	Одно значение (автоопределение типа)
%l?	Список значений
%ll?	Список списков (пакетная вставка)

Их применяют CRUD-хелперы (Insert, insertOrReplace) под капотом.

---

Передача массива аргументов

Если SQL и аргументы собраны в массив — разворачивайте через call_user_func_array:

$args = array_merge(array($sql), $bindings);
$rows = call_user_func_array(array('DB', 'query'), $args)->getAll();

---

Проверка результата подстановки

Чтобы увидеть, во что развернётся запрос (без выполнения):

echo DB::debugQuery('SELECT * FROM p WHERE id = %i AND t LIKE %ss', 5, 'кресло');
// SELECT * FROM p WHERE id = 5 AND t LIKE '%кресло%'