fof / online-users-widget

2.0.0 2026-10-10 14:23 UTC

Requires

• flarum/core: ^2.0.0
• fof/forum-widgets-core: ^2.0.0

Requires (Dev)

• flarum/phpstan: ^2.0.0
• flarum/realtime: ^2.0.0
• flarum/testing: ^2.0.0

Suggests

• flarum/realtime: Enables live updates of the online users list via the presence-online WebSocket channel.

Replaces

• afrux/online-users-widget: *

MIT

• FriendsOfFlarum

• Users
• widget
• online
• flarum

Published on Packagist.org on 2026-10-10 14:25 UTC

README

A Flarum extension. Forum Widget That Lists Online Users.

Note

This package was previously maintained as afrux/online-users-widget by @SychO9. It has been transferred to FriendsOfFlarum and is now published as fof/online-users-widget. The composer.json replace field ensures existing installs upgrade transparently — no manual removal needed.

Requirements

• Flarum 2.x
• Forum Widgets Core, which is installed with this extension
• Optionally, flarum/realtime for live updates

Installation

This will also install Forum Widgets Core as it relies on it.

Install with composer:

composer require fof/online-users-widget:"*"

Migrating from afrux/online-users-widget

If you currently have afrux/online-users-widget installed, run:

composer require fof/online-users-widget:"*"
composer remove afrux/online-users-widget
php flarum cache:clear

Updating

composer update fof/online-users-widget:"*" --with-dependencies
php flarum migrate
php flarum cache:clear

Setup

1. Enable the extension.
2. Grant the permission. Nobody but administrators can see the widget until you do. Under Admin → Permissions, in the View section, grant View Online Users Widget to the groups that should see it. It can be granted to guests too.
3. The widget is placed in the forum sidebar by default. Forum Widgets Core lets you move it; see its README.

Settings

Setting	Default	What it does
Max shown users	15	The most users listed. Anyone online beyond that is summarised as a "+N" chip. At least 1.
Last seen interval to consider a user online (in minutes)	5	Someone counts as online if they were seen within this long. At least 1.
Time to cache the users list (in seconds)	30	How long the list is kept before it is worked out again. 0 turns caching off.

A blank or non-numeric value falls back to the default.

Who is shown, and to whom

• Online means recently seen. A member counts as online if they were last seen within the last seen interval. That is the time of their last request, not whether they have a tab open.
• Only people with the permission are sent the list. This is enforced by the API, not just by hiding the widget: for anyone without View Online Users Widget the forum payload carries neither the list nor the total.
• Members can opt out. Someone who turns off Allow others to see when I am online in their privacy settings is left out of both the list and the total. Viewers who have the permission to see when users were last seen (user.viewLastSeenAt) still see them.
• Everyone sees only the users they are allowed to see, according to the forum's normal user visibility. On a forum that is not visible to guests, for example, a guest is shown nobody.
• The "+N" chip counts the rest. It is the total online minus the users listed, so it is also affected by the opt-out above.
• Avatars use the HiDPI variants of a member's picture when the forum has them.

The list is cached for the configured time, separately for each audience, so a viewer is never served a list worked out for someone who can see different users.

Keeping it up to date

Without realtime, the list arrives with the page. When you navigate back to a page that shows the widget and what is on screen is more than 30 seconds old, it is fetched again, so it does not stay frozen for the length of a visit.

Live updates with flarum/realtime

If flarum/realtime is installed and enabled, the widget also refreshes as people arrive. No configuration is needed.

composer require flarum/realtime

• Presence is only a signal. When someone arrives, other viewers' widgets ask the server for the list again, a few seconds later (between 2 and 5, so that everyone does not ask at once). What is shown is always the server's answer, with the same rules as above. The websocket never supplies the list itself.
• Only arrivals trigger it. Someone leaving does not remove them straight away; they drop off once they have not been seen for the last seen interval.
• Nothing happens while the widget is out of sight. A member joins the presence channel only once a page showing the widget has been opened. If something changed while they were on another page, they catch up when they come back.
• Who joins the channel. Joining announces the member by display name to everyone else in it, so it is restricted: they must have the View Online Users Widget permission, and members who have opted out of being shown as online do not join (so they get no live updates) unless they have the permission to see when users were last seen. Guests do not join and do not get live updates.

This extension does not use flarum/pusher and has no plans to.

For developers

The online users are cached per audience. The cache key already accounts for whether the viewer can see the forum and whether they can see when users were last seen. If your extension changes which users a viewer can see in some other way, for example a user visibility scope that depends on the viewer's group, tell the widget what distinguishes one audience from another. Otherwise viewers with different visible users would share one cache entry.

use Flarum\User\User;
use FoF\OnlineUsers\Extend\OnlineUsers;

return [
    (new OnlineUsers())
        ->cacheKeyParameters(fn (User $actor): string => $actor->groups->pluck('id')->sort()->implode('.')),
];

cacheKeyParameters() takes a callable, or the name of an invokable class resolved from the container. It receives the viewer and returns a string. Viewers who get the same string share a cache entry.

Troubleshooting

• The widget does not appear. Check that View Online Users Widget has been granted to the viewer's group (it is not granted to anyone by default), and that Forum Widgets Core has it in a placement. Forum Widgets Core shows widgets on the discussion list (all discussions, a tag, following) and on any page that extends IndexPage. A page added by another extension, such as a categories page, shows them only if that extension opts the page in; see "Showing widgets on your own page" in the Forum Widgets Core README.
• Nobody is listed, but people are online. They may have opted out (see above), or this viewer may not be allowed to see them.
• The list is a little behind. It is cached for the configured time. Lower Time to cache, or install flarum/realtime.

Development

composer install
composer test:setup       # once, to prepare the test database. It wipes the database it points at,
                          # so use a dedicated one.
composer test             # unit and integration tests
composer analyse:phpstan

cd js
yarn install
yarn test                 # frontend tests
yarn format               # before committing JS changes

Links

• Packagist
• GitHub
• Discuss