Download the PHP package sergeybruhin/laravel-analytics without Composer

sergeybruhin/laravel-analytics

First-party, event-based analytics for Laravel apps — visitors, sessions, pageviews, and generic named events (goals) — with a pluggable storage driver. Ships one fully-built driver (Postgres) today; a higher-volume driver (e.g. ClickHouse) can be added later without touching the ingestion path, the queue job, or the frontend tracker.

This package is completely independent of any third-party analytics vendor. It has no concept of Yandex Metrika, Google Analytics, or any other SaaS — no ym_client_id-shaped field, no vendor goal registry, nothing. If a host app also runs a vendor tag, the two simply don't know about each other.

Why

Vendor analytics tools own your data and rarely let you join it against your own schema (a cart, an order, a customer). This package gives a host app a first-party visitor → session → pageview/event log it can query, join, and own outright — while staying small enough to run in the same database as the app itself for a low-volume install.

Requirements

• PHP ^8.2, Laravel ^12.0
• The Postgres driver (the only one shipped) requires a PostgreSQL connection — same database as the app, or a separate instance/host.

Installation

Once published on Packagist:

Until then (or to track a specific tag/branch directly from GitHub), add a VCS repository to the host app's composer.json first:

then run the same composer require command above.

The service provider auto-registers via Laravel package discovery.

Publish config and migrations, then run them against the analytics connection specifically — a plain php artisan migrate would silently skip them:

Or run all three in one step:

This package's own hard rule, matching this repo's CLAUDE.md: never run migrate (or analytics:install, which calls it) automatically from tooling — always hand these commands to whoever operates the app.

Configuration

Set in .env:

Full list with comments: config/laravel-analytics.php.

Queueing

All storage writes happen on a queue — the collect endpoint only validates and dispatches, then returns 202 immediately, so a slow or unavailable analytics database never delays a request. Add a dedicated queue connection (own retry_after, since analytics writes are best-effort and shouldn't compete with app-critical queues):

If you run Horizon, add a supervisor for it (short tries/backoff — a dropped analytics hit is not worth retrying aggressively):

CSRF exemption

sendBeacon cannot attach custom headers, so the collect endpoint must be CSRF-exempt:

The endpoint is protected instead by request throttling, an origin/referrer check, and strict payload validation (see "Security model" below).

Frontend

resources/js/tracker.ts is a reference implementation, not a publishable asset — copy it into your own Vite build and adapt the two marked "integration point" spots (UTM/click-id extraction, and the CSRF posture of the delivery call) to your project's own conventions. It has no dependency on any specific host project's CustomEvents, UTM helper, or CSRF helper.

Public API once loaded:

Behavior:

• Automatic pageview on load; duration_ms is filled in on the next flush or on unload (pagehide / visibilitychange), whichever comes first.
• Hits batch in memory and flush every 5s, at a 20-hit cap, or on unload via sendBeacon (falling back to fetch(..., {keepalive: true})).
• Every event gets a client-generated dedup_key so a retried/duplicate flush can't double-count it (pageviews are not deduplicated — there is no equivalent guarantee needed, a duplicate pageview is harmless).
• Visitor id: crypto.randomUUID() in localStorage (qskn_vid). Deliberately a separate identifier from any cart/session id the host app already keeps — don't repurpose an existing one.

Backend: writing events from PHP

Resolve the Analytics class from the container anywhere server-side — e.g. to record a purchase that doesn't depend on client-side JS having fired:

Do this from a queued listener on your own domain event (e.g. OrderPlaced), not inline in a controller — keep the analytics write off the request path that has to succeed for checkout.

Data model

Four tables on the analytics connection, all carrying a site column:

• visitors — one row per anonymous visitor (uuid id). First-touch utm_*/click-id fields, set once and never overwritten. Optional external_id + traits (jsonb) once identify() is called.
• sessions — one row per session (uuid id), FK to visitor. Last-touch utm_*/click-ids (a non-direct hit overwrites these; a direct hit doesn't), device/browser/OS, is_bot, truncated IP.
• pageviews — one row per page load. url, path, referrer, title, duration_ms.
• events — one generic row per named event (purchase, add_to_cart, signup, anything). name, properties (jsonb), value (nullable numeric), dedup_key (unique per site).

The package has no ecommerce-specific tables or columns — events is intentionally generic. Only utm_source/medium/campaign/content/term are normalized columns; everything else platform- or app-specific (click ids, event properties, identify traits) is JSON.

IPs, when stored at all, are truncated (last IPv4 octet / last 80 bits of IPv6 zeroed) before being persisted — never the raw address. Disable entirely with ANALYTICS_STORE_IP=false.

Security model

The collect endpoint is anonymous and unauthenticated by design. It's protected by, in order:

1. throttle:analytics-collect — 300/min per visitor (visitor_id + IP) with a 3000/min per-IP backstop, so one person behind a NAT can't switch ingestion off for the rest of the building while a rotated visitor_id still buys nothing. Tune with ANALYTICS_RATE_LIMIT_PER_VISITOR / ANALYTICS_RATE_LIMIT_PER_IP; set both to 0 to turn throttling off where a CDN or WAF already does it.

   A named limiter, deliberately. Laravel keys the throttle:n,m shorthand on sha1($domain.'|'.$ip) — the route isn't in the key — so every shorthand throttle in a host application shares one counter per visitor IP, and the host's strictest route silently pays for this endpoint's traffic. A tracker flushing every five seconds would then start refusing the host's checkout. A named limiter is keyed on md5($limiterName.$key) and can never do that.

   Define your own analytics-collect limiter in an application provider to override it entirely — application providers boot after package ones, and the last registration for a name wins.

2. VerifyAnalyticsOrigin — compares Origin/Referer against config('app.url'). A mismatch gets a silent 202 no-op, never a 403, so a prober can't distinguish "blocked" from "accepted."
3. CollectRequest — strict shape validation: batch capped at 20 hits, event names restricted to ^[a-z0-9_.-]{1,191}$, properties capped at 4KB encoded.
4. site is always taken from server config (laravel-analytics.site), never from the client payload.

Bots are detected (jenssegers/agent + a UA-substring blocklist) and flagged (is_bot = true), not silently dropped — so your exclusion rate stays auditable instead of just disappearing.

Retention

Deletes pageviews/events older than ANALYTICS_RETENTION_DAYS (plain DELETE, not partition-drop — fine at the small-to-medium scale this driver targets). Register it on your scheduler:

Nova reporting (optional, Postgres driver only)

Register AnalyticsVisit (read-only) as a Nova resource, and add PageviewsTrend/TopTrafficSources to a dashboard's cards(). This reporting layer is Postgres-specific; a future driver would need its own, or a host can point an external BI tool at whichever store is active.

Adding a storage driver

Implement SergeyBruhin\Analytics\Contracts\AnalyticsStore and register it via DriverManager::extend():

Every contract method receives a flat, fully denormalized attribute array — no method may assume the driver can join across tables to fill in a value, since not every backend (e.g. ClickHouse) has foreign keys or row- level unique constraints. Nothing in CollectController, RecordAnalyticsHitJob, or the frontend tracker changes when a new driver is added.

Testing

The suite (tests/) uses Orchestra Testbench and runs the Postgres driver against a real Postgres connection — set ANALYTICS_TEST_DB_HOST / _PORT / _DATABASE / _USERNAME / _PASSWORD to point it at a disposable database/schema before running.

Changelog

See the GitHub releases for a version history.

License

MIT — see LICENSE.md.