Встроенный кеш ORM в Битриксе: cache в getList()

ORM в Битриксе (D7) позволяет кешировать результаты запросов к базе данных прямо в методах getList(), getByPrimary(), getRow() и других. Достаточно передать параметр cache — и система сама сформирует ключ кеша, сохранит результат и очистит его при изменении данных.

1. Что такое ORM-кеш в Битриксе

В D7-ORM Битрикса (Bitrix\Main\ORM) запросы к таблицам делаются методами типа:

SomeTable::getList([...]);
SomeTable::getByPrimary($id, [...]);
SomeTable::getRow([...]);

Почти во всех этих методах можно передать параметр:

'cache' => [
    'ttl'         => 3600,  // время жизни кеша в секундах
    'cache_joins' => true,  // учитывать runtime-поля и Reference в формировании ключа кеша
]

ORM сам:

• формирует SQL-запрос,
• считает по нему ключ кеша (учитывая select, filter, order, runtime и другие параметры),
• кладёт результат в управляемый кеш (папка /bitrix/managed_cache/MYSQL/orm_*),
• автоматически очищает кеш при add/update/delete через соответствующий DataManager.

То есть вам не нужно городить Data\Cache — достаточно правильно настроить cache в самом запросе.

Важное ограничение: ORM-кеш не добавляет автоматически информацию о текущем пользователе или его правах доступа в ключ кеша. Если результаты запроса зависят от прав (например, фильтрация по группам доступа), обязательно включайте эти условия в параметры запроса (filter) или используйте другой механизм кеширования.

2. Базовый пример: кешируем список активных пользователей

Простейший случай — кешируем результат UserTable::getList():

 [
        'ID',
        'LOGIN',
        'NAME',
        'LAST_NAME',
        'EMAIL',
    ],
    'filter' => [
        '=ACTIVE' => 'Y',
    ],
    'order' => [
        'ID' => 'ASC',
    ],
    'limit' => 50,
    'cache' => [
        'ttl'         => 600,  // 10 минут
        'cache_joins' => true, // включать runtime-поля в ключ кеша
    ],
]);
$users = [];
while ($user = $result->fetch()) {
    $users[] = $user;
}
echo '
';
print_r($users);
echo '
';

Особенности:

• Ключ кеша считается из всех параметров запроса (select, filter, order, limit, offset, runtime и т.д.).
• TTL — в секундах.
• Если вы добавите/обновите пользователя через UserTable::add() / ::update() / ::delete(), ORM сам сбросит кеш по этой сущности.

Внимание: При использовании offset (пагинация) каждая страница будет создавать отдельную запись в кеше. Учитывайте это при настройке TTL.

3. Своя сущность + кеш ORM: пример с CityTable

Чаще всего ORM-кеш используют со своими таблицами/HL-блоками. Сделаем пример сущности CityTable и запрос с кешем.

3.1. Описываем сущность

/local/modules/vendor.demo/lib/internals/citytable.php:

 true,
                'autocomplete' => true,
            ]),
            new StringField('NAME', [
                'required' => true,
            ]),
            new StringField('CODE', [
                'required' => true,
                'unique'   => true,
            ]),
            new StringField('REGION', [
                'required' => false,
            ]),
        ];
    }
}

3.2. Кешируем список городов

Где-нибудь в компоненте/странице:

 [
        'ID',
        'NAME',
        'CODE',
        'REGION',
    ],
    'filter' => [
        '=REGION' => 'Moscow',
    ],
    'order' => [
        'NAME' => 'ASC',
    ],
    'cache' => [
        'ttl'         => 3600, // час
        'cache_joins' => true,
    ],
]);
$cities = [];
while ($row = $result->fetch()) {
    $cities[] = $row;
}
if (!empty($cities)) {
    echo '
';
    foreach ($cities as $city) {
        echo '
';
        echo htmlspecialcharsbx($city['NAME']) . ' (' . htmlspecialcharsbx($city['CODE']) . ')';
        if (!empty($city['REGION'])) {
            echo ' — ' . htmlspecialcharsbx($city['REGION']);
        }
        echo '
';
    }
    echo '
';
}

После первого выполнения запрос (SQL) будет кешироваться. При добавлении/изменении/удалении городов через CityTable::add()/update()/delete() кеш этой сущности будет очищен.

4. getByPrimary() и getRow() с кешем

Кеш работает не только с getList(), но и с другими методами ORM.

4.1. getByPrimary() с cache

 ['ID', 'NAME', 'CODE', 'REGION'],
        'cache'  => [
            'ttl' => 3600,
        ],
    ]
)->fetch();
echo '
';
print_r($city);
echo '
';

4.2. getRow() с кешем

 ['ID', 'NAME', 'CODE', 'REGION'],
    'filter' => [
        '=CODE' => 'msk',
    ],
    'cache' => [
        'ttl' => 600,
    ],
]);
echo '
';
print_r($city);
echo '
';

getRow() вернёт одну строку, но кешируется результат аналогично getList().

