Разработка ORM-сущностей 1С-Битрикс D7

Разработка ORM-сущностей 1С-Битрикс D7

ORM D7 — ответ Битрикс на вопрос «как работать с базой данных, не заваривая сырой SQL на каждый чих». DataManager-сущность — это PHP-класс, который описывает таблицу БД, её поля и связи с другими таблицами. Вместо $DB->Query("SELECT ...") вы пишете MyTable::getList([...]) и получаете типизированные объекты вместо сырых массивов. Платформа появилась в Битрикс 14 и с тех пор является стандартом для серьёзной разработки.

Базовая структура DataManager

Минимальная сущность:

namespace MyProject\Storage;

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

class OrderLogTable extends DataManager
{
    public static function getTableName(): string
    {
        return 'my_order_log';
    }

    public static function getMap(): array
    {
        return [
            new IntegerField('ID', [
                'primary'      => true,
                'autocomplete' => true,
            ]),
            new IntegerField('ORDER_ID', [
                'required' => true,
            ]),
            new StringField('ACTION', [
                'required'  => true,
                'size'      => 100,
            ]),
            new DatetimeField('CREATED_AT', [
                'default_value' => new \Bitrix\Main\Type\DateTime(),
            ]),
        ];
    }
}

Класс регистрируется в autoload-карте модуля или через PSR-4 в composer.json внутри /local/.

Типы полей ORM

Для валидации полей используется validation в параметрах поля:

new StringField('STATUS', [
    'required'   => true,
    'values'     => ['DRAFT', 'ACTIVE', 'CLOSED'],
    'validation' => function() {
        return [new \Bitrix\Main\ORM\Fields\Validators\LengthValidator(1, 50)];
    },
]),

Связи между сущностями

Один-ко-многим (Reference):

use Bitrix\Main\ORM\Fields\Relations\Reference;
use Bitrix\Main\ORM\Query\Join;

// В OrderLogTable добавляем связь с заказом
new Reference(
    'ORDER',
    \Bitrix\Sale\Internals\OrderTable::class,
    Join::on('this.ORDER_ID', 'ref.ID'),
    ['join_type' => 'LEFT']
),

Один-к-одному и многие-ко-многим реализуются аналогично, через Reference с соответствующими ключами или через промежуточную таблицу.

После описания связи в запросе можно получать данные joined-таблицы:

$result = OrderLogTable::getList([
    'select' => ['ID', 'ACTION', 'ORDER_.USER_ID', 'ORDER_.DATE_INSERT'],
    'filter' => ['ORDER_ID' => 42],
]);

Создание таблицы: миграции

Таблицу создаёт метод createDbTable():

// В методе установки модуля
OrderLogTable::getEntity()->createDbTable();

Для изменения структуры существующей таблицы — прямые DDL-запросы через Application::getConnection():

$conn = \Bitrix\Main\Application::getConnection();
$conn->query("ALTER TABLE my_order_log ADD COLUMN CONTEXT TEXT DEFAULT NULL");

Битрикс не имеет встроенного механизма миграций — для продакшн-проектов это решается либо собственным скриптом-мигратором, либо сторонними пакетами типа arrilot/bitrix-migrations.

ORM-запросы: основные операции

Выборка с условиями:

$result = OrderLogTable::getList([
    'select'  => ['ID', 'ORDER_ID', 'ACTION', 'CREATED_AT'],
    'filter'  => [
        '>CREATED_AT' => new \Bitrix\Main\Type\DateTime('-7 days'),
        'ACTION'      => 'STATUS_CHANGED',
    ],
    'order'   => ['CREATED_AT' => 'DESC'],
    'limit'   => 50,
    'offset'  => 0,
]);

while ($row = $result->fetch()) {
    // $row — ассоциативный массив
}

Объектный интерфейс (D7 EO — Entity Objects, Битрикс 18+):

$result = OrderLogTable::getList([
    'select' => ['*'],
    'filter' => ['ORDER_ID' => 42],
]);

foreach ($result->fetchCollection() as $log) {
    echo $log->getAction(); // типизированный getter
    $log->setAction('UPDATED');
    $log->save();
}

Добавление:

$addResult = OrderLogTable::add([
    'ORDER_ID'   => 42,
    'ACTION'     => 'STATUS_CHANGED',
    'CREATED_AT' => new \Bitrix\Main\Type\DateTime(),
]);

if ($addResult->isSuccess()) {
    $newId = $addResult->getId();
}

Обновление и удаление:

OrderLogTable::update($id, ['ACTION' => 'CANCELLED']);
OrderLogTable::delete($id);

Агрегация и группировка

$result = OrderLogTable::getList([
    'select' => [
        new \Bitrix\Main\ORM\Query\Query\ExpressionField('CNT', 'COUNT(*)'),
        'ACTION',
    ],
    'group' => ['ACTION'],
]);

Индексы

Индексы добавляются отдельно от создания таблицы:

$conn = \Bitrix\Main\Application::getConnection();
$conn->query("CREATE INDEX idx_order_log_order_id ON my_order_log (ORDER_ID)");
$conn->query("CREATE INDEX idx_order_log_created ON my_order_log (CREATED_AT)");

Для часто фильтруемых полей индексы обязательны. На таблице в 500 000 строк запрос без индекса по ORDER_ID — это полный скан.

Кеширование запросов

ORM интегрируется с кешем Битрикс:

$result = OrderLogTable::getList([
    'select' => ['ID', 'ACTION'],
    'filter' => ['ORDER_ID' => 42],
    'cache'  => ['ttl' => 3600, 'cache_joins' => true],
]);

Кеш сбрасывается автоматически при изменении данных через ORM-методы (если включён управляемый кеш).

Сроки

DataManager-сущности — это инвестиция в читаемость и поддерживаемость кода. Через год разработчик, не писавший этот код, разберётся в схеме БД за час, а не за день. При работе с сырым SQL такой гарантии нет.