Download the PHP package akibeo/kirby-umami without Composer

Kirby Umami

Umami analytics for Kirby. Umami is cookieless and stores no personal data, so it needs no cookie banner and no consent gating.

• Tracker script — one snippet prints the <script> tag with every tracker option as config.
• CSP nonce — picks up cspNonce() from akibeo/kirby-csp automatically.
• Off while developing — nothing is tracked while Kirby's debug option is on.
• Server-side events — umami()->track('contact-form') from PHP, for things that never reach the browser tracker (form endpoints, redirects).
• Panel view — an "Analytics" entry with visitors, visits, pageviews, bounce rate and visit time for the last 24h / 7 / 30 / 90 days, a link to the Umami dashboard and, optionally, the embedded public share report.
• Cloud or self-hosted — works with Umami Cloud (API key) and self-hosted instances (API key or username/password).

Installation

Composer

Download / Git submodule

Copy this repository into site/plugins/kirby-umami/:

No build step is required — Kirby autoloads plugins from site/plugins/. The plugin registers itself as akibeo/umami and reads its options from the akibeo.umami namespace.

Configuration

Add to site/config/config.php. Only enabled and websiteId are required; the rest are shown with their defaults.

Keep secrets (apiKey, password) in a host config (config.<host>.php) that is not committed.

Per-environment overrides

config.localhost.php and friends can override any key:

Content-Security-Policy

With akibeo/kirby-csp the script tag carries the per-request nonce, so script-src needs nothing extra. The tracker posts to /api/send on the Umami host, so add that host to connect-src:

Without kirby-csp, set 'nonce' => fn () => myNonce() (a callable is resolved per request) or leave it null.

trackPanelUsers and the pages cache

When the pages cache is on, the first visitor decides what gets cached. A logged-in Panel user hitting an uncached page would cache it without the tracker. Leave trackPanelUsers on when the pages cache is on, or exclude your own visits in Umami instead (localStorage.setItem('umami.disabled', 1) in the browser console).

Usage

Tracker script

In a plain PHP template:

In a Blade layout:

Or build the tag yourself:

The tag is empty when tracking is off, so it can always be printed.

Server-side events

The event joins the visitor's session in Umami: the visitor's IP and User-Agent are forwarded. Returns false when tracking is off or Umami could not be reached; it never throws.

Stats from PHP

Results are cached for 10 minutes (one minute for active()). All of them throw Akibeo\Umami\UmamiException when the API is unreachable or the credentials are wrong; $e->status() holds the HTTP status. Any other endpoint of the Umami API is reachable through umami()->api('websites/…').

Panel

"Analytics" in the Panel menu: the summary numbers with the change against the previous period, visitors online now, a pageviews chart and the breakdown tables of the Umami dashboard (pages, referrers, browsers, countries, events, …) for the last 24 hours, 7, 30 or 90 days. Without API credentials it only links to the Umami dashboard (and shows the share report if shareUrl is set). To embed the share report, the Umami instance has to allow framing by the Panel origin: set ALLOWED_FRAME_URLS=https://www.example.com in the Umami environment.

API endpoints

Both need a Panel session.

GET /api/plugin/umami/stats?range=7d returns the summary, the live count and the chart series:

GET /api/plugin/umami/metrics?type=country&range=7d&limit=50 returns one breakdown table:

Development

The logic lives in Akibeo\Umami\Umami (src/Umami.php); the test suite in tests/ runs it against a bare Kirby app, so no Umami instance is needed.

License

E-xperience LAB

Credits

• Wannes Debusschere