"usradmintools" Plugin for Cotonti Siena: Complete Overview and Guide

Version: 3.0.0
Author: webitproff
Compatibility: Cotonti Siena 0.9.26, PHP 8.4+, MySQL 8.0+
License: BSD

My plugin is an almost from-scratch rebuild of the old "usermanager", whose latest version can be found on GitHub.

but with differential logic and templates, a search and filter form created from scratch, sorting by all fields, dynamic loading of extra fields when editing a user (no need to manually write each field in templates). It is up-to-date for the current version of Cotonti.
I haven't decided yet whether to release it "paid or free" – a lot of work has been done and much more is planned for the intended functionality.
It is needed by those who really have a thousand or more users, for example in an online store. Anyone who wants to join in supporting development is welcome – your donations mean release, support, updates – free of charge!

Table of Contents

1. Introduction
2. Main Features of the Plugin
3. Installation and Initial Setup
4. Architecture and File Structure
5. Main Interface: User Management
   • 5.1. User List
   • 5.2. Search and Filtering
   • 5.3. Sorting and Its Peculiarities
   • 5.4. Bulk Operations
   • 5.5. Creating a New User
6. Editing a User
   • 6.1. Basic Data
   • 6.2. Extra Fields
   • 6.3. Group Management
   • 6.4. Temporary Access
   • 6.5. Deleting a User
7. Integration with Other Modules and Plugins
8. Technical Implementation Details
   • 8.1. Request Parameter Handling
   • 8.2. Building SQL Queries with Filters and Sorting
   • 8.3. Generating the Sorting Interface and Direction
   • 8.4. Working with Messages and Validation
9. Templates and Customization
10. Frequently Asked Questions (FAQ)
11. Conclusion

1. Introduction

The usradmintools (User Administration Tools) plugin is a powerful extension for the Cotonti administrative panel, significantly expanding the standard user management capabilities. While the built-in Users module provides basic profile viewing and editing functionality, usradmintools adds advanced filters, flexible sorting, bulk operations, temporary access support, and a user-friendly interface aligned with modern administration standards.

The plugin is developed with the latest security and performance requirements in mind, is fully compatible with PHP 8.4+, and leverages all the advantages of Cotonti Siena. It integrates with popular plugins from the Cotonti ecosystem, such as payments, paypro, verification, pm, forums, pfs, and others, making it a versatile tool for webmasters and community administrators of any scale.

In this article, we will examine in detail all aspects of the plugin's operation: from installation to fine-tuning templates and writing custom extensions based on it. The guide is intended for both novice Cotonti users and experienced developers who want to understand the inner workings of the plugin.

2. Main Features of the Plugin

• User list view with pagination and configurable items per page.
• Advanced filtering by:
  • Country of residence;
  • Main group;
  • Any group the user belongs to;
  • Search by login, email, or extra fields (first name, last name, etc.).
• Flexible sorting by any field in the users table, including extra fields, with the ability to change direction (ascending / descending).
• Bulk deletion of selected users.
• Creating a new user via a modal window with preset values (name, email, password, group, etc.).
• Editing a user profile with access to all fields, including extra fields, password change, group management, registration and last login dates, IP address, notification settings.
• Temporary Group Access (TGA) management — the ability to assign a user temporary membership in a specific group with a defined validity period.
• Integration with modules:
  • pm — displaying private message notification status and the ability to edit them.
  • payments — displaying the user's current balance.
  • paypro — managing Premium status and its expiration date.
  • verification — managing verification status.
  • pfs — deleting all user files upon user deletion.
  • forums, page, comments — automatically updating the author name when the login is changed.
• Support for Cotonti extra fields — all extra fields are automatically detected and displayed in creation/editing forms and in the list.
• Security:
  • Administrator permission checks at every step.
  • Protection against demoting the main administrator (ID=1).
  • Use of built-in Cotonti mechanisms for CSRF protection (cot_xg(), cot_check_xg()).
  • Output escaping and input validation.
• Localization — support for Cotonti language files for all labels and messages.

3. Installation and Initial Setup

3.1. Requirements

• Cotonti Siena 0.9.26 or newer (the latest stable version is recommended).
• PHP 8.4 or higher with mbstring, pdo_mysql extensions.
• MySQL 8.0+ (MariaDB 10.4+ is also supported).

3.2. Installation

