Плагин «usradmintools» для Cotonti Siena: полный обзор и руководство

Версия: 3.0.0
Автор: webitproff
Совместимость: Cotonti Siena 0.9.26, PHP 8.4+, MySQL 8.0+
Лицензия: BSD

Мой плагин, это почти с нуля пересобранный старенький "usermanager", последняя версия которого лежит на github

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

Оглавление

1. Введение
2. Основные возможности плагина
3. Установка и первоначальная настройка
4. Архитектура и структура файлов
5. Основной интерфейс: управление пользователями
   • 5.1. Список пользователей
   • 5.2. Поиск и фильтрация
   • 5.3. Сортировка и её особенности
   • 5.4. Массовые операции
   • 5.5. Создание нового пользователя
6. Редактирование пользователя
   • 6.1. Основные данные
   • 6.2. Дополнительные поля
   • 6.3. Управление группами
   • 6.4. Временный доступ
   • 6.5. Удаление пользователя
7. Интеграция с другими модулями и плагинами
8. Технические детали реализации
   • 8.1. Обработка параметров запроса
   • 8.2. Построение SQL-запросов с фильтрами и сортировкой
   • 8.3. Генерация интерфейса сортировки и направления
   • 8.4. Работа с сообщениями и валидацией
9. Шаблоны и их кастомизация
10. Часто задаваемые вопросы (FAQ)
11. Заключение

1. Введение

Плагин usradmintools (User Administration Tools) представляет собой мощное расширение для административной панели Cotonti, значительно расширяющее стандартные возможности управления пользователями. В то время как встроенный модуль Users предоставляет базовый функционал просмотра и редактирования профилей, usradmintools добавляет расширенные фильтры, гибкую сортировку, массовые операции, поддержку временного доступа и удобный интерфейс, ориентированный на современные стандарты администрирования.

Плагин разработан с учётом последних требований безопасности и производительности, полностью совместим с PHP 8.4+ и использует все преимущества Cotonti Siena. Он интегрируется с популярными плагинами экосистемы Cotonti, такими как payments, paypro, verification, pm, forums, pfs и другими, что делает его универсальным инструментом для веб-мастеров и администраторов сообществ любого масштаба.

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

2. Основные возможности плагина

• Просмотр списка пользователей с постраничной навигацией, настраиваемым количеством записей на странице.
• Расширенная фильтрация по:
  • Стране проживания;
  • Основной группе;
  • Любой из групп, в которых состоит пользователь;
  • Поиску по логину, email или дополнительным полям (имя, фамилия и т.д.).
• Гибкая сортировка по любому полю таблицы users, включая дополнительные поля, с возможностью изменения направления (по возрастанию / убыванию).
• Массовое удаление выбранных пользователей.
• Создание нового пользователя через модальное окно с предустановленными значениями (имя, email, пароль, группа и т.д.).
• Редактирование профиля пользователя с доступом ко всем полям, включая дополнительные, смена пароля, управление группами, датами регистрации и последнего входа, IP-адресом, настройками уведомлений.
• Управление временным доступом (Temporary Group Access) — возможность задать пользователю временное членство в определённой группе с указанием срока действия.
• Интеграция с модулями:
  • pm — отображение статуса уведомлений о личных сообщениях, возможность их редактирования.
  • payments — отображение текущего баланса пользователя.
  • paypro — управление Premium-статусом и датой его истечения.
  • verification — управление статусом верификации.
  • pfs — удаление всех файлов пользователя при его удалении.
  • forums, page, comments — автоматическое обновление имени автора при смене логина.
• Поддержка дополнительных полей Cotonti — все экстраполя автоматически подхватываются и выводятся в формах создания/редактирования и в списке.
• Безопасность:
  • Проверка прав администратора на каждом шаге.
  • Защита от понижения главного администратора (ID=1).
  • Использование встроенных механизмов Cotonti для защиты от CSRF (cot_xg(), cot_check_xg()).
  • Экранирование вывода и валидация входных данных.
• Локализация — поддержка языковых файлов Cotonti для всех надписей и сообщений.

3. Установка и первоначальная настройка

3.1. Требования

