ORM в Битрикс: полное руководство по работе с ORM с примерами кода

Современная разработка на платформе 1С-Битрикс все чаще использует D7 API и ORM вместо устаревших методов работы с базой данных. ORM позволяет получать, изменять и удалять данные без написания SQL-запросов, что делает код более безопасным, понятным и удобным для поддержки. В этой статье подробно рассмотрим, что такое ORM в Битрикс, как оно работает и как использовать его на практике с примерами кода.

Что такое ORM

ORM (Object-Relational Mapping) — это технология объектно-реляционного отображения, которая позволяет работать с данными базы данных через PHP-классы и объекты. Вместо SQL-запроса:

SELECT * FROM b_user WHERE ID = 1

используется PHP-код:

UserTable::getById(1);

ORM самостоятельно формирует SQL-запрос и возвращает результат в удобном формате.

Преимущества ORM в Битрикс

Использование ORM дает множество преимуществ:

удобная работа с данными;
меньше SQL-кода;
защита от SQL-инъекций;
поддержка связей между таблицами;
удобная фильтрация и сортировка;
высокая читаемость кода;
совместимость с D7 API.

Сегодня ORM считается стандартом разработки для новых проектов на Битрикс.

Нужна помощь с Битрикс?

Основные классы ORM

Большинство таблиц системы имеют собственные ORM-классы. Например:

Bitrix\Main\UserTable
Bitrix\Iblock\ElementTable
Bitrix\Main\GroupTable
Bitrix\Main\FileTable

Перед использованием необходимо подключить нужный класс:

use Bitrix\Main\UserTable;

Получение одного пользователя

Самый простой пример — получение пользователя по ID.

use Bitrix\Main\UserTable;

$user = UserTable::getById(1)->fetch();

echo $user['LOGIN'];

После выполнения запроса в переменной $user будет массив с данными пользователя.

Получение списка пользователей

ORM позволяет получать сразу несколько записей.

use Bitrix\Main\UserTable;

$result = UserTable::getList([
    'select' => ['ID', 'LOGIN', 'EMAIL'],
    'filter' => ['ACTIVE' => 'Y'],
    'order'  => ['ID' => 'DESC']
]);

while ($user = $result->fetch()) {
    echo $user['LOGIN'] . '<br>';
}

Данный запрос вернет всех активных пользователей.

Фильтрация данных

Для отбора записей используется параметр filter. Примеры:

По ID

'filter' => ['ID' => 15]

По логину

'filter' => ['LOGIN' => 'admin']

По нескольким значениям

'filter' => [
    'ACTIVE' => 'Y',
    '=GROUPS.GROUP_ID' => 1
]

По диапазону дат

'filter' => [
    '>=DATE_REGISTER' => '01.01.2025',
    '<=DATE_REGISTER' => '31.12.2025'
]

ORM поддерживает десятки операторов фильтрации.

Операторы фильтрации ORM

Наиболее используемые операторы:

Оператор	Значение
=	равно
!=	не равно
>	больше
<	меньше
>=	больше или равно
<=	меньше или равно
%	содержит
!%	не содержит
@	входит в массив
!@	не входит в массив

Пример поиска пользователей по части e-mail:

'filter' => [
    '%EMAIL' => '@gmail.com'
]

Добавление записи через ORM

Для создания новой записи используется метод add(). Пример добавления пользователя:

use Bitrix\Main\UserTable;

$result = UserTable::add([
    'LOGIN' => 'testuser',
    'EMAIL' => 'test@example.com',
    'ACTIVE' => 'Y'
]);

Однако для пользователей рекомендуется использовать класс CUser, поскольку он выполняет дополнительную обработку паролей и системных полей. Наиболее часто ORM применяется для собственных таблиц.

Обновление данных

Изменение записи выполняется методом update().

use Bitrix\Main\UserTable;

UserTable::update(
    15,
    [
        'EMAIL' => 'newmail@example.com'
    ]
);

Где:

15 — ID записи;
массив содержит изменяемые поля.

Удаление записи

Для удаления используется метод delete().

use Bitrix\Main\UserTable;

UserTable::delete(15);

После выполнения запись будет удалена из базы данных. Следует использовать данный метод с осторожностью.

Получение количества записей

Иногда требуется узнать количество элементов.

$count = UserTable::getCount([
    'ACTIVE' => 'Y'
]);

echo $count;

Это значительно удобнее, чем писать отдельный SQL-запрос.

Работа с собственными таблицами

Одно из главных преимуществ ORM — возможность создавать собственные сущности. Пример класса:

namespace Local\ORM;

use Bitrix\Main\ORM\Data\DataManager;
use Bitrix\Main\ORM\Fields\IntegerField;
use Bitrix\Main\ORM\Fields\StringField;

class ProductTable extends DataManager
{
    public static function getTableName()
    {
        return 'local_products';
    }

    public static function getMap()
    {
        return [
            new IntegerField('ID', [
                'primary' => true,
                'autocomplete' => true
            ]),
            new StringField('NAME'),
            new StringField('ARTICLE')
        ];
    }
}

Теперь можно выполнять запросы:

use Local\ORM\ProductTable;

$list = ProductTable::getList()->fetchAll();

JOIN в ORM Битрикс

ORM поддерживает связи между таблицами через ReferenceField. Пример:

new Reference(
    'USER',
    UserTable::class,
    ['=this.CREATED_BY' => 'ref.ID']
)

После этого можно получать связанные данные в одном запросе.

'select' => [
    'ID',
    'NAME',
    'USER.LOGIN'
]

Это аналог SQL JOIN.

Runtime-поля

Иногда необходимо добавить вычисляемое поле прямо в запрос. Пример:

'runtime' => [
    new ExpressionField(
        'FULL_NAME',
        "CONCAT(%s,' ',%s)",
        ['NAME', 'LAST_NAME']
    )
]

Теперь можно получить:

echo $item['FULL_NAME'];

без дополнительной обработки в PHP.

ORM и инфоблоки

Начиная с современных версий Битрикс, многие сущности инфоблоков также поддерживают ORM. Например:

use Bitrix\Iblock\ElementTable;

$list = ElementTable::getList([
    'select' => ['ID', 'NAME']
]);

Однако для работы со свойствами инфоблоков часто продолжают использовать:

CIBlockElement

или сгенерированные ORM-классы элементов.

Типичные ошибки при работе с ORM

Unknown parameter

Ошибка возникает при неправильном указании параметров запроса. Например:

[
    '>=DATE_CREATE' => $date
]

должно находиться внутри массива filter. Правильно:

[
    'filter' => [
        '>=DATE_CREATE' => $date
    ]
]

Не найден класс

Необходимо проверить:

Loader::includeModule('iblock');

или правильность namespace.

Пустой результат

Следует убедиться:

что данные существуют;
правильно указаны поля;
корректно настроены фильтры.

Когда использовать ORM

ORM рекомендуется применять в следующих случаях:

разработка новых модулей;
создание собственных таблиц;
сложные выборки данных;
интеграции с внешними сервисами;
работа с D7 API.

Для старых проектов допускается использование legacy-классов, однако новые решения лучше строить на ORM.

Заключение

ORM в Битрикс — это современный инструмент для работы с базой данных через объектный интерфейс. Он позволяет выполнять выборку, добавление, обновление и удаление данных без написания SQL-запросов. Использование ORM делает код более безопасным, читаемым и удобным для сопровождения. Если вы разрабатываете новые проекты на Битрикс D7, рекомендуется использовать именно ORM как основной способ взаимодействия с данными.