Initial implementation of a Health Check system and dashboard

[obuisard]

Pull Request resolves # .

• I read the Generative AI policy and my contribution is either not created with the help of AI or is compatible with the policy and GNU/GPL 2 or later.

Summary of Changes

This PR aims at adding Health Check functionality to Joomla, in a dedicated dashboard.
It lays out the underlying initial implementation and aims at giving instructions to developers to create specific Health Check plugins.

Testing Instructions

There is one piece missing, it is the installation of a module healthcheck instance. It is incoming in this draft.
Right now, you need to use the 'discover' functionality to try this PR out.
Thank you for your patience.

Health Check Plugin Developer Guide

This guide explains how to build a healthcheck plugin for Joomla's Health Check module, using the existing usermaintenance plugin as the baseline example.

Relevant core code in this workspace:

• Module data collection: administrator/modules/mod_healthcheck/src/Helper/HealthCheckHelper.php
• Module rendering entry point: administrator/modules/mod_healthcheck/tmpl/default.php
• Layout rendering helper: libraries/src/HTML/Helpers/HealthChecks.php
• Layout templates:
  • layouts/joomla/healthchecks/icon.php
  • layouts/joomla/healthchecks/gauge.php
  • layouts/joomla/healthchecks/list.php
  • layouts/joomla/healthchecks/table.php
• Example plugin (icons only): plugins/healthcheck/usermaintenance

1) How the Health Check plugin system works

1. The module imports the healthcheck plugin group and dispatches events like onHealthcheckGetIcons, onHealthcheckGetGauges, onHealthcheckGetLists, and onHealthcheckGetTables.
2. Each enabled plugin can subscribe to one or more events and append data into the event result argument.
3. The module validates required fields and applies defaults (HealthCheckHelper methods getButtons(), getGauges(), getLists(), getTables()).
4. The HTMLHelper::_('healthchecks.*', ...) helper renders each item through the matching layout file.

The module passes a context value to events. Your plugin should usually ignore events for other contexts.

2) Minimal plugin structure

Use the same structure as plugins/healthcheck/usermaintenance:

plugins/healthcheck/yourplugin/
  yourplugin.xml
  services/provider.php
  src/Extension/YourPlugin.php
  language/en-GB/plg_healthcheck_yourplugin.ini
  language/en-GB/plg_healthcheck_yourplugin.sys.ini

yourplugin.xml essentials

• group="healthcheck"
• plugin namespace
• files and language declarations
• optional plugin params (including a context text field)

The usermaintenance example defines:

<extension type="plugin" group="healthcheck" method="upgrade">

services/provider.php essentials

Register your plugin as PluginInterface with lazy loading, like plugins/healthcheck/usermaintenance/services/provider.php.

src/Extension/YourPlugin.php essentials

• extend CMSPlugin
• implement SubscriberInterface
• return event subscriptions in getSubscribedEvents()

3) Event subscriptions and payload contracts

Event names

• Icons: onHealthcheckGetIcons
• Gauges: onHealthcheckGetGauges
• Lists: onHealthcheckGetLists
• Tables: onHealthcheckGetTables

Expected return pattern

Each event method should:

1. Read current result: $result = $event->getArgument('result', []);
2. Append one array of items: $result[] = $items;
3. Write back: $event->setArgument('result', $result);

This matches the pattern in usermaintenance (onHealthcheckGetIcons).

Context guard pattern

Use the same guard style as usermaintenance:

$context = $event->getContext();

if ($context !== $this->params->get('context', 'general')) {
    return;
}

4) Icon items (button layout)

Icons are dispatched through onHealthcheckGetIcons and rendered by layouts/joomla/healthchecks/icon.php.

Required fields

From HealthCheckHelper::getButtons():

• link (required)
• one of text or name (required)

Common fields

