Функции пользователей Albireo CMS

checkUserAccess findUser getUser loginUser noUserAccess noUserAccessFull

Функция checkUserAccess

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

Сигнатура

function checkUserAccess(string|array $level): bool

Аргументы

string|array $level: Один или несколько уровней доступа для проверки. Может быть передан как массив (['admin', 'editor']) или как строка, разделенная запятыми ('admin,editor').

Результат

Возвращает булево значение (bool):

true — если пользователь авторизован и имеет хотя бы один из требуемых уровней доступа.
false — если пользователь не авторизован, у него не определены уровни доступа, или у него нет ни одного из требуемых уровней.

Примеры использования

Пример 1: Защита административной панели

Классический пример, где доступ разрешен только пользователям с уровнем 'admin'.

if (!checkUserAccess('admin')) {
    // Если у пользователя нет прав администратора, прекращаем выполнение
    exit('Доступ запрещен.');
}

// Код, который будет выполнен только для администраторов
echo 'Добро пожаловать в панель управления!';

Пример 2: Доступ для нескольких ролей

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

// Доступ разрешен, если у пользователя есть уровень 'editor' ИЛИ 'author'
if (checkUserAccess('editor,author')) {
    echo '<a href="/new-post.php">Создать новую статью</a>';
}

Пример 3: Использование с массивом в качестве аргумента

Тот же пример, что и выше, но с использованием массива, что может быть удобнее при программном формировании списка ролей.

$requiredLevels = ['editor', 'author'];

if (checkUserAccess($requiredLevels)) {
    echo 'У вас есть права на создание контента.';
}

Примечания

Логика проверки: Доступ предоставляется, если у пользователя есть хотя бы один из требуемых уровней, а не все сразу (логическое "ИЛИ").
Гибкость форматов: Функция самостоятельно обрабатывает как строковые, так и массивные представления уровней доступа, как для требуемых уровней, так и для уровней самого пользователя.

Функция findUser

Функция findUser ищет пользователя по его логину. Особенностью является двухуровневая система поиска: сначала данные ищутся в конфигурационном файле config/users.php (что имеет приоритет), и только если пользователь там не найден, происходит обращение к базе данных. Результаты поиска кешируются в рамках одного запроса для предотвращения повторных обращений к источникам данных.

Сигнатура

function findUser(string $login): array|false

Аргументы

string $login: Логин пользователя, данные которого необходимо найти.

Результат

Возвращает ассоциативный массив (array) с данными пользователя или false, если пользователь не найден ни в конфигурационном файле, ни в базе данных.

Примеры использования

Пример 1: Стандартный поиск пользователя

$login = 'testuser';
$userData = findUser($login);

if ($userData) {
    echo "Пользователь '{$userData['login']}' найден. Имя: {$userData['name']}.";
} else {
    echo "Пользователь с логином '{$login}' не найден.";
}

Примечания

Кеширование: Результат поиска кешируется в статической переменной. Это означает, что при повторном вызове findUser('some_login') в рамках одного HTTP-запроса, обращение к файлу или базе данных производиться не будет, а будет возвращен результат из кеша.
Приоритет: Данные из конфигурационного файла users.php всегда имеют приоритет над данными из базы данных.

Функция getUser

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

Сигнатура

function getUser(string|bool $loginField = ''): array|false|string

Аргументы

string|bool $loginField (необязательный)

Определяет режим работы функции:

Пустое значение или false (по умолчанию): Запускает полный режим проверки. Функция ищет в сессии $_SESSION['login'] и $_SESSION['hash'], находит пользователя через findUser(), проверяет срок действия учетной записи и сверяет хэши сессии и пользователя.
Непустая строка (например, 'login'): Запускает быстрый режим проверки. Функция просто возвращает значение из $_SESSION[$loginField]. Это полезно, когда нужно только узнать, существует ли сессия, без детальной проверки.

Результат

Возвращаемое значение зависит от режима работы:

В полном режиме:
- array — ассоциативный массив с данными пользователя, если все проверки прошли успешно.
- false — если пользователь не аутентифицирован, его сессия недействительна или учетная запись истекла.
В быстром режиме:
- string — значение из сессии по указанному ключу (например, логин пользователя). Если ключ в сессии отсутствует, вернется пустая строка ''.

Примеры использования

Пример 1: Быстрая проверка для отображения элементов интерфейса

В шаблоне можно быстро проверить, залогинен ли пользователь, чтобы показать ему либо кнопку входа, либо кнопку выхода.

<?php if (getUser('login')): ?>
    <a href="/logout">Выйти</a>
<?php else: ?>
    <a href="/login">Войти</a>
<?php endif; ?>

Пример 2: Полное получение данных для защищенной страницы

На страницах, требующих авторизации, необходимо выполнять полную проверку.

<?php
// Получаем данные пользователя с полной проверкой
$user = getUser();

