Statistics Laravel Package

Getting Started

Install through Composer and enable it like any Flarum extension:

composer require flarum/statistics
php flarum cache:clear
# then Admin → Extensions → Statistics → Enable

There are no migrations to run — the extension reads existing users, discussions, and posts tables rather than storing its own data, so enabling/disabling is non-destructive.

Where to look first

• extend.php — shows the /api/statistics route and the DashboardPage extender that mounts the widget.
• js/src/admin/ — the widget component and its chart rendering.
• src/Api/Controller/ — the controller that aggregates counts and time-series data.

First use case: log into the admin panel, open Dashboard, and confirm the Statistics widget renders totals plus the growth chart. Then call the API with an admin session/token to confirm you can consume it programmatically:

curl -H "Authorization: Token <admin-token>" https://forum.test/api/statistics

That endpoint is the real integration surface — the widget is just a consumer of it.

Implementation Patterns

Dashboard-first monitoring. The default pattern is simply enabling the widget and letting admins eyeball user/discussion/post growth. Treat the Dashboard page as the "home" for community health.

External status boards. Because the data is exposed at /api/statistics, poll it from a cron job or uptime/status tool (Grafana JSON datasource, a small Laravel/PHP collector, etc.) using an admin token. This is the most common day-to-day leverage — get the numbers out of Flarum and into whatever you already monitor.

Snapshot for history. The extension computes aggregates live; it does not keep historical rows. If you need long-term reporting, write a scheduled command in your own extension that hits the endpoint (or queries the DB directly) and persists one row per day into a statistics_snapshots table. You then own retention, backfills, and charting.

Custom admin widgets via extenders. To add your own metrics card alongside it, create a small extension and use Flarum's DashboardPage extender to register another widget component. Mirror the structure of this extension's frontend component — same extend() registration, same widget position API. You can also use the extender to remove or reorder the Statistics widget without forking.

Overriding presentation. Need a different chart library or extra series? Don't patch vendor/; create an extension that imports the widget and uses Flarum's JS override() to replace its source/view, or register a replacement component and hide the original via the Dashboard extender.

Reporting commands. For periodic reports (weekly growth email, Slack digest), reuse the same aggregation queries inside a custom flarum console command rather than scraping the API — you avoid token handling and get direct DB access for date bucketing.

Gotchas and Tips

• This repo is a read-only subtree split. Never send PRs here — contributions belong upstream (the Flarum framework/monorepo). Pin a version constraint and expect the split to track upstream releases rather than independent ones.
• Admin-gated endpoint. /api/statistics requires admin permission. Regular user tokens get a 403. For automation, mint a dedicated admin token or expose your own read-only endpoint in a custom extension if you want public stats.
• Performance on large forums. Counts and grouped-by-day queries run live against big tables. On forums with millions of posts the Dashboard can get noticeably slow. Mitigate with DB indexes on created_at, snapshotting, or disabling the widget for non-essential admins.
• Timezone/date bucketing. Grouping by day follows the DB/app timezone. If your server is UTC but your community is UTC+8, chart edges can look "a day off." Set APP_TIMEZONE/DB timezone consistently and document it.
• Soft-deleted and hidden content. Verify whether counts include hidden discussions or soft-deleted posts for your version — totals in the widget and your own SQL may disagree until you match the same whereNull('hidden_at') conditions.
• Caching and assets. After enabling/disabling or changing anything frontend, run php flarum cache:clear; in production also republish assets. A stale admin bundle is the usual cause of "the widget disappeared."
• JS overrides require a real extension. You cannot tweak the widget by editing vendor/ — Composer will overwrite it. Do it through a companion extension with override() and a proper extend.php.
• Version coupling. The API response shape and component internals can shift between Flarum minor releases. Re-test the endpoint after upgrades; if you depend on the JSON structure, wrap it behind your own transformer.
• Debugging checklist: browser Network tab for the /api/statistics call and status code, storage/logs/flarum.log for backend errors, php flarum info to confirm the extension is listed and enabled.