Weave Code
Laravel Umami Laravel Package
atm-code/laravel-umami
Laravel integration for Umami, the privacy-friendly, cookieless analytics platform. Add tracking snippets to your Blade views, query stats through a fluent API client, and keep visitor data self-hosted and GDPR-friendly without cookies.
API wrapper for umami website analytics. get your stats in the laravel app
Frequently asked questions about Laravel Umami
- How do I install atm-code/laravel-umami in a Laravel app?
- Install the package with Composer, publish the package configuration, and set your Umami website ID and host through environment variables. The published config file is config/umami.php. After configuration, add the tracking directive to your base Blade layout and confirm the script renders.
- Which Laravel and PHP versions does laravel-umami support?
- Version 5.0.3 adds Laravel 12 compatibility and is a backwards-compatible patch within the 5.x line. The package is a best fit for Laravel 10, 11, and 12 with PHP 8.1 or newer. Check the Composer constraints for the exact supported matrix before upgrading.
- How do I add Umami tracking to Blade views?
- The package is designed to inject the Umami client-side tracking script through a Blade directive, typically placed in your base layout. Add the directive once in the shared layout so normal server-rendered page loads are tracked. Then verify the rendered HTML and confirm pageviews arrive in your Umami instance.
- Does laravel-umami work with Inertia, Livewire, or SPA route changes?
- Blade-based injection assumes server-rendered HTML, so client-side route changes may not emit pageviews automatically. Inertia navigation, Livewire wire:navigate, and Turbo visits can require manual instrumentation per route change. Test against your actual front end before assuming out-of-the-box coverage.
- Can I query Umami stats from Laravel with this package?
- Yes, the package exposes a fluent API client for retrieving Umami website statistics inside your Laravel application. You can use it for dashboards, reports, or internal analytics views without leaving PHP. It still requires a reachable Umami instance configured with your host and website ID.
- Is laravel-umami GDPR-friendly and cookieless?
- Umami is cookieless and self-hosted by design, which materially simplifies GDPR and CCPA conversations compared with GA4. This package inherits that posture because it integrates with your Umami instance rather than adding its own cookie-based tracking. You remain responsible for the data residency and operation of your self-hosted endpoint.
- Do I need to self-host Umami to use this package?
- The package is an integration layer for an Umami instance; it does not bundle the analytics server itself. You need access to a running Umami deployment, whether self-hosted or otherwise managed, and its website ID and host configured in Laravel. Self-hosting is the common setup because it keeps visitor data under your control.
- Why am I not seeing pageviews or analytics data in Umami?
- Analytics failures are intentionally non-fatal, so problems often appear as missing data rather than application errors. Check that the Blade directive renders, that content security policy and ad blockers are not blocking the script, and that the website ID and host are correct. For SPA-style navigation, also confirm that each route change is instrumented.
- How do I handle consent and exclude admin or API routes from Umami tracking?
- The technical evaluation lists consent kill-switches and route scoping as items to verify, so do not assume built-in consent enforcement. In practice, conditionally render the Blade tracking directive only after consent is granted. Keep it out of admin, API, and health-check layouts or middleware paths where analytics is unnecessary.
- Is atm-code/laravel-umami production-ready and actively maintained?
- It is a small, single-maintainer package with a thin integration surface, so the main risks are supply chain and bus factor rather than runtime complexity. Version 5.0.3 is a patch release whose functional change is Laravel 12 compatibility, with release content otherwise dominated by CI dependency updates. Pin the version, review diffs on upgrade, and run your test suite before deploying.
Weaver
How can I help you explore Laravel packages today?