Подготовить колонки и значения для INSERT SqlHelper::prepareInsert
Модуль: main — подключать отдельно не нужно
Метод SqlHelper::prepareInsert готовит список колонок и значений для запроса INSERT. Метод экранирует значения и преобразует их по типам колонок таблицы. Метод Connection::add использует его, чтобы добавить строку.
Сигнатура метода в классе Bitrix\Main\DB\SqlHelper:
public function prepareInsert($tableName, array $fields, $returnAsArray = false)
Параметры
Обязательные параметры обозначены *
| Параметр | Тип | Описание |
|---|---|---|
| tableName* | string |
Задает имя таблицы. Таблица должна существовать |
| fields* | array |
Задает значения в виде имя колонки => значение. Регистр имени не важен. Метод превращает null в NULL, объект SqlExpression — в собранный SQL-фрагмент |
| returnAsArray | bool |
Возвращает колонки и значения массивами, если равен true. По умолчанию — false, строками через запятую |
Типы tableName и returnAsArray в таблице описывают назначение аргументов. Сигнатура PHP не объявляет их.
Возвращаемое значение
Метод возвращает массив из трех элементов.
|
Ключ |
Описание |
|
0 |
Содержит имена колонок в кавычках |
|
1 |
Содержит значения в формате SQL в том же порядке |
|
2 |
Содержит дополнительные данные для отдельной записи больших полей. В MySQL и PostgreSQL массив всегда пуст |
Колонку, которой нет в таблице, метод пропускает и выдает предупреждение E_USER_WARNING. Описание колонок метод получает через Connection::getTableFields.
Исключения
| Исключение | Когда возникает |
|---|---|
Bitrix\Main\DB\SqlQueryException |
В MySQL таблицы нет |
Bitrix\Main\DB\ConnectionException |
Подключиться к базе данных не удалось |
Bitrix\Main\ArgumentException |
Код передал для колонки даты и времени непустое значение, но не объект Bitrix\Main\Type\Date |
\Error |
Код передал для колонки даты без времени непустое значение, но не объект Bitrix\Main\Type\Date |
Примеры
Пример. Код готовит и выполняет запрос INSERT для рабочей таблицы:
<?php
use Bitrix\Main\Application;
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';
$connection = Application::getConnection();
$helper = $connection->getSqlHelper();
$connection->queryExecute('CREATE TABLE demo_api_units (ID INT NOT NULL, CODE VARCHAR(20) NOT NULL)');
try
{
[$columns, $values] = $helper->prepareInsert('demo_api_units', ['ID' => 1, 'CODE' => "kg'"]);
$connection->queryExecute(
'INSERT INTO ' . $helper->quote('demo_api_units') . ' (' . $columns . ') VALUES (' . $values . ')'
);
echo $connection->queryScalar('SELECT CODE FROM demo_api_units');
}
finally
{
$connection->dropTable('demo_api_units');
}