• icon (for icon class, used by layout)
• image (optional image URL)
• amount (numeric/string badge amount)
• status (success, warning, error, etc.; affects color/filter)
• id, class, target, title, onclick
• group (defaults to general)
• access (boolean or ACL pair array)

Example (based on usermaintenance)

public function onHealthcheckGetIcons(HealthChecksEvent $event): void
{
    if ($event->getContext() !== $this->params->get('context', 'usermanagement')) {
        return;
    }

    $checks = [];

    $checks[] = [
        'link'   => 'index.php?option=com_users&view=users&filter[state]=1',
        'icon'   => 'fas fa-users-gear',
        'amount' => 12,
        'text'   => 'Inactive users',
        'id'     => 'plg_healthcheck_example_inactive',
        'status' => 'warning',
    ];

    $checks[] = [
        'link'   => 'index.php?option=com_users&view=users&filter[mfa]=0',
        'icon'   => 'fas fa-shield-halved',
        'amount' => 0,
        'text'   => 'Users without MFA',
        'status' => 'success',
    ];

    $result   = $event->getArgument('result', []);
    $result[] = $checks;
    $event->setArgument('result', $result);
}

5) Gauge items

Gauges are dispatched through onHealthcheckGetGauges and rendered by layouts/joomla/healthchecks/gauge.php.

Required fields

From HealthCheckHelper::getGauges():

• score
• unit

Useful optional fields

• label, sublabel, note
• score_min, score_max
• score_threshold_warning, score_threshold_success
• link
• linktitle (used by layout)
• group, access, class, id

Example

public function onHealthcheckGetGauges(HealthChecksEvent $event): void
{
    if ($event->getContext() !== $this->params->get('context', 'performance')) {
        return;
    }

    $gauges = [[
        'id'                      => 'plg_healthcheck_example_php_memory',
        'label'                   => 'PHP memory usage',
        'sublabel'                => 'Current process',
        'note'                    => 'Values over 80% should be reviewed.',
        'score'                   => 72,
        'unit'                    => '%',
        'score_min'               => 0,
        'score_max'               => 100,
        'score_threshold_warning' => 70,
        'score_threshold_success' => 90,
        'link'                    => 'index.php?option=com_config',
        'linktitle'               => 'Open Global Configuration',
        'status'                  => 'warning',
    ]];

    $result   = $event->getArgument('result', []);
    $result[] = $gauges;
    $event->setArgument('result', $result);
}

6) List items

Lists are dispatched through onHealthcheckGetLists and rendered by layouts/joomla/healthchecks/list.php.

Required fields

From HealthCheckHelper::getLists():

• items (array)

Useful optional fields

• type (ul, ol, or div)
• class, id, itemClass
• group, access

Example

public function onHealthcheckGetLists(HealthChecksEvent $event): void
{
    if ($event->getContext() !== $this->params->get('context', 'security')) {
        return;
    }

    $lists = [[
        'id'       => 'plg_healthcheck_example_security_tips',
        'class'    => 'list-group list-group-flush',
        'itemClass'=> 'list-group-item',
        'type'     => 'ul',
        'items'    => [
            'Enable MFA for all administrators',
            'Review inactive accounts monthly',
            'Remove users not assigned to any group',
        ],
    ]];

    $result   = $event->getArgument('result', []);
    $result[] = $lists;
    $event->setArgument('result', $result);
}

7) Table items

Tables are dispatched through onHealthcheckGetTables and rendered by layouts/joomla/healthchecks/table.php.

Required fields

From HealthCheckHelper::getTables():

• columns (array)
• data (array)

Column definition basics

Each column typically uses:

• key (data key)
• title (header)
• optional type (text, badge, link, date, boolean, progress, icon, custom)
• optional display keys (align, width, scope, cellClass, etc.)

type rendering is handled by HealthCheckHelper::renderTableCellContent().

Example

