Добавить строку Connection::add

Модуль: main — подключать отдельно не нужно

Доступно с версии: 14.0.0

Метод Connection::add добавляет строку в таблицу и возвращает ее идентификатор. Метод экранирует значения и преобразует их по типам колонок таблицы. Для таблиц ORM-классов используйте метод add ORM-класса. Он проверяет поля и вызывает события.

Сигнатура метода в классе Bitrix\Main\DB\Connection:

public function add($tableName, array $data, $identity = "ID")

Параметры

Обязательные параметры обозначены *

Параметр Тип Описание
tableName* string Задает имя таблицы
data* array Задает значения колонок в виде имя колонки => значение. Регистр имени не важен. Колонку, которой нет в таблице, метод пропускает и выдает предупреждение E_USER_WARNING
identity string, null Задает имя автоинкрементной колонки. По умолчанию — ID. Учитывает только PostgreSQL. Для таблицы без автоинкремента передайте null

Типы tableName и identity в таблице описывают назначение аргументов. Сигнатура PHP не объявляет их.

Возвращаемое значение

Результат зависит от реализации.

Реализация Что возвращает
MysqliConnection Результат getInsertedId — значение автоинкремента добавленной строки
PgsqlConnection Если identity не null и в data нет значения этой колонки или значение — объект SqlExpression, метод добавляет строку с RETURNING и возвращает новое значение колонки целым числом. Иначе метод возвращает data[identity] или null

Метод читает описание колонок через getTableFields, поэтому таблица должна существовать.

Исключения

Исключение Когда возникает
Bitrix\Main\DB\SqlQueryException База данных вернула ошибку при выполнении запроса
Bitrix\Main\DB\DuplicateEntryException Строка нарушила уникальность ключа. Класс наследует SqlQueryException
Bitrix\Main\DB\ConnectionException Подключиться к базе данных не удалось
Bitrix\Main\ArgumentException Код передал для колонки даты и времени непустое значение, но не объект Bitrix\Main\Type\Date
\Error Код передал для колонки даты без времени непустое значение, но не объект Bitrix\Main\Type\Date

Примеры

Пример. Код создает рабочую таблицу с автоинкрементом, добавляет строку и выводит ее идентификатор. Блок finally удаляет таблицу:

<?php
use Bitrix\Main\Application;
use Bitrix\Main\ORM\Fields\IntegerField;
use Bitrix\Main\ORM\Fields\StringField;

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

$connection = Application::getConnection();

$connection->createTable(
    'demo_api_units',
    [
        'ID' => new IntegerField('ID'),
        'CODE' => new StringField('CODE', ['size' => 20]),
    ],
    ['ID'],
    ['ID']
);

try
{
    $id = $connection->add('demo_api_units', ['CODE' => "kg'"]);
    echo $id;
}
finally
{
    $connection->dropTable('demo_api_units');
}

Метод сам экранировал апостроф в значении kg'.

Смотрите также