Laravel Plausible Laravel Package

Getting Started

The package wraps two distinct Plausible concerns, and it's worth knowing which one you actually need before installing:

1. Server-side stats — querying the Plausible Stats API (visitors, pageviews, timeseries, breakdowns) from your Laravel app.
2. Client-side tracking — dropping the Plausible snippet into your Blade views without hand-editing layouts.

Install and publish the config first:

composer require kilobyteno/laravel-plausible
php artisan vendor:publish --tag=plausible-config

The published config/plausible.php is the first place to look. At minimum you need to decide whether you're on Plausible Cloud or self-hosted (self-hosted means pointing the API base URL at your own instance rather than the default), and you'll need a domain and an API key for anything stats-related. Put the key in .env — never commit it, since it grants read access to your analytics.

Your first use case should be the cheapest one: render the tracking script in your base layout. If that works and Plausible shows a live hit, your domain/config is correct and you can move on to the API side. If you start with stats queries you'll be debugging API keys and domains and script placement at the same time, which is a slow way to find a typo.

The release notes for 1.4.0 are almost entirely housekeeping — the only functional change is Laravel 13 support in the composer constraint, with the rest being GitHub Actions bumps. That means: no new features, no breaking changes, no migration steps. A composer update kilobyteno/laravel-plausible is sufficient. Run your test suite afterwards if you're on Laravel 13, but don't expect surprises.

Implementation Patterns

Keep the API key out of the client. The tracking script needs only your domain (public by definition). The Stats API key is a secret. Resist the temptation to build a dashboard that calls Plausible directly from the browser — proxy it through a controller or, better, cache it server-side.

Wrap stats calls in a service, not scattered in controllers. Plausible's Stats API is an external dependency with rate limits and latency. Something like App\Services\AnalyticsService that the package's facade calls into gives you one place to add caching, retries, or a feature flag to disable analytics calls entirely in local/test environments.

Cache aggressively. Stats data for anything older than "today" is effectively immutable. A 5–15 minute cache on timeseries and breakdown queries turns a dashboard with six cards from six API round-trips into a single warm read. Use Cache::remember() keyed on the query parameters, and give realtime/current-visitor queries a much shorter TTL (or none).

Gate dashboard routes. Any route rendering Plausible stats should sit behind your admin middleware. It's easy to ship an /analytics page that leaks traffic numbers publicly because it was built as a quick internal tool.

Conditional script rendering. In AppServiceProvider or a view composer, disable the tracking output when app()->isLocal() or when the user is authenticated as staff — otherwise your own team inflates the numbers on every page load. If the package exposes a config toggle or a runtime check, use it; otherwise wrap the Blade usage in your own @unless guard.

Multi-tenant setups need per-tenant domains. Since the config is global, either resolve the domain dynamically before rendering the snippet or maintain a small map of tenant → domain in your own code and pass it through. Don't fight the config file for this.

Testing: fake the HTTP layer rather than the facade where possible, so you're verifying the package actually builds the request you expect. Assert on the outgoing request URL and query string — that's where domain and filter mistakes surface.

Gotchas and Tips

Self-hosted vs cloud is the #1 source of 404s. If you self-host Plausible and leave the API base URL at the cloud default, every stats call fails with a confusing not-found rather than an auth error. Set the base URL explicitly.

The API key is not the site ID. Plausible's Stats API expects a domain string; the API key is a separate bearer credential. Mixing these up produces 401s that look like a key problem but are actually a wrong-domain problem, or vice versa. Log both (the domain, not the key) when debugging.

"No data" is not an error. Plausible returns an empty result set for a valid query over a period with no traffic — for example, a brand-new site or a filter that matches nothing. Make sure your code distinguishes an empty timeseries from a failed request, or you'll render broken charts on low-traffic days.

Filters are the fragile part. Plausible's filter syntax (event:page, visit:source, etc.) is string-based and unforgiving. Typos don't throw — they silently return zeros or unfiltered data depending on the endpoint. Build filter arrays through a small helper with named constants rather than hand-writing strings in ten controllers, and test one filtered query explicitly.

Timezones and date ranges. Plausible keys data to the site's configured timezone, not your app's. A "today" query computed with now() in a different timezone will be subtly wrong at the edges of the day. Be explicit about the period string you send.

Rate limits exist and are per-account. Dashboards that poll multiple endpoints on every page load will hit them under any real traffic. Server-side caching isn't an optimisation here, it's the design.

Extension points are limited by design. This is a thin wrapper. If you need request middleware, retry logic, or logging of Plausible calls, put it in your own wrapper class around the facade — don't fork the package for it. The maintenance cadence here is mostly Dependabot, so upstream feature requests move slowly.

Version constraints: 1.4.0 widens support to Laravel 13. If you're pinned below Laravel 12, nothing changes for you. If you're on Laravel 13 and were holding back, this release unblocks the upgrade — but check your other analytics/tracking packages too, since they rarely move in lockstep.

Debugging order when something returns nothing useful: (1) is the domain string exactly right, including any subdomain, (2) cloud vs self-hosted base URL, (3) is the API key valid and unscoped, (4) does the same query return data in the Plausible UI itself. That last step separates "package problem" from "no traffic / wrong site" faster than any amount of logging.