Weave Code
Laravel Umami Laravel Package
still-code/laravel-umami
Laravel Umami is a lightweight integration for the privacy-friendly Umami analytics platform. Easily add analytics to your Laravel application, track page views and custom events with Blade directives, middleware, and simple configuration—no cookies or complex setup required.
API wrapper for umami website analytics. get your stats in the laravel app
Frequently asked questions about Laravel Umami
- How do I install and configure still-code/laravel-umami in a Laravel app?
- Install it with composer require still-code/laravel-umami, then publish the package config file with php artisan vendor:publish. You set your Umami host/endpoint, website ID, and (for server-side event API calls) an API token via UMAMI_* environment variables. There is no database schema, migration, or queue worker requirement beyond what your app already runs.
- Which Laravel and PHP versions does laravel-umami support?
- The package is versioned in lockstep with Laravel majors, and the 5.0.3 release added Laravel 12 support. It targets conventional PHP 8.x Laravel monoliths and modular monoliths. Check the composer.json constraints on the tag you plan to use before pinning, since 5.0.x is the line aligned with current Laravel releases.
- Do I need a self-hosted Umami instance or can I use Umami Cloud?
- Either works, but you must have a reachable Umami deployment, whether self-hosted or Umami Cloud. You then mint a website ID for the property you are tracking and, if you use the server-side event API, an API token. Provisioning that instance is an infrastructure or procurement task, not a code change in your Laravel app.
- Does laravel-umami use cookies or require a GDPR consent banner?
- The cookie-less, privacy-friendly behavior comes from Umami itself, not from this wrapper. Because no tracking cookies are set, the usual cookie-consent prompt is generally unnecessary for basic pageview tracking. Be careful with custom event payloads, however: if you push emails, user IDs, or other PII into events, you reintroduce the consent and retention burden Umami is meant to avoid, and the package will send whatever you give it.
- How do I send custom events with payloads through laravel-umami?
- The package exposes a small surface for dispatching server-side events, typically via the provided facade or service binding, with an optional data payload. You call it from your controllers, jobs, or listeners wherever a meaningful action happens, such as signup or checkout. Keep payloads to non-identifying properties like plan name or feature flag so your analytics stay compliant.
- Can I track page views server-side, or do I need the Blade/JS snippet?
- You get both options: a Blade directive for injecting browser-side tracking and server-side pageview dispatch, which can be wired through middleware. Server-side tracking is reliable for request-level funnels but cannot capture JavaScript-only signals like scroll depth, clicks, or client-side SPA navigations. Many teams run the Blade snippet for rich browser metrics and use server-side events for backend-confirmed conversions.
- Are the Umami API calls synchronous or queued, and what happens if Umami is unreachable?
- This is the key thing to verify for your version before design sign-off, since an analytics wrapper can sit directly on the request path. If pageview tracking is middleware-driven and dispatched synchronously, a slow or down Umami endpoint can add latency or surface an error to the user. Wrap dispatch in a queued job or a try/catch with a short HTTP timeout so analytics failures never break a request.
- Does laravel-umami replace Laravel Telescope, Sentry, or application logging?
- No. It sits in the product analytics and observability layer, sending pageviews and events to Umami, and it does not do APM, error tracking, or structured logging. Keep Telescope for local debugging, Sentry for exceptions, and your log stack for diagnostics. Think of this package as a GA substitute for GDPR-conscious traffic analytics, not as a monitoring tool.
- How do I test my Umami integration without polluting real analytics data?
- Because events are HTTP calls to the Umami endpoint, you can fake them in tests with Laravel's Http::fake and assert the outgoing request URL and payload. Point the host config at a no-op or local Umami instance in your testing environment, or disable tracking via an environment flag. That keeps CI deterministic and avoids writing test traffic into production dashboards.
- Is still-code/laravel-umami actively maintained, and what are the alternatives?
- It is a single-maintainer community package with a modest contributor base, though the CI is healthy with active Dependabot updates and recent community pull requests. The 5.0.3 release is essentially a Laravel 12 compatibility patch plus tooling churn, so expect steady compatibility work rather than fast feature velocity. Alternatives are the official Umami tracking script used directly, hand-rolled HTTP calls to the Umami API, or switching to a different privacy-focused analytics backend; this package mainly saves you from writing and maintaining that glue code.
Weaver
How can I help you explore Laravel packages today?