Розробка 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 такої гарантії немає.