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

← [Назад к разделу БД](README.md)

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

```php
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` | Сырое значение **без экранирования** | как есть — **осторожно** |

```php
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` | заканчивается на |

```php
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 |

```php
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 |

```php
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()`](crud.md).

---

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

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

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

---

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

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

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

---

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

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

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