public function onHealthcheckGetTables(HealthChecksEvent $event): void
{
    if ($event->getContext() !== $this->params->get('context', 'usermanagement')) {
        return;
    }

    $tables = [[
        'id'      => 'plg_healthcheck_example_user_risk',
        'caption' => 'Users requiring attention',
        'class'   => 'table-sm',
        'columns' => [
            ['key' => 'name', 'title' => 'User'],
            ['key' => 'lastvisitDate', 'title' => 'Last login', 'type' => 'date'],
            ['key' => 'mfa', 'title' => 'MFA', 'type' => 'boolean'],
            ['key' => 'risk', 'title' => 'Risk', 'type' => 'badge', 'badgeClass' => static function ($value) {
                return $value === 'high' ? 'danger' : ($value === 'medium' ? 'warning' : 'success');
            }],
        ],
        'data' => [
            ['name' => 'Alice Admin', 'lastvisitDate' => '2026-05-14 09:05:00', 'mfa' => 1, 'risk' => 'low'],
            ['name' => 'Bob Manager', 'lastvisitDate' => '2026-01-07 11:21:00', 'mfa' => 0, 'risk' => 'high'],
        ],
    ]];

    $result   = $event->getArgument('result', []);
    $result[] = $tables;
    $event->setArgument('result', $result);
}

8) Full subscriber example

public static function getSubscribedEvents(): array
{
    return [
        'onHealthcheckGetIcons'  => 'onHealthcheckGetIcons',
        'onHealthcheckGetGauges' => 'onHealthcheckGetGauges',
        'onHealthcheckGetLists'  => 'onHealthcheckGetLists',
        'onHealthcheckGetTables' => 'onHealthcheckGetTables',
    ];
}

You can implement only the events you need.

9) Grouping and access control

• group: defaults to general; use it to classify data by module context strategy.
• access:
  • true/false for quick allow/deny
  • or ACL checks as pairs, e.g. ['core.manage', 'com_users', 'core.admin', 'com_users']

Access is evaluated in libraries/src/HTML/Helpers/HealthChecks.php (canAccess()).

10) Testing checklist

1. Install/enable your plugin in group healthcheck.
2. Ensure the module mod_healthcheck is enabled in Administrator.
3. Set module context to match your plugin context parameter.
4. Confirm each subscribed event returns at least one valid item with required fields.
5. Verify rendering in the module UI:
   • icons appear in the icon section
   • gauges render SVG meters
   • lists render item collections
   • tables render with expected cell types

11) Practical notes from current implementation

• The usermaintenance plugin currently demonstrates the icon event only.
• Gauge layout reads linktitle for link title text.
• The helper default includes link_title for gauges; if you need guaranteed title output in the current layout, set linktitle in your payload.
• Any missing required field causes that item to be filtered out before rendering.

12) How healthcheck-filters works

The filter bar is part of the module template (administrator/modules/mod_healthcheck/tmpl/default.php), not the plugin itself.

What filters are available

The module renders four filter buttons:

• all
• healthy
• warning
• critical

Selecting a button shows only matching health-check items in the module.

What plugin authors should set

To make your items filter correctly, provide status on each item payload.

Use these values:

• success for healthy items
• warning for warning items
• error for critical items

If status is omitted, items default to the healthy group.

Where filtering applies

Filtering currently applies to items rendered by these layouts:

• layouts/joomla/healthchecks/icon.php
• layouts/joomla/healthchecks/gauge.php
• layouts/joomla/healthchecks/list.php
• layouts/joomla/healthchecks/table.php

All filterable items are tagged with data-healthcheck-status, and the module script (media_source/mod_healthcheck/js/healthcheck-filter.js) uses that value to show/hide items.

Status aliases accepted by the module filter

The filter normalization accepts these aliases:

• success, ok, info -> healthy
• warning, warn, alert -> warning
• error, danger -> critical

Quick usage example