1. Download the plugin archive from the official repository or the developer's website.
2. Extract the contents of the usradmintools folder into the plugins/ directory of your Cotonti site.
3. Go to the Administration Panel → "Extensions" → "Plugins".
4. Find "usradmintools" in the list and click "Install".
5. After successful installation, the plugin will appear in the "Tools" section (/admin/other?p=usradmintools).

3.3. Configuration

The plugin does not have a separate configuration page in the admin panel. All settings are defined through the Cotonti configuration file (datas/config.php) or via the file plugins/usradmintools/inc/usradmintools.resources.php. The main configurable values are:

php

// usradmintools_defaultlevel — default group ID for new users (defaults to COT_GROUP_MEMBERS = 4)
// usradmintools_defaultname — suggested username when creating
// usradmintools_defaultemail — default email
// usradmintools_defaultlogcount — initial login counter value
// usradmintools_defaultpass — default password (recommended to leave empty for generation)
// usradmintools_defaultsign — default signature

These values can be overridden in the [plugin][usradmintools] section of the global config.

4. Architecture and File Structure

The plugin is built according to Cotonti standards and uses several key files:

text

plugins/usradmintools/
├── usradmintools.admin.php # Entry point for the administrative part (hook tools)
├── usradmintools.admin.tpl # Main user list template
├── inc/
│ ├── usradmintools.resources.php # Resources: functions, R-arrays, helpers
│ ├── usradmintools.edit.php # User editing logic
│ ├── usradmintools.edit.tpl # Editing form template
│ ├── usradmintools.access.php # Temporary access management
│ ├── usradmintools.create.php # User creation
│ ├── usradmintools.delete.php # User deletion (single/bulk)
│ └── usradmintools.profile.php # Viewing administrator's own profile
└── lang/
 ├── usradmintools.en.lang.php
 └── usradmintools.ru.lang.php # Language files

The main file usradmintools.admin.php is responsible for routing actions (a=edit, a=access, a=create, etc.) and displaying the main list. When called with an action parameter, control is passed to the corresponding included file from inc/. This approach separates logic and simplifies code maintenance.

5. Main Interface: User Management

When navigating to /admin/other?p=usradmintools, the administrator lands on the plugin's main page – a list of all users.

5.1. User List

The list is presented as a table with the following columns:

• Checkbox for bulk operations.
• PM (private message icon, if the pm module is active).
• TGA — temporary access status (active/inactive).
• User ID.
• Username with avatar and link to profile.
• Balance (if payments is active) and Premium status (if paypro is active).
• Email.
• Main group.
• Group level (stars).
• Country with flag.
• Registration date and last login.
• "Edit" and "Delete" buttons.

Each row is generated by the UM_ROW loop in the template, with data populated via a call to cot_generate_usertags(), which allows the use of all standard Cotonti user tags.

5.2. Search and Filtering

The filter panel is located above the table and contains the following elements:

• Country — a dropdown list of all countries, including "Not specified".
• Main group — filter by user_maingrp.
• Any group — filter by membership in any group (cot_groups_users table).
• Search by name — text field sq for searching by user_name, user_email, or extra fields first_name, last_name, middle_name.

All filters, except the text search, are implemented via <select> elements with the class filter-submit. When the value changes, JavaScript code automatically submits the form via GET, preserving all current parameters in the URL. This ensures instant application of filters without needing to click a "Search" button.

The "Reset" button (UM_RESET_URL) returns to the initial state without filters.

5.3. Sorting and Its Peculiarities

One of the key features of the plugin is flexible sorting of the user list. In the standard Users module, sorting is possible on a limited set of fields, and the s (sort) parameter conflicts with the system parameter of the admin panel. In usradmintools, this problem is solved by renaming the GET parameter to sort. This avoids a 404 error when using sorting in the admin panel.

Available sorting fields:

• id — User ID;
• name — login;
• maingrp — main group;
• country — country;
• occupation, location, timezone, birthdate, gender;
• regdate, lastlog, logcount, postcount;
• grplevel, grpname — group level and name (via JOIN);
• all extra fields from the cot_users table.

The sorting field is selected via the UM_FILTERS_SORT dropdown. Next to it is an icon-link UM_FILTERS_SORT_WAY, which allows toggling the sorting direction (asc / desc). Clicking the icon generates a URL that preserves all current filters and toggles the w parameter. The active direction is highlighted with a corresponding icon.