if (!$user) {
    // Если пользователь не авторизован, перенаправляем на страницу входа
    header('Location: /login.php');
    exit;
}

// Если мы здесь, значит, пользователь авторизован и его данные есть в $user
echo '<h1>Личный кабинет</h1>';
echo '<p>Здравствуйте, ' . htmlspecialchars($user['name']) . '!</p>';
?>

Функция loginUser

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

Сигнатура

function loginUser(string $login, string $password): bool

Аргументы

string $login: Логин пользователя, как правило, полученный из POST-запроса формы входа.
string $password: Пароль пользователя в открытом виде, полученный из формы входа.

Результат

Возвращает булево значение (bool):

true — если все проверки пройдены, и пользовательская сессия успешно создана.
false — в случае любой ошибки: пользователь не найден, срок действия учетной записи истек или пароль неверный.

Примеры использования

Пример обработки формы входа

Это типичный сценарий использования функции в файле-обработчике формы логина.

// login_handler.php

$error_message = '';

// Проверяем, были ли отправлены данные формы
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $login = $_POST['login'] ?? '';
    $password = $_POST['password'] ?? '';

    if (loginUser($login, $password)) {
        // Вход успешен, перенаправляем в личный кабинет
        header('Location: /account.php');
        exit;
    } else {
        // Ошибка входа
        $error_message = 'Неверный логин, пароль или срок действия вашей учетной записи истек.';
    }
}

// Если есть ошибка, можно отобразить ее в форме
if ($error_message) {
    echo '<div class="error">' . $error_message . '</div>';
}

Примечания

Безопасность пароля: Функция использует современный и безопасный подход password_verify() для проверки хэша пароля.
Системный "перец" (Pepper): Для повышения безопасности к паролю перед хэшированием добавляется не только логин, но и системный секретный ключ (secretKey). Это защищает хэши даже в случае утечки базы данных.
Данные сессии: При успешном входе в сессию записываются login, hash, nickname и level. Хэш, сохраненный в сессии, используется функцией getUser() для проверки валидности сессии при последующих запросах.

Функция noUserAccess

Функция noUserAccess является вспомогательным инструментом для реализации контроля доступа. Её основная задача — упростить код, объединив проверку флага доступа и вывод сообщения/шаблона об ошибке в один вызов. Она идеально подходит для использования в "защитных условиях" в начале скрипта или функции.

Сигнатура

function noUserAccess(string $snippet = '', string $message = '', string $extras = ''): bool

Аргументы

Все аргументы являются необязательными и используются только в том случае, если доступ запрещен.

string $snippet: Имя файла-сниппета (без расширения), который будет выведен с помощью функции snippet().
string $message: Произвольная строка (может содержать HTML), которая будет выведена напрямую.
string $extras: Имя файла-шаблона, который будет подключен с помощью функции extras().

Результат

Возвращает булево значение (bool), которое следует интерпретировать так:

true — если доступ запрещен (getVal('userAccess') вернул falsy-значение).
false — если доступ разрешен.

Примеры использования

Пример 1: Простая блокировка доступа

Самый частый сценарий: если у пользователя нет доступа, просто прекратить дальнейшее выполнение кода страницы.

// В начале файла admin-panel.php
if (noUserAccess()) {
    // Можно также использовать goto, return или die()
    exit; 
}

// ... остальной код страницы, который увидят только администраторы ...

Пример 2: Вывод сообщения об ошибке

Вместо "белого экрана" можно показать пользователю информативное сообщение.

if (noUserAccess(message: '<h1>403 Forbidden</h1><p>У вас нет прав для просмотра этой страницы.</p>')) {
    return; // Прекращаем выполнение шаблона
}

Пример 3: Вывод через шаблон (сниппет или extras)

Для более сложного вывода.

// Использование extras-файла
if (noUserAccess(extras: 'access-denied.php')) return;

if (noUserAccess(extras: 'not-access-1.php')) return;

// Использование сниппета (нужно его предварительно создать)
if (noUserAccess(snippet: 'access-denied-message')) return;

Функция noUserAccessFull

Анализирует данные текущей страницы на наличие флага no-user-access: +. Если флаг установлен и у текущего пользователя отсутствуют права доступа, функция блокирует отображение основного контента, подключая специальный файл-заглушку (_no_user_access.php) или выводя стандартное сообщение об ошибке. Используется в layout-файлах шаблона для полной блокировки страницы в случае ограничений пользователя.

Сигнатура

function noUserAccessFull(): bool

Аргументы

Данная функция не принимает аргументов.

Результат

Логическое значение (bool):

true — доступ ограничен, контент заглушки выведен на экран.
false — доступ разрешен или флаг ограничения не установлен.

Примеры использования

// Использование в контроллере или ядре шаблона
if (noUserAccessFull()) {
    // Если функция вернула true, значит сообщение о закрытом доступе уже выведено
    return; 
}