Filament Umami Widgets Laravel Package

Getting Started

• Install the Filament Umami plugin with Composer, then register FilamentUmamiPlugin on the panel(s) where analytics should appear. 2.1.0 is a drop-in upgrade — “No changes needed in your code.”
• Requirements: Laravel 12 or 13 (Laravel 11 is no longer supported/tested as of 2.1.0) and Filament 4 or 5.
• Publish config and views (check php artisan vendor:publish for the exact tags). If you already published views, publish them again — the accessibility fix lives in the views.
• Configure the Umami server URL (cloud or self-hosted), the website ID, and login credentials if your Umami requires auth.
• First use case: add a stats widget to a panel and verify sessions, page views, and events render against your Umami instance. The sessions chart now reports sessions (previously it reported page views).
• Where to look first: the config file (server, website, polling interval) and FilamentUmamiPlugin. The new FilamentUmamiPlugin::current() is the safest way to reach the plugin instance.

Implementation Patterns

• Panel registration. In a panel provider, call ->plugin(FilamentUmamiPlugin::make()). Multiple panels/apps can share a cache store safely: as of 2.1.0, cache keys — including the login token — are scoped per Umami server and website.
• Optional plugin access. Use FilamentUmamiPlugin::current() instead of assuming the plugin exists. It returns null when the plugin isn’t on the current panel; wire widgets/actions conditionally rather than catching exceptions.
• Polling. Widgets poll. A widget rendered on a panel without the plugin now uses the default polling interval instead of throwing.
• Query inputs are clamped. Date ranges, row limits, and table options sent from the browser are validated; invalid values fall back to defaults. Your own UI can send values without extra server-side guarding.
• Events chart alignment. Every dataset now has a value for every day, so multi-series charts line up instead of shifting by a day when a day only had other events. Days are normalized to Y-m-d regardless of Umami’s date format and no longer appear twice.
• Colour / accessibility. Event colours use the colour-blind-safe Okabe-Ito palette; the legend stays visible so event names are readable as text, not just colour. Hidden table-select labels now use fi-sr-only and are translated.
• Resilience. Slow/unreachable Umami, non-JSON responses, and missing keys produce empty widget values rather than exceptions. Failed calls are not cached, so widgets recover as soon as Umami is back — no cache clear required.
• Immutable dates. Apps using Date::useClass(CarbonImmutable::class) are supported; no TypeError.
• Self-hosted auth. If Umami is down during login, the dashboard keeps working; wrong credentials still raise a clear error. Treat auth failures as actionable and outages as transient.
• Integration tip. Reuse the configured server/website when linking out to Umami. Shared Redis/memcached stores are safe thanks to the scoped cache keys.

Gotchas and Tips

• Re-publish views. Filament 4/5 don’t ship sr-only, so the old hidden table-select labels rendered as visible text. If you published views, your copies still have the old class.
• Laravel 11 is unsupported. Composer blocks Laravel 11 releases because of open security advisories; target Laravel 12 or 13.
• Cache keys changed. They are now scoped per server and website, including the login token. Expect a cold start after upgrading, and don’t hard-code old key patterns.
• Failed calls aren’t cached. During an outage the widget keeps retrying on each poll; consider a longer interval if you poll aggressively against a slow self-hosted instance.
• current() is nullable. Guard with ?->/null checks; code that previously caught an exception should now check for null.
• Colour output changed. Okabe-Ito replaces the previous palette — screenshots, snapshot tests, and custom chart theming may need updating (data is unaffected).
• Sessions chart semantics changed. Earlier versions reported page views as sessions; historical screenshots/exports may be mislabeled.
• Date format assumptions. Data is normalized to Y-m-d; don’t assume Umami’s native date format when post-processing chart data.
• Silent fallbacks. Invalid browser-sent options fall back to defaults — good for robustness, but don’t rely on arbitrary ranges/limits being honoured; validate in your own UI if it matters.
• Extension points. Widgets (polling/interval), config (server, website, polling), and current() for conditional features. Custom widgets should match the package’s declare(strict_types=1) and PHPStan max-level standards.
• Distinguish failure modes. Credential errors are clearly reported; outages degrade to empty widgets. Don’t swallow the former.