User Directory Laravel Package

Getting Started

• Install with Composer and enable it, nothing else is required for the default page:

  composer require fof/user-directory
  php flarum cache:clear
  

  Then enable User Directory in the admin Extensions tab.
• Configure the two things that matter first: the permissions (View user directory under the Permissions tab) and the extension settings (default sort, page size, whether suspended users are listed, whether the nav link is shown). Guests only see the directory if the permission is granted to the Guest group.
• Look first at extend.php and js/src/forum/ in the package. extend.php shows the registered route, the API controller overrides, and any settings/permission registration; the forum JS shows the list page component and how it queries /api/users.
• The default first use case is simply exposing /users as a member directory: grant the permission to Members (and optionally Guests), add the nav link in settings, and confirm the page renders in the same theme as the rest of the forum. From there the common next step is tuning what columns/sorts appear and who can see whom.

Implementation Patterns

• Permission-gated access in your own code. Reuse the same ability rather than role names, e.g. $actor->can('fof-user-directory.view') (check the exact ability string in extend.php) before linking to the directory from custom pages, widgets, or emails. Keep the admin permission and your custom link logic in sync so you never link to a 403.
• Deep-link into a pre-filtered directory. The page is backed by Flarum's /api/users endpoint, so build URLs with query parameters (filter[q], group filters, sort, page[near]) and let the directory component hydrate from them. This is the cleanest way to add "Browse members in group X" or "Find a user" entry points from other extensions.
• Custom filters and columns via JS extenders. Rather than forking the package, use Flarum's extend()/override pattern on the directory page component to inject an extra filter control or a badge/column on each user card. Override the component's view/items method and call the parent, then mutate the vnode tree. This survives minor package updates far better than a fork.
• Add API filters on the backend when the UI needs new data. Use an ApiController extender on the users index endpoint (and a matching filter on the User searcher) so the frontend filter you added maps to a real, paginated query rather than client-side filtering of a loaded page.
• Hiding users from the directory. If the package exposes a per-user "hide from directory" preference, respect it in any custom listing you build by applying the same filter. If it does not, add a boolean user preference via a settings extender and filter on it in your API extender — doing this consistently is the difference between a directory users trust and one they complain about.
• Pair with profile/badge extensions. The directory is a list view of the same User model used everywhere else, so badges, groups, online status, and avatar decorations generally flow through if those extensions extend the user model or the user card component. Test with them enabled rather than assuming.
• Theme integration. Prefer CSS overrides scoped to the directory page over template copies, and check the page in both the default Flarum theme and any custom theme — the list markup is plain Flarum/Mithril and themes that restyle .UserCard or discussion lists often miss it.
• Caching and scale. For large forums, keep the page size modest, keep sorting on indexed columns (username, joinedAt, lastSeenAt), and avoid adding filters that force full table scans. If you add a "random members" style feature, implement it with a bounded query, not ORDER BY RAND() over the whole user table.

Gotchas and Tips

• Permission changes need a cache clear. After adjusting who can view the directory, run php flarum cache:clear; stale permission caches are the usual cause of "guests still see it" or "members get 403."
• Guests and the /api/users endpoint. The directory page can render for guests while the underlying user list API still respects the user policy. If the page loads but is empty for guests, the problem is almost always the API-level visibility, not the page component.
• Suspended and unactivated users. Decide explicitly whether they should appear. The default listing can include them; filter on the relevant user attributes in your API extender if you want them excluded, and document the choice for moderators.
• Empty states look broken. With restrictive permissions or a new forum, the directory can be empty. Check the component's empty-state handling and add a sensible message; an empty white page reads as a bug.
• Search behavior is server-side. filter[q] matches usernames (and display names if nicknames are installed) according to the underlying searcher. If users report "search doesn't find me," check whether the field being searched is the one they expect, especially on forums using a separate display-name extension.
• Route and nav-link conflicts. Other extensions that add a "Users" link or override the user list page can collide with the directory's nav entry. Check the header nav after installing anything user-list related, and disable the package's nav link in settings if you're linking manually.
• SEO. A public directory is a crawlable list of member profiles. If that's not desired, restrict it to members or add noindex via your SEO extension; retrofitting this after Google has indexed the page is annoying.
• Upgrade pinning. Check the package's Flarum core constraint in composer.json before bumping Flarum. Because the extension is small and low-traffic, an incompatible core release may land before the extension catches up — pin core and the extension together and test on staging.
• Extend, don't fork, for small changes. The realistic extension points are the JS page component and the users API controller. Almost every day-to-day customization ("add a group filter," "show last seen," "hide banned users") fits in one of those two, which keeps you on the update path.