• Cotonti Siena 0.9.26 или новее (рекомендуется последняя стабильная версия).
• PHP 8.4 или выше с расширениями mbstring, pdo_mysql.
• MySQL 8.0+ (также поддерживается MariaDB 10.4+).

3.2. Установка

1. Скачайте архив плагина с официального репозитория или сайта разработчика.
2. Распакуйте содержимое папки usradmintools в директорию plugins/ вашего сайта Cotonti.
3. Перейдите в административную панель → «Расширения» → «Плагины».
4. Найдите в списке «usradmintools» и нажмите «Установить».
5. После успешной установки плагин появится в разделе «Инструменты» (/admin/other?p=usradmintools).

3.3. Настройки

Плагин не имеет отдельной страницы конфигурации в админке. Все параметры задаются через конфигурационный файл Cotonti (datas/config.php) или через файл plugins/usradmintools/inc/usradmintools.resources.php. Основные настраиваемые значения:

php

// usradmintools_defaultlevel — ID группы по умолчанию для новых пользователей (по умолчанию COT_GROUP_MEMBERS = 4)
// usradmintools_defaultname — предлагаемое имя пользователя при создании
// usradmintools_defaultemail — email по умолчанию
// usradmintools_defaultlogcount — начальное значение счётчика входов
// usradmintools_defaultpass — пароль по умолчанию (рекомендуется оставить пустым для генерации)
// usradmintools_defaultsign — подпись по умолчанию

Эти значения можно переопределить в секции [plugin][usradmintools] глобального конфига.

4. Архитектура и структура файлов

Плагин построен в соответствии со стандартами Cotonti и использует несколько ключевых файлов:

text

plugins/usradmintools/
├── usradmintools.admin.php # Точка входа для административной части (hook tools)
├── usradmintools.admin.tpl # Основной шаблон списка пользователей
├── inc/
│ ├── usradmintools.resources.php # Ресурсы: функции, R-массивы, хелперы
│ ├── usradmintools.edit.php # Логика редактирования пользователя
│ ├── usradmintools.edit.tpl # Шаблон формы редактирования
│ ├── usradmintools.access.php # Управление временным доступом
│ ├── usradmintools.create.php # Создание пользователя
│ ├── usradmintools.delete.php # Удаление пользователя (одиночное/массовое)
│ └── usradmintools.profile.php # Просмотр собственного профиля администратора
└── lang/
 ├── usradmintools.en.lang.php
 └── usradmintools.ru.lang.php # Языковые файлы

Главный файл usradmintools.admin.php отвечает за маршрутизацию действий (a=edit, a=access, a=create и т.д.) и отображение основного списка. При вызове с параметром действия управление передаётся соответствующему подключаемому файлу из inc/. Такой подход позволяет разделить логику и упрощает поддержку кода.

5. Основной интерфейс: управление пользователями

При переходе по адресу /admin/other?p=usradmintools администратор попадает на главную страницу плагина — список всех пользователей.

5.1. Список пользователей

Список представлен в виде таблицы со следующими колонками:

• Чекбокс для массовых операций.
• PM (иконка личного сообщения, если активен модуль pm).
• TGA — статус временного доступа (активен/неактивен).
• ID пользователя.
• Имя пользователя с аватаром и ссылкой на профиль.
• Баланс (если активен payments) и Premium-статус (если активен paypro).
• Email.
• Основная группа.
• Уровень группы (звёздочки).
• Страна с флагом.
• Дата регистрации и последнего входа.
• Кнопки «Редактировать» и «Удалить».

Каждая строка формируется циклом UM_ROW в шаблоне, данные подставляются через вызов cot_generate_usertags(), что позволяет использовать все стандартные теги пользователя Cotonti.

5.2. Поиск и фильтрация

Панель фильтров расположена над таблицей и содержит следующие элементы:

• Страна — выпадающий список всех стран, включая пункт «Не указано».
• Основная группа — фильтр по user_maingrp.
• Любая группа — фильтр по участию в любой группе (таблица cot_groups_users).
• Поиск по имени — текстовое поле sq для поиска по user_name, user_email или дополнительным полям first_name, last_name, middle_name.

Все фильтры, кроме текстового поиска, реализованы через <select> с классом filter-submit. При изменении значения JavaScript-код автоматически отправляет форму методом GET, сохраняя все текущие параметры в URL. Это обеспечивает мгновенное применение фильтров без необходимости нажимать кнопку «Поиск».

