ave-cms/help/en/database/placeholders.md

Request placeholders

← Back to DB section

Values are inserted into the request only through placeholders - like QueryBuilder It screens data itself and protects against SQL injections. Values are passed positional arguments (variadic), in the order of placeholders.

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

---

Scalar

Placeholder	Meaning	Substitution example
%s	Escaped string (exact comparison)	... = 'active'
%i	Integer	... = 10
%d	Fractional number	... = 12.50
%b	Table/field name (in back quotes)	`documents`
%t	Timestamp → 'Y-m-d H:i:s'	'2026-07-14 12:30:00'
%l	Raw value without escaping	as is - caution

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 lines

Placeholder	Wraps	For
%ss	%value%	search by occurrence
%ssb	value%	begins with
%sse	%value	ends with

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

⚠️ Common mistake: %s is an exact comparison (= 'x'), and %ss is wraps in %...% for LIKE. If you mix it up, the = query will not find anything.

---

Arrays (for IN (...) and more)

Placeholder	Meaning
%ls	Array of strings (escaped)
%li	Array of integers
%ld	Array of fractions
%lb	Array of table/field names
%ll	Array of raw values ​​
%lt	timestamps array

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 (key → value)

Placeholder	Gluing	For
%hc	k=v, k=v separated by commas	SET in UPDATE
%ha	k=v AND k=v	conditions by AND
%ho	k=v OR k=v	OR conditions

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

In practice, there is no need to write %hc by hand - it is used by DB::Update().

---

Sanitized (basic mode)

Placeholder	Meaning
%?	Single value (type autodetection)
%l?	List of values ​​
%ll?	List of lists (batch insert)

They are used by CRUD helpers (Insert, insertOrReplace) under the hood.

---

Passing an array of arguments

If the SQL and arguments are collected in an array, expand via call_user_func_array:

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

---

Checking the result of substitution

To see what the request will turn into (without execution):

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