Laravel Umami Laravel Package

Getting Started

still-code/laravel-umami is a thin integration layer that injects the Umami analytics tracker into your Laravel app and exposes a small API for server-side event tracking. Release 5.0.3 is maintenance-only — Dependabot bumps plus Laravel 12 support (PR #39) — so there are no migrations or breaking changes, but it unblocks installs on Laravel 12 projects.

1. composer require still-code/laravel-umami — on Laravel 12 you now need ^5.0.3; earlier 5.x tags will fail dependency resolution against laravel/framework ^12.0.
2. php artisan vendor:publish --tag="umami-config" and open config/umami.php first — it is the source of truth for every option discussed below.
3. Set the essentials in .env: UMAMI_ENABLED=true, UMAMI_WEBSITE_ID=<uuid-from-umami-dashboard>, and UMAMI_HOST=https://cloud.umami.is (or your self-hosted instance, e.g. https://analytics.example.com). There is no trailing slash on the host.
4. Render the tracker in your layout: @umami / <x-umami::script /> (check the config/README of the installed version for which is registered) just before </head>.
5. First real use case: pageview tracking on a public marketing site. Flip UMAMI_ENABLED off in config/umami.php for local/testing so your dev traffic doesn't pollute dashboards; keep it driven by env so staging can be toggled independently.

Implementation Patterns

Layout-level injection. The intended path is one include in resources/views/layouts/app.blade.php. Everything else — script URL, data-website-id, data-domains, data-auto-track, data-do-not-track — flows from config, so you never edit Blade when the marketing team moves from cloud to self-hosted.

Env-driven multi-environment setup. Standard pattern:

UMAMI_ENABLED=true
UMAMI_WEBSITE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
UMAMI_HOST=https://analytics.example.com
UMAMI_TRACK_LOCALHOST=false

Keep UMAMI_ENABLED=false in phpunit.xml and .env.testing. Because the flag is read at boot, config:cache in deploy pipelines will freeze the value — ensure the deploy env is set before artisan config:cache runs.

Server-side events (the reason to use the package over a raw <script>). When the config exposes the Umami /api/send endpoint, use it for conversions you can only trust server-side: registration completed, subscription upgraded, webhook-driven outcomes. Fire it from a listener or job, not the controller, and wrap in try/catch — analytics failures must never fail a checkout flow. Pass a stable, low-cardinality event name and keep data/payload keys consistent across releases so Umami's dashboard aggregations hold.

Multi-tenant / multi-site apps. If one Laravel instance serves several brands, publish the config but resolve website ID at runtime (per-tenant setting, or a config override in a middleware) rather than reading the env value directly in the Blade partial. Guard against a null ID — an injected script with an empty data-website-id silently collects nothing, which is worse than a visible error.

Livewire / Inertia / SPA navigation. Umami auto-tracks history changes, but only if your router actually pushes state. For Inertia this generally works; for Livewire wire:navigate verify pageviews land in the dashboard before assuming it's handled, and otherwise call umami.track() manually on navigation events.

CSP and consent. If you run a strict Content-Security-Policy, add UMAMI_HOST to script-src and connect-src. For GDPR-sensitive projects, gate rendering behind your consent manager (an Alpine/JS check or a Blade @if(cookie('consent'))) rather than enabling DNT handling and hoping.

Gotchas and Tips

• Laravel 12 constraint is the only material change in 5.0.3. If you're on L11, staying on 5.0.2 costs you nothing functional; both tags are content-equivalent outside the dev-dependency bumps. Don't schedule an upgrade solely for this release.
• Empty website ID = silent no-op. The most common support question. Confirm the UUID matches the site in the Umami dashboard and that you're pointing at the matching host (cloud IDs don't work on self-hosted instances and vice versa).
• Host URL traps. Include the scheme, omit the trailing slash, and remember self-hosted instances are often served under a subpath (https://example.com/stats) — the package appends /script.js, so a missing subpath yields a 404 that's only visible in DevTools.
• config:cache staleness. If the tracker stops rendering after a deploy, php artisan config:clear locally and check your CI deploy order before touching package code.
• Ad blockers. Umami is usually not blocked, but corporate proxies can be. Don't debug "missing events" for an hour without an incognito check.
• Testing. Assert the <script> tag is present or absent per env with a simple assertSee('data-website-id'). Because the flag is config-driven, config(['umami.enabled' => true]) in the test is more reliable than env manipulation.
• Extension points are limited by design. This is a script-injection wrapper, not a full SDK; if you need queueing, retries, or event batching server-side, write your own thin Umami HTTP client behind an interface rather than fighting the package's surface. That also keeps you upgrade-safe.
• Watch the repo cadence. 5.0.3 is the first release with a new contributor and Laravel 12 support after a quiet Dependabot-only stretch — a good sign, but verify the README documents the Blade component/directive name for your installed version, since docs have lagged releases here before.