Weave Code
Laravel Client Laravel Package
simplestats-io/laravel-client
A lightweight Laravel client for Simple Stats, the privacy-friendly, cookie-free analytics platform. Track pageviews and custom events from your app using a clean API, Blade directives, and middleware, with GDPR-friendly defaults, simple configuration, and no complex setup required.
Official Laravel Client for SimpleStats
Frequently asked questions about Laravel Client
- How do I install simplestats-io/laravel-client in a Laravel app?
- Install it with composer require simplestats-io/laravel-client, publish the package config, and set your SimpleStats site key in the environment file. Then add the tracking middleware to your web group or place the Blade directives where you want tracking to run. There are no migrations, tables, or other infrastructure to set up.
- Which Laravel and PHP versions does this package support?
- Check the require block in composer.json on Packagist for the exact Laravel and PHP constraints, since those are authoritative. The package is on the 5.x line with 5.1.0 as the current minor and targets modern Laravel releases. Pin the constraint you have tested rather than relying on a floating version.
- Can I track pageviews in Laravel without adding JavaScript?
- Yes. Add the CheckTracking middleware to your web middleware group and the package records pageviews server-side, with no client-side script required. Blade directives are also available for finer control, such as skipping tracking on selected views or emitting events from templates.
- How do I send custom events to SimpleStats from Laravel?
- Custom events go through the package's tracking API, where you pass an event name and optional properties. Events are forwarded server-side to SimpleStats, so they work without any browser JavaScript. Use them for signups, checkouts, or other conversions you want alongside pageviews.
- Why are pageviews missing when my Laravel or Statamic site uses full-page caching?
- When a page is served from Statamic full measure, nginx or Varnish, or Cloudflare Cache Everything, PHP never executes, the middleware is never invoked, and those visits simply do not reach SimpleStats. The beacon in 5.1.0 is the fallback: a same-origin request that lets the server derive the page path and utm parameters from the Referer, with a noscript pixel as an extra fallback. It is a data-correctness fix for cached sites, not an upgrade over server-side tracking where PHP still runs.
- How do I enable the SimpleStats beacon and what do I need to configure?
- The beacon is off by default and inert until you add the config key, so publish the config and enable the beacon option first. Then add the beacon route block, place the layout snippet including the noscript pixel in your Blade layout, and choose a path your cache and CDN rules exclude. Verify it with caching enabled and review Referrer-Policy, catch-all route precedence, and www versus apex handling, since the pixel request must be same-origin with the page.
- Is upgrading to 5.1.0 a breaking change for my Laravel app?
- For most applications the upgrade is a no-op because the beacon is off until configured. However, CheckTracking::getPage() and doTracking() gained an optional parameter, so any subclass or internal wrapper that overrides those methods without it will fatal at boot with an incompatible declaration. Audit subclasses before rolling out; a new method or a major bump would have been the safer vendor choice.
- Is the beacon endpoint a security or abuse risk?
- It is an unauthenticated GET route that accepts arbitrary query parameters, performs bot filtering, and forwards to the SimpleStats API. Dropping foreign-referer requests reduces accidental inflation from mirrored or scraped HTML, but the Referer header is client-controlled, so that check is not a rate limit. Add route throttling, CDN or WAF rules, and confirm your API quota exposure before enabling it in production.
- Is this package GDPR compliant and cookie-free?
- The client is cookie-free and ships privacy-friendly defaults, so it avoids analytics cookies and the consent banner that usually comes with them. You should still review what data you send, how IP hashing is handled, and your own processor agreement with SimpleStats for your jurisdiction.
- Will the beacon double-count pageviews that the middleware already tracked?
- Deduplication between a cache-miss app response and the beacon for the same page is claimed, but verify it under real conditions such as back/forward cache restores, prerender and Speculation Rules prefetch, and retried fetches. Keep server-side tracking wherever PHP still runs and treat the beacon strictly as a fallback for static responses. Any visits collected only through the beacon during a trial disappear from the series if you roll back.
Weaver
How can I help you explore Laravel packages today?