Создать SQL-выражение SqlExpression::__construct
Модуль: main — подключать отдельно не нужно
Конструктор SqlExpression::__construct создает выражение из шаблона SQL-фрагмента и значений для его плейсхолдеров. Конструктор только сохраняет аргументы. Метод compile подставляет значения в шаблон.
Сигнатура метода в классе Bitrix\Main\DB\SqlExpression:
public function __construct()
Конструктор читает аргументы через func_get_args(), поэтому в сигнатуре параметров нет.
Параметры
Обязательные параметры обозначены *
| Параметр | Тип | Описание |
|---|---|---|
| expression* | string |
Задает шаблон SQL-фрагмента с плейсхолдерами. Это первый аргумент конструктора |
| ...args | mixed |
Задают значения для плейсхолдеров. Каждое значение — отдельный аргумент, в порядке плейсхолдеров в шаблоне |
Типы в таблице описывают назначение аргументов. Сигнатура PHP не объявляет их.
Плейсхолдеры
Знак ? с необязательной буквой или символом после него отмечает место подстановки. Метод compile преобразует значение в зависимости от вида плейсхолдера.
| Плейсхолдер | Что подставляется |
|---|---|
? |
Для объекта Bitrix\Main\Type\DateTime или Bitrix\Main\Type\Date — дата в формате базы данных. Для другого значения — экранированная строка в одинарных кавычках |
?s |
Экранированная строка в одинарных кавычках. Объект Date или DateTime метод сначала приводит к строке в формате региональных настроек сайта |
?i |
Значение, приведенное к целому числу |
?f |
Значение, приведенное к числу с плавающей точкой |
?# |
Имя таблицы или колонки в кавычках идентификатора. В MySQL метод удаляет из значения обратные кавычки, а точку считает разделителем частей имени, например table.column. В PostgreSQL метод приводит имя к нижнему регистру и экранирует его целиком, точку не считает разделителем |
?v |
Значение колонки из строки таблицы, которую добавляет запрос. В MySQL — VALUES(<колонка>), в PostgreSQL — EXCLUDED.<колонка>. Для других типов баз данных метод выбрасывает исключение NotImplementedException |
?@ |
Список значений через запятую без скобок. Значение должно быть массивом или объектом Traversable и содержать хотя бы один элемент. Доступен с версии main 26.400.0 |
Значение null для всех плейсхолдеров, кроме ?# и ?@, превращается в NULL без кавычек.
Элементы списка для ?@ метод экранирует по отдельности. Строки и числа он подставляет в одинарных кавычках, элемент null — как NULL, объект SqlExpression — собранным SQL-фрагментом без кавычек.
Чтобы оставить в шаблоне знак вопроса как есть, поставьте перед ним обратный слеш, например \?.
Метод compile оставляет лишние плейсхолдеры без изменений, если значений меньше, чем плейсхолдеров. Лишние значения метод не использует. Два плейсхолдера подряд без разделителя, например ?i?i, метод не распознает как два.
Исключения
| Исключение | Когда возникает |
|---|---|
Bitrix\Main\ArgumentException |
Конструктор вызван без аргументов или первый аргумент равен null |
Примеры
Пример. Код создает условие по имени колонки и числу, собирает его и выводит результат:
<?php
use Bitrix\Main\DB\SqlExpression;
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';
$expression = new SqlExpression('?# > ?i', 'SORT', '100abc');
echo $expression->compile();
Для MySQL код выведет `SORT` > 100. Плейсхолдер ?i привел строку '100abc' к числу.
Пример. Код экранирует знак вопроса внутри маски LIKE, остальные знаки вопроса работают как плейсхолдеры:
<?php
use Bitrix\Main\DB\SqlExpression;
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';
$expression = new SqlExpression("?# LIKE '%\\?%' OR ?# = ?s", 'NAME', 'CODE', 'faq');
echo $expression->compile();
Для MySQL код выведет `NAME` LIKE '%?%' OR `CODE` = 'faq'.