Кнопка «Сброс» (UM_RESET_URL) возвращает к исходному состоянию без фильтров.

5.3. Сортировка и её особенности

Одной из ключевых функций плагина является гибкая сортировка списка пользователей. В стандартном модуле Users сортировка возможна по ограниченному набору полей, при этом параметр s (sort) конфликтует с системным параметром админки. В usradmintools эта проблема решена путём переименования GET-параметра в sort. Это позволило избежать ошибки 404 при использовании сортировки в админ-панели.

Доступные поля сортировки:

• id — ID пользователя;
• name — логин;
• maingrp — основная группа;
• country — страна;
• occupation, location, timezone, birthdate, gender;
• regdate, lastlog, logcount, postcount;
• grplevel, grpname — уровень и название группы (через JOIN);
• все дополнительные поля из таблицы cot_users.

Поле сортировки выбирается через выпадающий список UM_FILTERS_SORT. Рядом расположена иконка-ссылка UM_FILTERS_SORT_WAY, позволяющая переключить направление сортировки (asc / desc). При клике на иконку формируется URL с сохранением всех текущих фильтров и переключением параметра w. Активное направление подсвечивается соответствующей иконкой.

Техническая реализация ссылки направления:

php

$sortWayParams = $users_url_path;
if ($sort !== $defaultSortField) {
 $sortWayParams['sort'] = $sort;
} else {
 unset($sortWayParams['sort']);
}
$currentWay = $w ?? $defaultSortWay;
if ($currentWay === 'asc') {
 $sortWayParams['w'] = 'desc';
 $sortWayIcon = Cot::$R['icon_order_asc'];
} else {
 $sortWayParams['w'] = 'asc';
 $sortWayIcon = Cot::$R['icon_order_desc'];
}
$sortWayUrl = cot_url('admin', $sortWayParams);

Этот подход гарантирует, что ссылка всегда содержит правильный набор параметров и корректно обрабатывается роутером Cotonti.

5.4. Массовые операции

Под таблицей расположена кнопка «Удалить выбранных», отправляющая форму на адрес a=delete_selected. В PHP-обработчике массив выбранных ID передаётся через $_POST['s'], после проверки CSRF-токена для каждого ID вызывается процедура удаления (файл inc/usradmintools.delete.php). Удаление включает:

• Удаление записи из cot_users.
• Удаление связей с группами (cot_groups_users).
• Удаление связанных файлов дополнительных полей.
• При установленной опции — удаление всех файлов пользователя из PFS.
• Логирование действия.

5.5. Создание нового пользователя

Кнопка «Создать пользователя» открывает модальное окно с формой. В ней предзаполнены значения из настроек плагина (имя, email, пароль, счётчик входов). Администратор может изменить эти поля, выбрать основную группу и дополнительные группы, а также заполнить обязательные дополнительные поля (если они помечены как required). После отправки формы данные обрабатываются в inc/usradmintools.create.php: проверяется уникальность имени и email, хешируется пароль, создаётся запись в cot_users и связи с группами.

6. Редактирование пользователя

При клике на кнопку «Редактировать» (или по ссылке из имени пользователя) открывается страница /admin/other?p=usradmintools&a=edit&id=XXX. Интерфейс редактирования спроектирован с учётом удобства администратора и предоставляет доступ к полному набору полей пользователя.

6.1. Основные данные

В верхней части формы отображаются ID пользователя и поле для изменения логина. Здесь же можно увидеть аватар (если активен плагин userimages) и ссылку на публичный профиль.

Поля, доступные для редактирования:

• Новый пароль — при вводе пароль будет изменён, иначе остаётся прежним.
• Email — с проверкой уникальности.
• Скрывать email — радиокнопки Да/Нет.
• Подпись — текстовое поле (с возможностью использования мини-редактора).
• Пол, Дата рождения (выпадающие списки), Часовой пояс.
• Дата регистрации, Дата последнего входа, Счётчик входов, Последний IP (с ссылкой на поиск по IP).
• Основная группа и членство в дополнительных группах (флажки).
• Страна, Язык, Тема оформления.
• Удалить пользователя — радиокнопки и опция удаления файлов PFS.