Technical implementation of the direction link:

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);

This approach ensures that the link always contains the correct set of parameters and is properly handled by Cotonti's router.

5.4. Bulk Operations

Below the table, there is a "Delete selected" button, which submits the form to the address a=delete_selected. In the PHP handler, the array of selected IDs is passed via $_POST['s'], and after CSRF token verification, the deletion procedure (file inc/usradmintools.delete.php) is called for each ID. Deletion includes:

• Removing the record from cot_users.
• Removing group associations (cot_groups_users).
• Removing linked files of extra fields.
• If the option is set — deleting all user files from PFS.
• Logging the action.

5.5. Creating a New User

The "Create user" button opens a modal window with a form. It is pre-filled with values from the plugin settings (name, email, password, login counter). The administrator can modify these fields, select the main group and additional groups, and also fill in required extra fields (if marked as required). After submitting the form, the data is processed in inc/usradmintools.create.php: the uniqueness of the username and email is checked, the password is hashed, and a record is created in cot_users along with group associations.

6. Editing a User

Clicking the "Edit" button (or the link from the username) opens the page /admin/other?p=usradmintools&a=edit&id=XXX. The editing interface is designed with administrator convenience in mind and provides access to the full set of user fields.

6.1. Basic Data

At the top of the form, the user ID and a field for changing the login are displayed. The avatar (if the userimages plugin is active) and a link to the public profile are also visible here.

Fields available for editing:

• New password — if entered, the password will be changed; otherwise, it remains the same.
• Email — with uniqueness check.
• Hide email — Yes/No radio buttons.
• Signature — text field (with the possibility of using a mini-editor).
• Gender, Birthdate (dropdowns), Timezone.
• Registration date, Last login date, Login counter, Last IP (with a link to search by IP).
• Main group and membership in additional groups (checkboxes).
• Country, Language, Theme.
• Delete user — radio buttons and an option to delete PFS files.

6.2. Extra Fields

The plugin automatically picks up all extra fields defined for the users table. For each such field, an appropriate input field is created (the type depends on the extra field settings). The output is organized through the MAIN.EXTRAFLD loop in the template, allowing any number of extra fields to be added dynamically without changing the code.

Example template fragment:

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 -->

In PHP code, for each extra field, the following is performed:

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');

This approach ensures that even if new extra fields are added after the plugin installation, they will automatically appear in the editing form.

6.3. Group Management

In addition to the main group, the administrator can assign the user any number of additional groups. The function cot_build_um1_groupsms() is used, which generates a set of checkboxes for all groups (except guests), taking into account the current administrator's permissions. Upon saving, the plugin synchronizes records in cot_groups_users: adds missing ones and removes extraneous ones. Special protection is built in for the user with ID=1 — they cannot be removed from the super administrators group or placed into banned/inactive groups.

6.4. Temporary Access

The "Edit temporary access" link leads to the temporary access management page (a=access). Here, the administrator can set up temporary membership for the user in a specific group with a start and end date. This functionality is implemented in a separate table cot_usradmintools. The access status is displayed in the main list under the "TGA" column.

6.5. Deleting a User

The editing page includes a "Delete user" block. When "Yes" is selected and the form is saved, the user will be deleted, and the administrator will be redirected back to the list. It is also possible to delete all user files from PFS (if the module is active). Deletion of the super administrator (ID=1) is prohibited.

7. Integration with Other Modules and Plugins

The plugin is designed with Cotonti extensibility in mind and actively interacts with related extensions.

7.1. Module pm

If the private messages module is active, a column with a PM icon appears in the user list, and in the editing form — a setting for new message notifications.

7.2. Plugin payments

With the active payments module, the user's current balance is displayed in the list and during editing (via the cot_payments_getuserbalance() function).

7.3. Plugin paypro

If paypro is active, the plugin adds:

• In the list — a Premium status indicator with an expiration date.
• In the editing form — a field to set the Premium expiration date.

7.4. Plugin verification

A "Verification status" radio button (Yes/No) appears in the editing form, allowing the administrator to manually verify users.

7.5. Modules forums, page, comments

When the user's login is changed, the plugin automatically updates the author name in the corresponding tables of forums, pages, and comments. This ensures data integrity.

7.6. Plugin pfs

