Laravel Umami Laravel Package

Technical Evaluation

Architecture fit. still-code/laravel-umami is a thin, opinionated integration layer between a Laravel application and a self-hosted Umami analytics instance. It does not add an architectural tier — it injects a client-side tracking script (typically via a Blade directive in the base layout) and exposes a small server-side surface for forwarding events. For a Laravel monolith or a Blade/Livewire-rendered app this is a near-zero-friction fit. For an API-only or Inertia/SPA front end, the value drops sharply, because the package's core convenience (layout injection) assumes server-rendered HTML.

Integration feasibility. High. Published on Packagist, installable via Composer, config published to config/umami.php with environment-driven website ID and host. The realistic effort is measured in hours, not days, and most of that is standing up or pointing at a Umami instance, not wiring the package.

Technical risk. The dominant risks are not in the code path but around it:

• Supply chain / bus factor. A small, single-maintainer package. 5.0.3 accepts a first-time contributor's Laravel 12 support PR — healthy signal for community, but it also means compatibility-critical changes are landing without a long track record. Pin the version and review diffs on upgrade.
• Release content is mostly CI hygiene. Of the five merged PRs, four are Dependabot bumps to GitHub Actions (fetch-metadata, laravel-pint-action). These carry no runtime effect. The only functional change is Laravel 12 compatibility.
• Silent degradation. Analytics failures are, by design, non-fatal. That is correct behaviour but means breakage (ad blockers, CSP, host downtime, wrong website ID) surfaces as missing data weeks later, not as an error.
• Compliance posture is a genuine positive. Umami is cookieless and self-hosted, which materially simplifies GDPR/CCPA conversations versus GA4. The package inherits that, but the self-hosted endpoint's data residency becomes your responsibility.
• SPA/turbo navigation gap. Client-side route changes in Inertia, Livewire wire:navigate, or Turbo may not emit pageviews without manual calls. Verify against your actual front-end before assuming out-of-the-box coverage.

Key questions for the maintainer / spike.

1. Which Umami server versions (v2 API) are supported, and is the server-side event path version-pinned?
2. Does the client script handle SPA/turbo navigations, or must each route change be instrumented manually?
3. What is the test matrix for Laravel 9/10/11/12 and PHP 8.1–8.4?
4. Does the middleware respect a consent/config kill-switch, and can it be scoped to exclude admin, API, and health-check routes?
5. What is the release cadence and stated support window for the current major?

Integration Approach

Stack fit. Best fit: Laravel 10/11/12 with Blade-rendered views, PHP 8.1+. Acceptable fit: Livewire apps (with per-navigation instrumentation). Poor fit: headless/API-only backends, or teams unwilling to operate a Umami instance.

Compatibility. 5.0.3 is a patch release within the 5.x line — no breaking changes, no config or API surface changes, no deprecations. The Laravel 12 addition is additive and backwards-compatible. Any application already on 5.0.2 can take this with a routine composer update and no code changes.

Migration path.

• From 5.0.x: trivial. Bump the constraint, run the test suite, confirm the directive still renders in the base layout. No published config or asset changes.
• From 4.x: out of scope for this release — the major-version boundary was crossed earlier. If you are still on 4.x, treat that as a separate upgrade with its own review; do not treat 5.0.3 as the migration vehicle.
• From GA4 or nothing: additive. Run both in parallel for one to two weeks and reconcile pageview counts before decommissioning the incumbent.

Sequencing.

1. Spike (0.5 day). Install in a scratch branch; stand up a throwaway Umami instance via Docker; confirm pageviews and one server-side event land.
2. Front-end audit. Enumerate navigation patterns (full loads vs. client-side). Decide whether manual route instrumentation is needed.
3. Staging rollout. Wire config via environment variables, not committed files. Confirm CSP allows the Umami host and that the script is not blocked by an existing consent manager.
4. Route scoping. Exclude admin, API, and health endpoints from any middleware-driven tracking to avoid polluting the dataset.
5. Production, behind a flag. Ship with the website ID unset in the deploy config, then enable per-environment once staging data reconciles.
6. Pin and document. Lock the minor version in composer.json, record the Umami server version, and note the upgrade-review owner.

Operational Impact

Maintenance. Low code-maintenance burden — the package is a few hundred lines of glue. The real ongoing cost is the Umami instance: container/host patching, database backups, retention policy, and TLS. Budget for that explicitly; it is often larger than the integration itself.

Support. No commercial support, no SLA. Escalation path is GitHub issues on a volunteer timeline. Mitigation: the package is small enough to fork and vendor internally if it goes stale — a genuine advantage of thin wrappers. Keep a named internal owner for both the package and the Umami host.

Scaling. The package itself does not scale — it emits an HTTP request per tracked interaction. Throughput concerns belong to the Umami instance and its backing database. At high traffic, watch for the tracking endpoint becoming a hot path and consider sampling or edge-side collection. Server-side event forwarding doubles the outbound request count; measure before enabling broadly.

Failure modes and blast radius.

The critical design property to enforce: analytics must never be able to break page rendering or fail a request. Verify the package's script tag is non-blocking and that any server-side call is wrapped in a try/catch or queued.

Ramp-up. Low. A mid-level Laravel engineer can complete the integration and verification in under a day. The Umami instance setup is another half day for someone comfortable with Docker and a reverse proxy. No specialised analytics knowledge is required to operate it; interpreting the data is the harder half and is outside this package's scope.

Recommendation. Adopt 5.0.3 for Blade-rendered Laravel apps where privacy-friendly, self-hosted analytics is a requirement. Treat the release itself as low-risk housekeeping — the Laravel 12 support is the only substantive change and it is additive. Gate the decision on two things: a confirmed owner for the Umami host, and a front-end audit confirming pageview coverage for your navigation model.