6.2. Дополнительные поля

Плагин автоматически подхватывает все дополнительные поля, определённые для таблицы users. Для каждого такого поля создаётся соответствующее поле ввода (тип зависит от настроек экстраполя). Вывод организован через цикл MAIN.EXTRAFLD в шаблоне, что позволяет динамически добавлять любое количество экстраполей без изменения кода.

Пример фрагмента шаблона:

smarty

<!-- BEGIN: EXTRAFLD -->
<div class="mb-3 row">
 <label class="col-sm-3 col-form-label">{UM_EDIT_EXTRAFLD_TITLE}:</label>
 <div class="col-sm-9">{UM_EDIT_EXTRAFLD}</div>
</div>
<!-- END: EXTRAFLD -->

В PHP-коде для каждого экстраполя выполняются:

php

$exfld_val = cot_build_extrafields('ruser' . $exfld['field_name'], $exfld, $urr['user_' . $exfld['field_name']]);
$exfld_title = cot_extrafield_title($exfld, 'user_');
$t->assign([
 'UM_EDIT_' . $uname => $exfld_val,
 'UM_EDIT_' . $uname . '_TITLE' => $exfld_title,
 'UM_EDIT_EXTRAFLD' => $exfld_val,
 'UM_EDIT_EXTRAFLD_TITLE' => $exfld_title,
]);
$t->parse('MAIN.EXTRAFLD');

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

6.3. Управление группами

Помимо основной группы, администратор может назначить пользователю любое количество дополнительных групп. Используется функция cot_build_um1_groupsms(), которая генерирует набор чекбоксов для всех групп (кроме гостей), с учётом прав текущего администратора. При сохранении плагин синхронизирует записи в cot_groups_users: добавляет недостающие и удаляет лишние. Особая защита встроена для пользователя с ID=1 — его нельзя исключить из группы суперадминистраторов или поместить в забаненные/неактивные.

6.4. Временный доступ

Ссылка «Edit temporary access» ведёт на страницу управления временным доступом (a=access). Здесь администратор может установить для пользователя временное членство в определённой группе с указанием даты начала и окончания. Эта функциональность реализована в отдельной таблице cot_usradmintools. Статус доступа отображается в основном списке в колонке «TGA».

6.5. Удаление пользователя

На странице редактирования присутствует блок «Удалить пользователя». При выборе «Да» и сохранении формы пользователь будет удалён, а администратор перенаправлен обратно к списку. При этом возможно также удалить все файлы пользователя из PFS (если модуль активен). Удаление суперадминистратора (ID=1) запрещено.

7. Интеграция с другими модулями и плагинами

Плагин спроектирован с учётом расширяемости Cotonti и активно взаимодействует со смежными расширениями.

7.1. Модуль pm

Если модуль личных сообщений активен, в списке пользователей появляется колонка с иконкой PM, а в форме редактирования — настройка уведомлений о новых сообщениях.

7.2. Плагин payments

При наличии активного модуля payments в списке и при редактировании отображается текущий баланс пользователя (функция cot_payments_getuserbalance()).

7.3. Плагин paypro

Если активен paypro, плагин добавляет:

• В список — индикатор Premium-статуса с датой окончания.
• В форму редактирования — поле для установки даты истечения Premium.

7.4. Плагин verification

В форме редактирования появляется радиокнопка «Статус верификации» (Да/Нет), позволяющая администратору вручную подтверждать пользователей.

7.5. Модуль forums, page, comments

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

7.6. Плагин pfs

При удалении пользователя с опцией «Удалить файлы PFS» плагин вызывает cot_pfs_deleteall(), очищая все загруженные пользователем файлы.

7.7. Плагин userimages

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

8. Технические детали реализации

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

8.1. Обработка параметров запроса

Все входные параметры извлекаются с помощью cot_import() с указанием ожидаемого типа и максимальной длины. Это защищает от инъекций и некорректных данных. Параметр sort (ранее s) переименован для избежания конфликта с системным параметром админки Cotonti.

8.2. Построение SQL-запросов с фильтрами и сортировкой

Сборка WHERE-условий происходит динамически на основе переданных фильтров. Используются именованные плейсхолдеры PDO для защиты от SQL-инъекций. Пример для фильтра по стране:

