CUser::GetList в Битрикс: выборка пользователей

CUser::GetList — основной способ выбрать пользователей из базы по условию: активных, из определённой группы, зарегистрированных за период, с заполненным конкретным полем. Метод старого ядра, но по-прежнему рабочий и распространённый вариант для таких выборок.

Базовый вызов

<?php

$result = CUser::GetList(
    $by = 'ID',
    $order = 'ASC',
    ['ACTIVE' => 'Y'],
    ['SELECT' => ['UF_PHONE']]
);

while ($user = $result->Fetch()) {
    echo $user['LOGIN'] . ' — ' . $user['EMAIL'] . PHP_EOL;
}

Разберём аргументы по порядку.

Параметр	Назначение
`$by`	Поле сортировки: ID, LOGIN, LAST_LOGIN и другие
`$order`	ASC или DESC
Фильтр	Массив условий отбора
Параметры	Дополнительная выборка полей, в том числе UF-

Частые условия фильтра

<?php

// пользователи конкретной группы
$result = CUser::GetList('ID', 'ASC', ['GROUPS_ID' => 5]);

// зарегистрированные за период
$result = CUser::GetList('ID', 'ASC', [
    '>=DATE_REGISTER' => '01.01.2026',
    '<=DATE_REGISTER' => '31.01.2026',
]);

// по подстроке в почте
$result = CUser::GetList('ID', 'ASC', ['%EMAIL' => '@gmail.com']);

// комбинация условий
$result = CUser::GetList('ID', 'ASC', [
    'ACTIVE'     => 'Y',
    'GROUPS_ID'  => 5,
    '!EMAIL'     => false,
]);

Префиксы у ключей фильтра работают так же, как в ORM: >=, <=, % для подстроки, ! для отрицания. Условие 'GROUPS_ID' => 5 отбирает пользователей, состоящих в группе с этим идентификатором, — без необходимости отдельного соединения с таблицей групп в самом запросе.

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

Выборка пользовательских полей

UF-поля не приходят автоматически — их нужно явно запросить через параметр SELECT:

<?php

$result = CUser::GetList(
    'ID', 'ASC',
    ['ACTIVE' => 'Y'],
    ['SELECT' => ['UF_PHONE', 'UF_COMPANY']]
);

Без этого параметра значения дополнительных полей в результате отсутствуют, даже если они заполнены в базе, — частая причина, когда код обращается к $user['UF_PHONE'] и получает пустоту без всякой ошибки.

Постраничная выборка

На большом количестве пользователей выборку разумно разбивать на страницы, а не получать всех разом:

<?php

$result = CUser::GetList('ID', 'ASC', ['ACTIVE' => 'Y'], [
    'NAV_PARAMS' => ['nTopCount' => 100],
]);

Для полноценной пагинации со счётчиком страниц используются методы навигации результата, аналогичные тем, что применяются при выборке элементов инфоблока.

Подсчёт количества без выборки данных

<?php

$result = CUser::GetList('ID', 'ASC', ['ACTIVE' => 'Y']);
$count  = $result->SelectedRowsCount();

Метод удобен, когда нужно только число — например, для отображения «Зарегистрировано 4 218 пользователей» без необходимости получать и перебирать сами записи.

Частые ошибки

UF-поля не указаны в SELECT. Значения приходят пустыми, хотя данные в базе есть.
Выборка без фильтра на большой базе. Получение всех пользователей разом расходует память и время без необходимости.
Фильтр по группе как по строке. GROUPS_ID ожидает числовой идентификатор группы, а не её название.
Не используется SelectedRowsCount() там, где нужно только число. Вместо этого перебираются все строки ради подсчёта.

Итог

CUser::GetList — гибкая выборка пользователей с фильтром по стандартным полям, группам и произвольным условиям с теми же префиксами, что используются в ORM. Ключевое, что стоит помнить: пользовательские поля нужно запрашивать явно через SELECT, а на больших объёмах данных — использовать постраничную выборку вместо получения всех пользователей одним вызовом.

Теги: Пользователи Разработка