Руководство по работе с классом UserTable в 1С-Битрикс D7

UserTable — это класс, позволяющий получать доступ к данным пользователей в 1С-Битрикс на основе новой концепции работы с данными (D7). Он наследуется от класса Bitrix\Main\ORM\Data\DataManager (в версиях до 18.0.2 модуля main — от класса Bitrix\Main\Entity\DataManager).

Благодаря объектно-ориентированному подходу D7 можно гибко работать с базой данных, строить запросы, фильтрацию и сортировку, а также использовать связи (relations) и выражения (expressions). В этой статье мы разберём, как использовать UserTable на практике, и приведём ряд примеров.

1. Общая информация

1.1. Где располагается класс UserTable

Файл, в котором объявлен класс UserTable, находится по пути:

bitrix/modules/main/lib/user.php

Основная таблица в базе данных, которую этот класс обёртывает, — b_user.

1.2. Цепочка наследования

Bitrix\Main\UserTable
        ↳ Наследуется от Bitrix\Main\ORM\Data\DataManager (до версии 18.0.2 — от Bitrix\Main\Entity\DataManager)

1.3. Важное изменение с версии 20.0.1300

С версии 20.0.1300 1С-Битрикс формы авторизации и регистрации принимают данные только методом POST. На это стоит обратить особое внимание при разработке. Старые формы и запросы методом GET работать не будут — обязательно нужно использовать $_POST.

2. Основные методы и их назначение

В классе UserTable переопределён стандартный функционал DataManager, а также объявлены собственные методы. Часть методов недоступна напрямую (например, add(), update(), delete() выбрасывают исключение NotImplementedException, с сообщением «Use CUser class.»). Это значит, что для создания, обновления и удаления пользователей в системе нужно использовать класс CUser. Но для получения списка пользователей и сложных выборок данная сущность UserTable очень удобна.

Основные публичные методы, которые мы обычно используем:

• public static function getList(array $parameters = []) — получение списка записей (в данном случае пользователей).
• public static function getById($id) — выборка конкретной записи по ID.
• public static function getByPrimary($primary, array $parameters = []) — выборка по одному или нескольким первичным ключам (в случае пользователей это обычный ID).

Методы add(), update(), delete() в UserTable переопределены и выбрасывают исключение. Повторимся, для создания и редактирования пользователей используйте CUser::Add(), CUser::Update() и CUser::Delete().

3. Простой пример получения списка пользователей

Ниже — минимальный пример, который демонстрирует, как получить список активных пользователей и вывести их ID, NAME, LAST_NAME:

use Bitrix\Main\UserTable;

$select = ['ID', 'NAME', 'LAST_NAME'];
$filter = ['ACTIVE' => 'Y'];

$res = UserTable::getList([
    'select' => $select,
    'filter' => $filter
]);

$users = $res->fetchAll();

// Для отладки выведем массив
echo '
';
var_dump($users);
echo '
';

В переменной $users вы получите массив, содержащий все необходимые данные. Каждый элемент массива будет содержать выбранные поля пользователя, например:

Array
(
    [0] => Array
        (
            [ID] => 1
            [NAME] => Иван
            [LAST_NAME] => Иванов
        )

    [1] => Array
        (
            [ID] => 5
            [NAME] => Анна
            [LAST_NAME] => Смирнова
        )
    ...
)

4. Подробные примеры работы с параметрами

Метод getList() поддерживает не только select и filter, но и другие параметры, такие как order, limit, offset, а также позволяет использовать сложные конструкции для фильтрации и связи (relation, join).

4.1. Сортировка результата

Чтобы, например, отсортировать пользователей сначала по фамилии, а затем по имени, используйте параметр order:

$res = UserTable::getList([
    'select' => ['ID', 'NAME', 'LAST_NAME'],
    'filter' => ['ACTIVE' => 'Y'],
    'order'  => [
        'LAST_NAME' => 'ASC',
        'NAME' => 'ASC'
    ],
]);

4.2. Ограничение выборки limit и offset

Допустим, нам нужно выбрать только 10 пользователей, пропустив первых 5. Можно добавить:

$res = UserTable::getList([
    'select' => ['ID', 'NAME', 'LAST_NAME'],
    'filter' => ['ACTIVE' => 'Y'],
    'order'  => ['ID' => 'DESC'],
    'limit'  => 10,
    'offset' => 5,
]);

4.3. Сложная фильтрация

Фильтр поддерживает разные операторы (=, >, >=, !, !=, %, search, between и другие). Примеры:

$filter = [
    'LOGIC' => 'OR',  // Логическое ИЛИ
    [
        '=ACTIVE' => 'Y',
        '>ID'     => 2
    ],
    [
        '=LAST_NAME' => 'Петров',
        '!=NAME'     => 'Сергей'
    ]
];

$res = UserTable::getList([
    'select' => ['ID', 'NAME', 'LAST_NAME', 'ACTIVE'],
    'filter' => $filter
]);

Здесь результатом будут все активные пользователи с ID > 2 ИЛИ все пользователи с фамилией "Петров" и именем не "Сергей".

4.4. Использование ExpressionField

В UserTable присутствуют предопределённые поля-выражения, например, IS_ONLINE, определяющее, находится ли пользователь «онлайн» (по полю LAST_ACTIVITY_DATE и настройке сессии). Такое поле можно напрямую выбрать:

$res = UserTable::getList([
    'select' => [
        'ID',
        'NAME',
        'IS_ONLINE'  // это ExpressionField
    ],
    'filter' => ['ACTIVE' => 'Y']
]);

while ($arUser = $res->fetch())
{
    echo 'Пользователь ' . $arUser['NAME'] . ' — ' .
         ($arUser['IS_ONLINE'] === 'Y' ? 'онлайн' : 'офлайн') . '
';
}

5. Ссылочные поля и связи (References)

D7 позволяет работать со связями OneToMany, ManyToOne, ManyToMany и Reference. В UserTable есть поля:

• GROUPS — связь один-ко-многим (OneToMany) с UserGroupTable.
• INDEX и другие поля-референсы, указывающие на UserIndexTable и т. д.

Например, можно сформировать запрос, который получает данные о пользователе и информацию о привязанных группах. Однако обычно для подобного у UserGroupTable своя реализация. Но в самом простом виде это может выглядеть так (пример условный):

use Bitrix\Main\UserGroupTable;
use Bitrix\Main\UserTable;

$res = UserTable::getList([
    'select' => [
        'ID',
        'NAME',
        'LAST_NAME',
        'GROUPS.GROUP_ID',  // Получаем поле из связи OneToMany
    ],
    'filter' => ['ACTIVE' => 'Y'],
    'runtime' => [
        // Если нужно добавить runtime-поле,
        // например, Reference на произвольные таблицы,
        // можно сделать это здесь
    ]
]);

while ($arUser = $res->fetch())
{
    echo 'ID: ' . $arUser['ID'] . ' | ' .
         'ФИО: ' . $arUser['NAME'] . ' ' . $arUser['LAST_NAME'] . ' | ' .
         'GROUP_ID: ' . $arUser['BITRIX_MAIN_USER_MAIN_USERGROUPTABLE_GROUPS_GROUP_ID'] . '
';
}

Обратите внимание, что при получении полей из связи GROUPS.GROUP_ID возвращаемый ключ может формироваться автоматически — в формате ПОЛНОЕ_ИМЯ_ПОЛЯ. Это связано с тем, как D7 формирует алиасы для связанных таблиц. Чтобы избежать таких длинных названий, обычно используют механизм runtime или корректное описание связи с указанием map() и configureJoinType().

6. Как добавлять и редактировать пользователей

Как уже говорилось, методы add(), update(), delete() у UserTable выбрасывают исключение:

public static function add(array $data)
{
    throw new NotImplementedException("Use CUser class.");
}

Это значит, что «правильный» способ создания и редактирования пользователей заключается в использовании классических методов:

$user = new CUser;
$fields = [
    "NAME"      => "Иван",
    "LAST_NAME" => "Петров",
    "LOGIN"     => "ivan.petrov",
    "ACTIVE"    => "Y",
    "PASSWORD"  => "test1234",
    "CONFIRM_PASSWORD" => "test1234",
    "EMAIL"     => "ivan.petrov@example.com"
];

$userId = $user->Add($fields);
if (intval($userId) > 0) {
    echo "Пользователь успешно добавлен, ID: ".$userId;
} else {
    echo "Ошибка при добавлении: ".$user->LAST_ERROR;
}

Обновление

$user = new CUser;
$fields = [
    "NAME" => "Иван (изменено)",
];
$res = $user->Update($userId, $fields);
if ($res) {
    echo "Пользователь обновлён";
} else {
    echo $user->LAST_ERROR;
}

Удаление

$user = new CUser;
$res = $user->Delete($userId);
if ($res) {
    echo "Пользователь удалён";
} else {
    echo "Не удалось удалить пользователя.";
}

7. Важное о POST-запросах (начиная с версии 20.0.1300)