When deleting a user with the "Delete PFS files" option, the plugin calls cot_pfs_deleteall(), cleaning up all files uploaded by the user.

7.7. Plugin userimages

Used in the editing form to display the user's avatar with a link to the public profile.

8. Technical Implementation Details

For developers who wish to extend the plugin or understand its inner workings, a detailed breakdown of key mechanisms is provided below.

8.1. Request Parameter Handling

All input parameters are extracted using cot_import() with the expected type and maximum length specified. This protects against injections and invalid data. The sort parameter (formerly s) has been renamed to avoid conflict with the system parameter of the Cotonti admin panel.

8.2. Building SQL Queries with Filters and Sorting

The WHERE clause is assembled dynamically based on the passed filters. Named PDO placeholders are used to protect against SQL injection. Example for country filter:

php

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

If necessary, a JOIN is added to the main query (for example, for filtering by any group or sorting by group level). Pagination is implemented via cot_pagenav(), which automatically takes into account all URL parameters.

8.3. Generating the Sorting Interface and Direction

As mentioned earlier, to toggle the sorting direction, a link is generated that preserves all active filters. It is important to note that sorting links for table column headers are also generated using the cot_rc('users_link_sort', ...) function. This ensures a consistent look and behavior throughout the plugin.

8.4. Working with Messages and Validation

The plugin uses the standard Cotonti mechanism for displaying messages: cot_error(), cot_message(), cot_display_messages(). When saving the editing form, the plugin first validates the data (login, email, password validation). If there are no errors, the database is updated and cot_message() is called with the ok type. A redirect then occurs to the same page to prevent form resubmission. On the target page, the call to cot_display_messages($t) retrieves messages from the session and passes them to the template, where they are displayed via {FILE warnings.tpl}. This approach prevents message duplication and follows Cotonti best practices.

9. Templates and Customization

The plugin comes with two main templates:

• usradmintools.admin.tpl — user list.
• usradmintools.edit.tpl — editing form.

Both templates are built on Bootstrap 5 (using classes like container-fluid, card, row, col, table, btn, etc.). If necessary, they can be copied to the theme folder (themes/yourtheme/plug/usradmintools/) and adapted to your design.

9.1. Main Blocks of the List Template

• UM_FILTERS_* — filter panel elements.
• UM_TOP_* — table column headers with sorting support.
• MAIN.UM_ROW — repeating block for each user row.
• MAIN.EXTRAFLD — block for displaying required extra fields in the create user modal window.

9.2. Editing Template

• UM_EDIT_* — variables for form fields.
• MAIN.EXTRAFLD — dynamic output of all extra fields.
• Built-in JavaScript support for tooltips (data-bs-toggle="tooltip").

10. Frequently Asked Questions (FAQ)

Q: Why does a 404 error occur when sorting?
A: In standard Cotonti, the s parameter is used for internal admin routing. The usradmintools plugin renames the sorting parameter to sort, which resolves the conflict. Make sure you have the latest version of the plugin installed.

Q: How can I add a new field to the user list?
A: If it is an extra field, it will automatically appear in the list provided it is not on the blacklist ($usersSortFieldsBlacklist). For custom fields, you can extend the $users_sort_tags array in the usradmintools.admin.php file.

Q: Can I change the default group for new users?
A: Yes, the value is stored in Cot::$cfg['plugin']['usradmintools']['usradmintools_defaultlevel']. It can be overridden in config.php.

Q: The plugin does not display a success message after updating the profile.
A: Ensure that your template contains the line {FILE "{PHP.cfg.themes_dir}/{PHP.cfg.defaulttheme}/warnings.tpl"} and that the cot_display_messages($t) call is located before parsing the template. In the current version of the plugin, this is implemented correctly.

Q: How can I disable automatic form submission when changing filters?
A: Remove the filter-submit class from the corresponding select elements in the PHP code or override the template.

11. Conclusion

The usradmintools plugin is a comprehensive solution for user administration in Cotonti, combining a convenient interface, advanced filters and sorting, integration with popular modules, and a high level of security. Its modular architecture and adherence to Cotonti standards make it easy to extend functionality and adapt to specific projects.

Thanks to detailed documentation and open source code, the plugin can serve both as a ready-to-use tool for daily work and as a foundation for learning how to develop extensions for Cotonti. We hope that this guide will help you make the most of all usradmintools features.