Filament Umami Widgets Laravel Package

Technical Evaluation

Architecture fit. The package is a read-only presentation layer: a Filament plugin that authenticates against an Umami instance, polls its API, and renders sessions/events charts and tables inside an admin panel. 2.1.0 does not change that contract — no schema, no new endpoints, no new configuration surface beyond FilamentUmamiPlugin::current(). It fits cleanly wherever we already run Filament 4/5 on Laravel 12+. The release is overwhelmingly a hardening release: stricter typing, PHPStan at max with no baseline, 18 new failure-path tests, and defensive handling of malformed/slow/unreachable upstream responses. Those are the signals we care about when a plugin sits in the admin panel of a business application.

Integration feasibility. The upgrade is a Composer version bump with an explicit "no changes needed in your code" claim. That claim is almost true — there are three real caveats:

1. Laravel 11 support is dropped. The vendor's rationale (Composer blocks Laravel 11 releases due to open security advisories) is sound, but any application still on Laravel 11 cannot take this release. That is a hard gate, not a warning.
2. Published views must be re-published. The sr-only → fi-sr-only change is a fix, but it only reaches apps that vendored the views if we re-publish. Teams that don't will get visible label text bleeding into table selects — a cosmetic regression that looks like a bug and will generate tickets.
3. Cache keys are now scoped per Umami server and website. This is the correct fix (apps sharing a Redis store were previously reading each other's analytics), but it silently invalidates the existing key namespace. Expect a one-time cold fetch per widget on first load after deploy, and orphaned entries from the old scheme lingering until TTL.

Technical risk: low, with two non-obvious edges. The current() addition (returns null instead of throwing when the plugin isn't on the current panel) and the default-polling fallback remove a class of hard failures from mixed panels. The failure-path hardening means an Umami outage now degrades to empty widgets rather than an exception page — good for uptime, but it converts a loud failure into a silent one. Combined with "failed calls are not cached," a recovering Umami instance will take the full polling load from every open panel simultaneously; there is no evidence of backoff or jitter in the notes. Second edge: the Okabe-Ito palette change is an accessibility improvement but alters every chart's appearance — screenshots in internal runbooks, onboarding docs, and any dashboard annotated with "the blue line is X" become stale.

Key questions.

• For teams on Laravel 11: is there a maintained 2.0.x line receiving security fixes, and for how long? If not, what is our forced-upgrade date?
• Does the cache-key change leave unbounded orphaned entries in a shared store, or do the old keys expire on the existing TTL?
• Is there any retry/backoff on the Umami client, or does each widget retry independently on every poll?
• Does graceful degradation emit a log entry or any admin-visible signal when Umami is misconfigured (e.g. wrong base URL), or does a permanently broken integration look identical to "zero traffic"?
• Is FilamentUmamiPlugin::current() intended as the recommended guard from now on, and is the older throwing behaviour deprecated?

Integration Approach

Stack fit. Requires Filament 4/5 and Laravel 12 or 13. The dependency footprint shrank — the unused npm toolchain, empty testing mixin, and skeleton leftovers were removed, and the Composer package no longer ships screenshots or dev files. That trims installed size and removes a Node build step from our pipeline assumptions, but note the flip side: no Node means no local asset rebuild path, so any view-level customisation is pure PHP/Blade and must go through view publishing.

Migration path. Treat as a routine minor bump:

1. Confirm the target app is on Laravel 12+ and Filament 4/5. If on Laravel 11, stop — this release is not available to you.
2. Bump the constraint in a branch; run composer update and the full test suite.
3. If views are published, re-publish them and re-apply any local edits. Diff before overwriting — this is the one step the release notes bury.
4. Clear the application cache (or accept a cold-start) to avoid serving from the now-unused key namespace.
5. view:cache / optimize if the deployment pipeline uses it, so the new fi-sr-only classes are picked up.

Compatibility. No database migration, no config file changes required, no public API removals. The immutable-date fix (Date::useClass(CarbonImmutable::class)) matters specifically for apps that set that globally — previously a TypeError, now supported, so this release may unblock teams that had to work around it. The input-validation fix (invalid date range, row limit, or table option from the browser falls back to the default) closes a parameter-tampering path where a crafted request could pass arbitrary values into the upstream query; that is worth noting in our security review even though it presents as a robustness fix.

Sequencing. One PR, one deploy window. Do it early in a sprint rather than alongside a Filament major upgrade — the fi-sr-only behaviour is version-coupled to Filament 4/5 internals, and bundling the two makes attribution harder when something renders wrong.

Operational Impact

Maintenance. Very low. declare(strict_types=1) enforced by an architecture test, PHPStan at max on src and config with no baseline, 18 new tests, and Dependabot configured with grouped updates and a 3-day cooldown. The changelog workflow no longer hard-codes main, which matters if our fork or mirror uses a different default branch. No baseline on PHPStan max is the standout detail — it means the upstream project intends to stay warning-clean, which correlates with fewer surprise breakages at upgrade time.

Support. Expect a short bump in "widget is empty" tickets immediately post-deploy, from three causes: the cold cache, unreleased view caches, or genuinely unreachable Umami. Publish a one-line triage note for the service desk: empty widget + Umami reachable = stale views/cache; empty widget + Umami unreachable = expected, self-healing. The silent-degradation behaviour makes this triage necessary — previously the exception told you what was wrong.

Scaling. Unchanged and bounded by Umami's API, not by us. The per-server/per-website cache scoping actually improves multi-tenant correctness for anyone running several Umami properties from one application. The open concern is the recovery stampede: with failed calls deliberately uncached, N admin users with open panels will all hit a just-recovered Umami within one polling interval. For internal-tool-scale concurrency this is a non-issue; if we ever expose these dashboards broadly, revisit.

Failure modes. Umami down, slow, returning non-JSON, or missing keys → empty widget values, no page break, auto-recovery. Self-hosted Umami down during login → dashboard still loads; wrong credentials still raise a clear error (correct distinction). Plugin absent from panel → default polling interval. Bad browser-supplied parameters → defaults. Immutable dates → no TypeError. Shared cache store → no cross-tenant bleed. The residual failure mode is the invisible one: a misconfigured integration that never succeeds looks exactly like a site with no traffic.

Ramp-up. Effectively zero for developers — no new concepts, no config, one optional new static helper. The real onboarding cost is for whoever supports the dashboard: they need to know that empty charts are now a valid, expected state and where to look when they aren't. Budget fifteen minutes of documentation, not a training session. Recommend a follow-up ask to upstream for a debug/logging signal on failed Umami calls; until then, pair this upgrade with a monitoring check against the Umami health endpoint so "silently zero" can't persist unnoticed.