Task - Inactive Users Documentation

Extension Page: Task - Inactive Users

The Task - Inactive Users plugin is a free Joomla task plugin designed to automate the management of inactive user accounts, ensuring your site remains secure and compliant. Commissioned by an anonymous member of the Joomla community, who generously offered this tool to the Joomla community, it identifies users who haven’t logged in for a specified period and either deactivates them or triggers custom actions like notifications. Built for Joomla 5.x, it integrates with the task scheduler, CLI, and event system, offering flexibility for community sites, membership platforms, or e-commerce portals.

Overview

Task - Inactive Users provides two tasks:

Deactivate Inactive Users: Blocks users inactive for a specified period, adds a note to their account, and triggers the onInactiveUserDeactivate event.
Warn Inactive Users: Triggers the onInactiveUserWarn event for inactive users, allowing custom actions like notifications.

Key features include configurable inactivity periods (using ISO 8601 format), user group exclusions, categorized user notes, CLI support, and event-driven extensibility. Released under the GPL license, it’s a community-driven tool for Joomla administrators.

Installation

Download: Get Task - Inactive Users from the Joomla Extensions Directory or the RicheyWeb GitHub repository.
Install: In your Joomla administrator panel, navigate to System > Install > Extensions, upload the plugin package, and install it.
Enable: Go to System > Manage > Plugins, search for Task - Inactive Users, and enable it.

Configuration

Plugin Settings

Navigate to System > Manage > Plugins and open Task - Inactive Users.
Configure the following parameters:
- Ignored User Groups: Select user groups (e.g., Administrators) to exclude from inactivity checks. Use the multi-select field to choose groups.
- User Note Category: Choose a category (from com_users) for notes added to deactivated users’ accounts. Create a category in Users > Categories if needed.

Task Setup

Go to System > Scheduler > Tasks and click New.
Select a task type:
- Deactivate Inactive Users: Blocks inactive users and adds notes.
- Warn Inactive Users: Triggers events for custom actions (e.g., notifications).
Set task parameters:
- Inactivity Period: Enter an ISO 8601 duration (e.g., P1Y for 1 year, P6M for 6 months, P1Y2M3D for 1 year, 2 months, 3 days). Default is P1Y.
- Example: For 6 months, enter P6M. For 1 year and 1 month, enter P1Y1M.
Configure the task schedule (e.g., daily, weekly) or set to manual execution.
Save and enable the task.

Usage

Running Tasks via Scheduler

Tasks run automatically based on the schedule set in the Joomla task scheduler.
The plugin queries the #__users table for users who:
- Have a lastvisitDate older than the specified period, OR
- Have a registerdate older than the period and lastvisitDate is NULL (never logged in).
Deactivate Task:
- Blocks users (block = 1).
- Adds a note to the user’s account (e.g., “User account deactivated on 2025-10-20 13:51:00 due to more than 1 year of inactivity”).
- Triggers the onInactiveUserDeactivate event.
Warn Task:
- Triggers the onInactiveUserWarn event without modifying accounts.
- Requires a companion plugin to handle actions like notifications.

Running Tasks via CLI

Execute tasks manually or via cron using Joomla’s CLI:
```
php joomla.php scheduler:run -i <task id>
```
Find the <task id> in System > Scheduler > Tasks (e.g., 1 for the first task).

Example cron job to run task ID 1 daily at midnight:

0 0 * * * php /path/to/joomla/joomla.php scheduler:run -i 1

Ensure the Joomla CLI is accessible and your server supports cron jobs.

Event Handling

The plugin dispatches two events for extensibility:

onInactiveUserDeactivate: Triggered when a user is deactivated, with data:
- userId: User ID.
- username: Username.
- email: User email.
onInactiveUserWarn: Triggered for inactive users, with the same data.

Create a companion plugin in the inactiveusers group to listen for these events. Example for email notifications:

namespace MyCompany\Plugin\InactiveUsers\Notify\Extension;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\CMS\Mail\MailTemplate;
use Joomla\Event\SubscriberInterface;

\defined('_JEXEC') or die;

class Notify extends CMSPlugin implements SubscriberInterface
{
    protected $autoloadLanguage = true;

    public static function getSubscribedEvents(): array
    {
        return ['onInactiveUserWarn' => 'onInactiveUserWarn'];
    }

    public function onInactiveUserWarn($event): void
    {
        $data = $event->getArgument('data');
        if (!$data['email']) {
            return;
        }
        $mailer = new MailTemplate('plg_inactiveusers_notify.warn', 'en-GB');
        $mailer->addRecipient($data['email']);
        $mailer->addTemplateData([
            'username' => $data['username'],
            'site_name' => \Joomla\CMS\Factory::getApplication()->get('sitename'),
            'login_url' => \Joomla\CMS\Uri\Uri::root() . 'index.php?option=com_users&view=login',
        ]);
        try {
            $mailer->send();
        } catch (\Exception $e) {
            error_log('Inactive user warning email failed: ' . $e->getMessage());
        }
    }
}

Save this as notify.php in a plugin package under the inactiveusers group and create a corresponding email template.

Troubleshooting

Task Not Running: Ensure the Joomla scheduler is enabled (System > Scheduler > Settings) and the task is enabled with a valid schedule.
CLI Errors: Verify the path to joomla.php and PHP version (8.0–8.2 recommended). Check server permissions for CLI execution.
No Users Processed: Confirm the inactivity period is correct (e.g., P1Y for 1 year) and users meet the criteria (active, not in ignored groups).
Event Not Triggering: Ensure companion plugins are in the inactiveusers group and enabled. Check for errors in Joomla’s logs.
Notes Not Added: Verify the user note category exists and is correctly set in plugin parameters.

Documentation