$checks[] = [
    'link'   => 'index.php?option=com_users&view=users&filter[mfa]=0',
    'icon'   => 'fas fa-shield-halved',
    'amount' => 3,
    'text'   => 'Users without MFA',
    'status' => 'warning', // appears when the Warning filter is selected
];

Testing filter behavior

1. Enable your healthcheck plugin and mod_healthcheck.
2. Return items with a mix of success, warning, and error statuses.
3. In Administrator, switch between All, Healthy, Warning, and Critical.
4. Confirm only matching items remain visible for each filter.

Link to documentations

Please select:

• Documentation link for guide.joomla.org:

• No documentation changes for guide.joomla.org needed

• Pull Request link for manual.joomla.org:

• No documentation changes for manual.joomla.org needed

[brianteeman]

double %% ?

[obuisard]

It is needed for PHP sprintf escaping so we end with one % and not have PHP trying to parse it

[brianteeman]

i am not convinced this is correct but its impossible to test

[brianteeman]

Better, I think I will create an additional plugin that highlights all cases, that will not be included in the core.

Please do so that this PR can be really tested - otherwise its not possible for someone to test the entirety of the PR

[chmst]

The color contrast for review is not sufficient. This color (warning) It is a long existing error in atum, but not visible on other places. (Except during update/migration checks)

[obuisard]

The color contrast for review is not sufficient. This color (warning) It is a long existing error in atum, but not visible on other places. (Except during update/migration checks)

It looks like we should open a PR for a template fix.

[brianteeman]

none of the language strings in this file are present in the pr

[brianteeman]

inconsistency in the language strings

Score: 68 % out of 100 %. This represents 68.0% of the range from 0 to 100. Status: Good performance with room for improvement.

• here we can see that there is a space between the value and the % which should not be there
• the first instance is to 0 decimal places and the second is to one devimal place
• as its a % it doesnt even need to say "out of 100%" as it cant be anything else
• as its a % then the entire "This represents 68.0% of the range from 0 to 100" is redundant

[brianteeman]

using link text and title and aria-label is not a good idea. It is generally bad of accessibility espec with screen readers. what are you trying to achieve by doing this

[brianteeman]

Thanks for getting the ai to find the issue with the language strings

[brianteeman]

This makes extensive use of (often invisible) links with both title and aria-labels to explain the purpose of the link with different levels of information. This can be tricky as screen readers will use one or both which is overkill.

Titles are also invisible to keyboard users and mobile users. On the gauges it's not even obvious that they have a link behind them.

Ideally every link should have anchor text which describe the link and an aria-labels only used where the anchor text is insufficient.

Additional reading https://www.deque.com/blog/text-links-practices-screen-readers/

[brianteeman]

Please don't add useless descriptions. This doesn't add anything that is not in the field label

[brianteeman]

Setting tabindex -1 will make it unreachable by a screenreader

[brianteeman]

Please follow the style guide - labels should be capitalised

[brianteeman]

Based on the link option=com_users&view=users&filter[state]=1 this should be disabled not inactive users and the description was completely wrong

[brianteeman]

Suggested change

	PLG_HEALTHCHECK_USERMAINTENANCE_GETINACTIVE_ERROR="Error while trying to get the number of inactive users."
	PLG_HEALTHCHECK_USERMAINTENANCE_GETINACTIVE_ERROR="Error while trying to get the number of disabled users."

[brianteeman]

Suggested change

	PLG_HEALTHCHECK_USERMAINTENANCE_INACTIVE_FIELD_LABEL="Inactive Users"
	PLG_HEALTHCHECK_USERMAINTENANCE_INACTIVE_FIELD_LABEL="Disabled Users"

[brianteeman]

Suggested change

	PLG_HEALTHCHECK_USERMAINTENANCE_INACTIVE_FIELD_DESC="Users who did not login in the last few months."
	PLG_HEALTHCHECK_USERMAINTENANCE_INACTIVE_FIELD_DESC="Users whose accounts are disabled."

[dgrammatiko]

XSS