Laravel Umami Laravel Package

Technical Evaluation

still-code/laravel-umami is a thin Laravel integration for Umami, the self-hosted, privacy-focused, cookie-less analytics platform. Architecturally it sits in the "observability/analytics" layer alongside first-party event tracking: it is not a logging or APM tool, and it does not replace Laravel Telescope, Sentry, or structured logging. Its architectural fit is therefore narrow but clean — teams that have already chosen (or are evaluating) Umami as a GA substitute for GDPR-conscious web analytics get an idiomatic Laravel wrapper (config publishing, facade/service bindings, Blade directive / middleware-style pageview tracking, and server-side event dispatch) rather than hand-rolling HTTP calls.

Integration feasibility is high. It is a Composer package installable via composer require still-code/laravel-umami, with a published config file and a small public surface (track pageviews, send custom events with optional payload). There is no database schema, no queue worker requirement beyond what the app already has (events are HTTP calls to the Umami instance), and no service provider conflicts expected. The main feasibility constraint is external: you must operate or contract a reachable Umami instance (Umami Cloud or self-hosted) and mint a website ID and, for server-side event API usage, an API token. That is a procurement/infra task, not a code task.

Technical risk is moderate-low but concentrated in three areas. First, supply chain and bus factor: this is a single-maintainer community package with a modest contributor base; the 5.0.3 release is almost entirely Dependabot CI bumps plus one community contribution. That is a positive signal (CI hygiene, active dependabot) but it also means feature velocity and security-response capacity are limited. Second, telemetry blast radius: an analytics wrapper sits on the request path if pageview tracking is middleware-driven, so a slow or unreachable Umami endpoint can translate into latency or, if implemented synchronously, user-facing errors. Confirm the package's dispatch model (sync HTTP vs. queued job) before design sign-off. Third, privacy/compliance claims: "cookie-less and GDPR-friendly" is a property of Umami, not of this wrapper; if you route PII into custom event payloads you reintroduce the exact consent burden Umami is meant to avoid, and the package will happily send it.

Key questions to resolve before adoption: (1) Does the package dispatch server-side events synchronously or via the queue, and can that be configured? (2) What is the retry/timeout behavior on a failed Umami call, and does failure ever surface to the end user? (3) Is there an existing Umami deployment in the org, and who owns it (SRE vs. product analytics)? (4) What is the data-retention and PII policy for custom event payloads? (5) Do we need client-side (browser) tracking too, in which case a Blade snippet or JS tag is required in addition to this package, or is server-side event tracking sufficient for our funnel questions?

Integration Approach

Stack fit is good for a conventional Laravel monolith or modular monolith on PHP 8.x. The package is versioned in lockstep with Laravel majors, and 5.0.3's headline change — Laravel 12 support (#39) — is the operationally meaningful line in these release notes. Everything else in 5.0.3 is CI/tooling churn (dependabot/fetch-metadata 2.1.0 → 2.4.0, aglipanci/laravel-pint-action 2.4 → 2.5) and carries no runtime impact. Treat 5.0.3 as a compatibility patch, not a feature release.

Migration path is trivial from a prior 5.0.x: this is a patch bump with no breaking changes flagged, no deprecations, and no config or API surface changes indicated in the changelog. From 4.x, the 5.0 major was the real migration event and should already be complete; 5.0.3 does not reopen it. For teams not yet on the package, "migration" is really an adoption: publish config, set UMAMI_* environment variables, register the website ID, and wire tracking into the layouts/middleware or explicit event calls.

Compatibility notes to verify in the PR that performs the upgrade: confirm the package's illuminate/* constraints actually admit ^12.0 (the PR title says Laravel 12 support, but verify the released constraint), confirm PHP 8.2+ floor, and confirm no transitive dev-dependency bumps leaked into require (Dependabot PRs in this repo are scoped to GitHub Actions, which is reassuring, but verify the composer.json diff). Also confirm Laravel 12's application bootstrap/skeleton changes don't affect any published config or provider auto-discovery.

Sequencing recommendation: (1) upgrade to 5.0.3 in a branch on a non-production environment and run the existing test suite plus a smoke test that emits a pageview and a custom event against a staging Umami instance; (2) land it behind the Laravel 12 upgrade if you are mid-migration, or independently if you are already on Laravel 12 and were previously blocked on this package; (3) defer any new instrumentation (custom events, funnels) to a follow-up change so the compat bump stays a low-risk, easily-revertable deploy.

Operational Impact

Maintenance burden is low in steady state and dominated by version-tracking, not code. The package itself is small; the recurring work is (a) keeping it aligned with Laravel majors — historically this has been prompt (Laravel 12 support arrived as a community PR), and (b) upgrading the Umami server, which is a separate, self-hosted product with its own release cadence, database migrations (typically Postgres), and Docker/Helm upgrade path. Budget for two upgrade streams, not one, and note that the package's server-side event API compatibility is coupled to the Umami API version you run — pin both and upgrade them together.

Support posture: expect community-only support (GitHub issues, no SLA, no vendor). Do not place this on a path where a regression blocks revenue. Internal ownership should sit with the team that owns marketing/analytics instrumentation, with SRE owning the Umami instance itself.

Scaling characteristics are favorable and worth stating plainly: because Umami is self-hosted and cookie-less, there is no third-party quota, no per-event vendor billing, and no data-egress-to-a-vendor concern. The cost center shifts to your own infrastructure — one modest Postgres-backed service handles substantial traffic, but you inherit its backup, HA, and capacity planning. On the application side, the risk is request-path overhead: if pageview tracking is middleware-driven and synchronous, every web request gains an HTTP round trip to Umami. At high volume this argues strongly for queued dispatch and a local/co-located Umami endpoint.

Failure modes to design against: Umami unreachable or slow (mitigate with queue + short timeout + fail-open — analytics loss is acceptable, user-facing errors are not); misconfigured website ID or missing API token, which typically fails silently and produces a silent analytics black hole that nobody notices for weeks (mitigate with a synthetic canary event and a dashboard/alert on ingest volume dropping to zero); schema drift after an Umami server upgrade breaking event payload shape; PII leakage into custom event payloads, which quietly converts a compliance-friendly tool into a compliance liability; and abandonment of the package by its single maintainer, for which the mitigation is the fact that the wrapper is thin — the escape hatch is to inline the handful of HTTP calls it makes, so keep the integration surface confined to a small internal service class rather than scattering facade calls through controllers.

Ramp-up is genuinely small: an experienced Laravel developer can read the package and complete a first integration in under a day, and the operational learning curve is mostly on the Umami side (deployment, dashboard setup, funnel/report configuration) rather than the PHP side. The assessment that matters for a go/no-go is not "is this package good" — it is "does the org want to own a self-hosted analytics platform." If yes, 5.0.3 is a clean, low-risk, Laravel 12-ready pin. If no, the package's quality is irrelevant.