Создание собственных D7 ORM сущностей (таблиц) в Битрикс: Пошаговое руководство

Работать с готовыми ORM-сущностями вроде ElementTable — это хорошо, но настоящая сила D7 ORM раскрывается, когда вы создаете собственные таблицы для хранения данных вашего модуля. Давайте создадим простую таблицу для логов.

Шаг 1: Создание таблицы при установке модуля

Лучшее место для создания таблицы — инсталлятор вашего модуля (/local/modules/mymodule/install/index.php).

• getTableName(): Обязательный метод. Возвращает физическое имя таблицы в базе данных.
• getMap(): Обязательный метод. Описывает каждое поле таблицы. Здесь вы указываете тип поля (IntegerField, StringField, DatetimeField и т.д.), является ли оно первичным ключом, обязательным, и какие валидаторы применять.

// /local/modules/mymodule/install/index.php

use Bitrix\Main\Application;
use Bitrix\Main\Entity;

class mymodule extends CModule
{
    // ... инфо о модуле ...

    function DoInstall()
    {
        // ...
        $this->InstallDB();
        // ...
    }

    function InstallDB()
    {
        $connection = Application::getConnection();

        // Создаем таблицу, если ее нет
        if (!$connection->isTableExists('my_custom_logs')) {
            $entity = \My\Module\LogTable::getEntity();
            $entity->createDbTable();
        }
    }
    
    function DoUninstall()
    {
        // ...
        $this->UnInstallDB();
        // ...
    }

    function UnInstallDB()
    {
        $connection = Application::getConnection();
        // Удаляем таблицу при деинсталляции
        if ($connection->isTableExists('my_custom_logs')) {
            $connection->dropTable('my_custom_logs');
        }
    }
}

Мы используем ORM-сущность `LogTable` (которую мы сейчас создадим), чтобы она сама создала себе таблицу методом `createDbTable()`.

Шаг 2: Создание класса DataManager (`*Table.php`)
Теперь создадим сам ORM-класс. Все ORM-классы должны наследоваться от `\Bitrix\Main\Entity\DataManager` и находиться в папке `lib/` модуля.

// /local/modules/mymodule/lib/logtable.php

namespace My\Module;

use Bitrix\Main\Entity;
use Bitrix\Main\Type\DateTime;

class LogTable extends Entity\DataManager
{
    /**
     * Возвращает имя таблицы
     * @return string
     */
    public static function getTableName()
    {
        return 'my_custom_logs';
    }

    /**
     * Описывает поля таблицы (ORM-сущности)
     * @return array
     */
    public static function getMap()
    {
        return [
            // Поле ID: целочисленное, первичный ключ, автоинкремент
            new Entity\IntegerField('ID', [
                'primary' => true,
                'autocomplete' => true,
            ]),
            
            // Поле Дата/Время события
            new Entity\DatetimeField('TIMESTAMP_X', [
                'required' => true,
                'default_value' => new DateTime(), // По умолчанию - текущее время
            ]),
            
            // Поле Уровень лога (например, INFO, ERROR)
            new Entity\StringField('LEVEL', [
                'required' => true,
                'validation' => function() {
                    return [new Entity\Validator\Length(null, 50)];
                },
            ]),
            
            // Поле Сообщение
            new Entity\TextField('MESSAGE', [
                'required' => true,
            ]),
        ];
    }
}

Шаг 3: Используем нашу новую ORM-сущность!

После создания класса LogTable мы можем работать с ним точно так же, как с любой стандартной сущностью Битрикс.

use My\Module\LogTable;
use Bitrix\Main\Type\DateTime;

// Добавляем запись
$result = LogTable::add([
    'LEVEL' => 'INFO',
    'MESSAGE' => 'Пользователь вошел в систему',
    'TIMESTAMP_X' => new DateTime()
]);

if ($result->isSuccess()) {
    echo "Лог добавлен с ID: " . $result->getId();
}

// Выбираем все ошибки за последний час
$date = new DateTime();
$date->add('-1 hour');

$res = LogTable::getList([
    'select' => ['ID', 'MESSAGE'],
    'filter' => [
        '=LEVEL' => 'ERROR',
        '>TIMESTAMP_X' => $date
    ],
    'order' => ['ID' => 'DESC']
]);

while($row = $res->fetch()) {
    print_r($row);
}

Вывод:
Создание собственных ORM-сущностей — это фундаментальный навык для разработки модулей на D7.

Это позволяет вам инкапсулировать работу с вашими таблицами, использовать всю мощь ORM (выборки, валидацию, события) и делать код чистым и поддерживаемым.

D7 ORM, DataManager, getMap, custom entity, своя таблица Битрикс, ORM с нуля, создание модуля, install.php, IntegerField, StringField.