Функция cot_fillGroupsForUser в Cotonti

Описание функции cot_fillGroupsForUser
Функция предназначена для проверки и заполнения массива данных пользователя его ID групп. Если в массиве данных пользователя отсутствуют группы, они будут извлечены из базы данных. Также производится проверка на бан пользователя, и если срок блокировки истек, то данные о блокировке и основной группе обновляются.

Код функции

/**
 * Function validates and fills, if necessary, user data array with the his groups IDs.
 * If passed user data array does not contain data about user groups, they will be retrieved from the database.
 *
 * When using this function in a loop, it is recommended to pass all the necessary data so as not to make a lot
 * of queries to the database
 *
 * @param array{user_id: int, user_maingrp?: int, groups?: list<int>, user_banexpire?: int} $user
 * @return void
 */
function cot_fillGroupsForUser(&$user)
{
    if (empty($user['user_id'])) {
        return;
    }

    if (!array_key_exists('user_maingrp', $user) || !array_key_exists('user_banexpire', $user)) {
        $result = Cot::$db->query(
            'SELECT user_maingrp, user_banexpire FROM ' . Cot::$db->users . ' WHERE user_id = ? LIMIT 1',
            $user['user_id']
        )->fetch();
        if (!$result) {
            return;
        }
        $user['user_maingrp'] = $result['user_maingrp'];
        $user['user_banexpire'] = $result['user_banexpire'];
    }

    $user['user_maingrp'] = (int) $user['user_maingrp'];
    $user['user_banexpire'] = (int) $user['user_banexpire'];

    if (!array_key_exists('groups', $user)) {
        $user['groups'] = cot_getUserGroupIds($user['user_id'], $user['user_maingrp']);
    }

    if (
        in_array(COT_GROUP_BANNED, $user['groups'], true)
        && $user['user_banexpire'] > 0
        && Cot::$sys['now'] > $user['user_banexpire']
    ) {
        $update = ['user_banexpire' => 0];
        if ($user['user_maingrp'] === COT_GROUP_BANNED) {
            $update['user_maingrp'] = COT_GROUP_MEMBERS;
            $user['user_maingrp'] = COT_GROUP_MEMBERS;
        }
        Cot::$db->update(Cot::$db->users, $update, 'user_id = :userId', ['userId' => $user['user_id']]);
        Cot::$db->delete(
            Cot::$db->groups_users,
            'gru_userid = :userId AND gru_groupid = ' . COT_GROUP_BANNED,
            ['userId' => $user['user_id']]
        );
        $user['groups'] = array_diff($user['groups'], [COT_GROUP_BANNED]);
    }

    /* === Hook === */
    foreach (cot_getextplugins('users.fillGroups') as $pl) {
        include $pl;
    }
    /* ===== */
}

Подробное описание каждого шага функции
Проверка наличия ID пользователя:

if (empty($user['user_id'])) {
    return;
}

Что проверяется?: Проверяется, что в переданном массиве данных пользователя присутствует ключ user_id. Если его нет, то функция завершается без дальнейших действий.

Извлечение основной группы и даты истечения бана:

if (!array_key_exists('user_maingrp', $user) || !array_key_exists('user_banexpire', $user)) {
    $result = Cot::$db->query(
        'SELECT user_maingrp, user_banexpire FROM ' . Cot::$db->users . ' WHERE user_id = ? LIMIT 1',
        $user['user_id']
    )->fetch();
    if (!$result) {
        return;
    }
    $user['user_maingrp'] = $result['user_maingrp'];
    $user['user_banexpire'] = $result['user_banexpire'];
}

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

Приведение данных к целым числам:

$user['user_maingrp'] = (int) $user['user_maingrp'];
$user['user_banexpire'] = (int) $user['user_banexpire'];

Что проверяется?: Преобразование значений user_maingrp и user_banexpire в целые числа для предотвращения возможных ошибок при дальнейших операциях.
Заполнение данных о группах пользователя, если они отсутствуют:

if (!array_key_exists('groups', $user)) {
    $user['groups'] = cot_getUserGroupIds($user['user_id'], $user['user_maingrp']);
}

Что проверяется?: Если в массиве данных пользователя нет ключа groups, то вызывается функция cot_getUserGroupIds, которая извлекает все группы пользователя, включая основную группу.

Проверка на бан пользователя и обновление данных:

if (
    in_array(COT_GROUP_BANNED, $user['groups'], true)
    && $user['user_banexpire'] > 0
    && Cot::$sys['now'] > $user['user_banexpire']
) {
    $update = ['user_banexpire' => 0];
    if ($user['user_maingrp'] === COT_GROUP_BANNED) {
        $update['user_maingrp'] = COT_GROUP_MEMBERS;
        $user['user_maingrp'] = COT_GROUP_MEMBERS;
    }
    Cot::$db->update(Cot::$db->users, $update, 'user_id = :userId', ['userId' => $user['user_id']]);
    Cot::$db->delete(
        Cot::$db->groups_users,
        'gru_userid = :userId AND gru_groupid = ' . COT_GROUP_BANNED,
        ['userId' => $user['user_id']]
    );
    $user['groups'] = array_diff($user['groups'], [COT_GROUP_BANNED]);
}

Что проверяется?: Если пользователь состоит в группе "Забаненные" (COT_GROUP_BANNED), и его бан истек (проверка по полю user_banexpire), то его данные обновляются:
Устанавливается поле user_banexpire в 0 (удаляется блокировка).
Если основная группа пользователя была "Забаненные", то она изменяется на "Члены" (COT_GROUP_MEMBERS).
Удаляется запись о бане из таблицы groups_users.
Обновленный список групп пользователя очищается от группы "Забаненные".
Хуки для плагинов:

foreach (cot_getextplugins('users.fillGroups') as $pl) {
    include $pl;
}

Что делается?:

Этот блок позволяет подключить плагины для дополнительной обработки. Все плагины, зарегистрированные для хука users.fillGroups, будут выполнены.

Список супер глобальных переменных:

Cot::$db: Это объект базы данных, используемый для выполнения запросов к базе данных. Он управляет всеми операциями с базой данных, такими как выборки, вставки и обновления данных.
Cot::$sys['now']: Текущая временная метка (время в секундах от начала эпохи Unix), используемая для различных временных проверок, например, для проверки истечения срока бана.
COT_GROUP_BANNED: Константа, которая содержит идентификатор группы забаненных пользователей.
COT_GROUP_MEMBERS: Константа, которая содержит идентификатор группы "Члены".
$user: Массив, содержащий данные о пользователе, такие как его ID, основная группа, дата истечения бана и группы, в которых он состоит.