php

$where['country'] = "user_country = :country";
$params['country'] = $country;

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

8.3. Генерация интерфейса сортировки и направления

Как упоминалось ранее, для переключения направления сортировки используется ссылка, формируемая с сохранением всех активных фильтров. Важно отметить, что для заголовков столбцов таблицы также генерируются ссылки сортировки с помощью функции cot_rc('users_link_sort', ...). Это обеспечивает единообразный вид и поведение во всём плагине.

8.4. Работа с сообщениями и валидацией

Плагин использует стандартный механизм Cotonti для вывода сообщений: cot_error(), cot_message(), cot_display_messages(). При сохранении формы редактирования плагин сначала проверяет данные (валидация логина, email, пароля). Если ошибок нет, выполняется обновление БД и вызывается cot_message() с типом ok. Затем происходит редирект на ту же страницу, чтобы избежать повторной отправки формы. На целевой странице вызов cot_display_messages($t) извлекает сообщения из сессии и передаёт их в шаблон, где они отображаются через {FILE warnings.tpl}. Такой подход предотвращает дублирование сообщений и соответствует лучшим практикам Cotonti.

9. Шаблоны и их кастомизация

Плагин поставляется с двумя основными шаблонами:

• usradmintools.admin.tpl — список пользователей.
• usradmintools.edit.tpl — форма редактирования.

Оба шаблона построены на Bootstrap 5 (используются классы container-fluid, card, row, col, table, btn и т.д.). При необходимости их можно скопировать в папку темы оформления (themes/yourtheme/plug/usradmintools/) и адаптировать под свой дизайн.

9.1. Основные блоки шаблона списка

• UM_FILTERS_* — элементы панели фильтров.
• UM_TOP_* — заголовки столбцов таблицы с поддержкой сортировки.
• MAIN.UM_ROW — повторяющийся блок для каждой строки пользователя.
• MAIN.EXTRAFLD — блок для вывода обязательных экстраполей в модальном окне создания пользователя.

9.2. Шаблон редактирования

• UM_EDIT_* — переменные для полей формы.
• MAIN.EXTRAFLD — динамический вывод всех дополнительных полей.
• Встроенная поддержка JavaScript для всплывающих подсказок (data-bs-toggle="tooltip").

10. Часто задаваемые вопросы (FAQ)

В: Почему при сортировке возникает ошибка 404?
О: В стандартном Cotonti параметр s используется для внутренней маршрутизации админки. Плагин usradmintools переименовывает параметр сортировки в sort, что устраняет конфликт. Убедитесь, что у вас установлена последняя версия плагина.

В: Как добавить новое поле в список пользователей?
О: Если это дополнительное поле, оно автоматически появится в списке при условии, что оно не входит в чёрный список ($usersSortFieldsBlacklist). Для кастомных полей можно расширить массив $users_sort_tags в файле usradmintools.admin.php.

В: Можно ли изменить группу по умолчанию для новых пользователей?
О: Да, значение хранится в Cot::$cfg['plugin']['usradmintools']['usradmintools_defaultlevel']. Его можно переопределить в config.php.

В: Плагин не выводит сообщения об успешном обновлении профиля.
О: Убедитесь, что в вашем шаблоне присутствует строка {FILE "{PHP.cfg.themes_dir}/{PHP.cfg.defaulttheme}/warnings.tpl"} и вызов cot_display_messages($t) расположен до парсинга шаблона. В актуальной версии плагина это реализовано корректно.

В: Как отключить автоматическую отправку формы при изменении фильтров?
О: Удалите класс filter-submit у соответствующих select в PHP-коде или переопределите шаблон.

11. Заключение

Плагин usradmintools — это комплексное решение для администрирования пользователей в Cotonti, объединяющее удобный интерфейс, продвинутые фильтры и сортировку, интеграцию с популярными модулями и высокую степень безопасности. Его модульная архитектура и следование стандартам Cotonti позволяют легко расширять функциональность и адаптировать под конкретные проекты.

Благодаря детальной документации и открытому исходному коду плагин может служить как готовым инструментом для повседневной работы, так и основой для обучения разработке расширений под Cotonti. Мы надеемся, что данное руководство поможет вам максимально эффективно использовать все возможности usradmintools.