Начиная с версии 20.0.1300 1С-Битрикс, все формы регистрации и авторизации принимают данные только методом POST. То есть при работе через CUser::Login(), CUser::Register() или написании своих форм нужно убедиться, что форма отправляет данные методом POST.

Пример HTML-формы авторизации (упрощённый):

<form action="/login/" method="post">
    <input type="text" name="USER_LOGIN" placeholder="Логин">
    <input type="password" name="USER_PASSWORD" placeholder="Пароль">
    <input type="hidden" name="AUTH_FORM" value="Y">
    <input type="hidden" name="TYPE" value="AUTH">
    <button type="submit">Войти</button>
</form>

Будьте внимательны: если по-прежнему использовать GET, ничего не произойдёт — авторизация просто не сработает.

8. Дополнительные возможности

8.1. Проверка, находится ли пользователь онлайн

Как мы уже рассмотрели, у UserTable есть поле-выражение IS_ONLINE, которое сравнивает текущее время с полем LAST_ACTIVITY_DATE. Это может быть полезно, если нужно отобразить статус пользователя.

8.2. Полнотекстовый поиск и индексирование (UserIndexTable)

В UserTable определён ряд служебных методов, ответственных за индексирование и поиск (indexRecord(), deleteIndexRecord(), и т. д.). Они работают совместно с таблицей UserIndexTable. Это используется внутри платформы (Intranet, чат, порталы и др.). Если вы разрабатываете собственный функционал полнотекстового поиска по пользователям, можете изучить, как Bitrix использует эти методы, — но обычно стандартных инструментов (Глобальный поиск, фильтр в списке пользователей) бывает достаточно.

8.3. Получение групп пользователя

Метод UserTable::getUserGroupIds($userId) возвращает все группы (включая анонимные, группу «Все пользователи») для конкретного пользователя. Это может пригодиться, если нужно быстро понять, где пользователь состоит:

$groups = UserTable::getUserGroupIds($userId);
var_dump($groups); // Массив ID групп, например [1,2,3,4]

9. Практический пример: фильтр по телефону, e-mail и городам

Допустим, вы хотите получить всех пользователей, у которых в поле PERSONAL_CITY указано «Москва» ИЛИ у которых телефон начинается на «+7 911» ИЛИ почта — example.com. При этом нужно взять только 20 пользователей. Пример:

use Bitrix\Main\UserTable;

$filter = [
    'LOGIC' => 'OR',
    [
        '=PERSONAL_CITY' => 'Москва'
    ],
    [
        '%PERSONAL_MOBILE' => '+7 911'
    ],
    [
        '%EMAIL' => '@example.com'
    ]
];

$res = UserTable::getList([
    'select' => [
        'ID',
        'NAME',
        'LAST_NAME',
        'PERSONAL_CITY',
        'PERSONAL_MOBILE',
        'EMAIL'
    ],
    'filter' => $filter,
    'order'  => ['ID' => 'ASC'],
    'limit'  => 20
]);

while ($arUser = $res->fetch())
{
    echo "ID: {$arUser['ID']}, " .
         "ФИО: {$arUser['NAME']} {$arUser['LAST_NAME']}, " .
         "Город: {$arUser['PERSONAL_CITY']}, " .
         "Телефон: {$arUser['PERSONAL_MOBILE']}, " .
         "Email: {$arUser['EMAIL']} 
";
}

10. Резюме

UserTable — мощный инструмент для получения и фильтрации списка пользователей в новом стиле ORM (D7) в 1С-Битрикс. Он:

1. Наследуется от DataManager, что позволяет использовать весь функционал D7 (фильтры, сортировка, выражения, связи).
2. Не даёт возможности напрямую добавлять/обновлять/удалять пользователей — для этого служит класс CUser.
3. Имеет удобные предопределённые поля-выражения (например, IS_ONLINE), а также связь с другими ORM-классами (например, UserGroupTable).
4. Поддерживает расширение функционала через runtime и собственные связи (References).
5. Начиная с версии 20.0.1300 требует отправки данных форм авторизации/регистрации только методом POST.

Если вы разрабатываете модули или проекты на D7, работа с UserTable может значительно упростить получение нужных данных о пользователях, фильтрацию и объединение (join) с другими данными. При этом «традиционные» операции (добавление, редактирование, удаление, авторизация и регистрация) работают через классическую API CUser и формы с POST-запросами.

Используйте этот функционал рационально, и вы сможете эффективно строить сложные выборки, повышать производительность и гибкость ваших решений на 1С-Битрикс!