5. Кеш + JOIN'ы и runtime-поля (параметр cache_joins)

Параметр cache_joins управляет включением runtime-полей в формирование ключа кеша:

• При cache_joins = false ключ формируется только по основному запросу без учёта JOIN'ов
• При cache_joins = true в расчёт ключа попадают все runtime-поля и Reference

5.1. Описание CountryTable

Создадим таблицу стран для связи:

/local/modules/vendor.demo/lib/internals/countrytable.php:

 true,
                'autocomplete' => true,
            ]),
            new StringField('NAME', [
                'required' => true,
            ]),
            new StringField('CODE', [
                'required' => true,
                'unique'   => true,
            ]),
        ];
    }
}

5.2. Обновляем CityTable с полем COUNTRY_ID

/local/modules/vendor.demo/lib/internals/citytable.php:

 true,
                'autocomplete' => true,
            ]),
            new StringField('NAME', [
                'required' => true,
            ]),
            new StringField('CODE', [
                'required' => true,
                'unique'   => true,
            ]),
            new StringField('REGION', [
                'required' => false,
            ]),
            new IntegerField('COUNTRY_ID', [
                'required' => false,
            ]),
        ];
    }
}

5.3. Запрос с runtime-связью и кешем

 [
        'ID',
        'NAME',
        'CODE',
        'COUNTRY_ID',
        'COUNTRY_NAME' => 'COUNTRY.NAME',
        'COUNTRY_CODE' => 'COUNTRY.CODE',
    ],
    'runtime' => [
        new Reference(
            'COUNTRY',
            CountryTable::class,
            Join::on('this.COUNTRY_ID', 'ref.ID')
        ),
    ],
    'filter' => [
        '=COUNTRY.CODE' => 'ru',
    ],
    'order' => [
        'NAME' => 'ASC',
    ],
    'cache' => [
        'ttl'         => 1800,
        'cache_joins' => true, // Включаем кеш с учётом runtime-полей
    ],
]);
$cities = [];
while ($row = $result->fetch()) {
    $cities[] = $row;
}
echo '
';
print_r($cities);
echo '
';

Примечание: При использовании cache_joins = true ORM включает runtime-поля (в том числе Reference) в формирование ключа кеша. Без этого параметра запросы с разными JOIN'ами могли бы получить одинаковый кеш, что привело бы к некорректным результатам.

6. Репозиторий с ORM-кешем: один раз написал — пользуйся везде

Удобный паттерн — писать репозитории, где кеш настроен внутри, а во всём проекте просто вызываются методы.

6.1. Репозиторий для городов

/local/php_interface/lib/CityRepository.php:

 [
                'ID',
                'NAME',
                'CODE',
                'REGION',
            ],
            'order' => [
                'NAME' => 'ASC',
            ],
            'cache' => [
                'ttl' => $ttl,
            ],
        ]);
        $cities = [];
        while ($row = $result->fetch()) {
            $cities[] = $row;
        }
        return $cities;
    }
    /**
     * Получить город по коду с кешем.
     *
     * @param string $code
     * @param int    $ttl
     *
     * @return array|null
     * @throws ArgumentException
     * @throws ObjectPropertyException
     * @throws SystemException
     */
    public static function getCityByCode(string $code, int $ttl = 600): ?array
    {
        $row = CityTable::getRow([
            'select' => [
                'ID',
                'NAME',
                'CODE',
                'REGION',
            ],
            'filter' => [
                '=CODE' => $code,
            ],
            'cache' => [
                'ttl' => $ttl,
            ],
        ]);
        if (!is_array($row)) {
            return null;
        }
        return $row;
    }
}

6.2. Использование репозитория

Все города';
    echo '
';
    print_r($cities);
    echo '
';

    echo '
Москва
';
    echo '
';
    print_r($moscow);
    echo '
';
} catch (Exception $e) {
    // Обработка исключений
    echo 'Ошибка: ' . $e->getMessage();
}

Плюсы:

• Весь проект обращается к городам через один слой.
• TTL легко менять в одном месте.
• При необходимости можно дописать ручную очистку кеша, логирование, статистику.

7. Очистка ORM-кеша: cleanCache()

ORM сам очищает кеш при add/update/delete, если вы изменяете данные через соответствующий DataManager.

Но иногда вы:

• правите данные напрямую SQL-скриптом,
• меняете структуру таблицы,
• импортируете данные сторонними инструментами.

В этом случае можно принудительно сбросить кеш сущности:

initCache($ttl, $cacheId, $cacheDir)) {
    $result = $cache->getVars();
} elseif ($cache->startDataCache()) {
    // Внутри репозитория уже есть ORM-кеш
    $cities = CityRepository::getAllCities(600);
    if (empty($cities)) {
        $cache->abortDataCache();
    } else {
        $result['CITIES'] = $cities;
        // Можно добавить дополнительные теги для управления кешем
        $cache->endDataCache($result);
    }
}
echo '
';
print_r($result);
echo '
';