Tracker Laravel Package

Getting Started

• Install with composer require pragmarx/tracker. As of v4.0.0 the package declares support for PHP >= 7 and Laravel 7 — that is both a floor and, in practice, the ceiling you should assume until a newer release says otherwise. On Laravel 8+ verify (or fork) before committing; on Laravel 6 or older PHP, pin to the 3.x line.
• If you are upgrading an existing install, treat the v4 major bump as breaking: diff the published config/tracker.php and migrations against what you already have before running php artisan migrate, and re-publish only the files you actually need.
• Publish the config and migrations using the provider/tags documented in the README. Look first at config/tracker.php, the published migrations, and the package middleware class. Those three files determine whether tracking is enabled, where data is stored, and what gets recorded.
• Run the migrations and inspect the created tables before using them in production. You should see tables for sessions, visitors, page views, routes, agents/devices, referrers, geo data, and possibly events/errors/logs depending on version.
• Register the tracker middleware for the routes you actually want to measure. For a normal Laravel 7 web app, put it in the web group or a route group after session/auth middleware. Do not enable it globally on admin, health-check, webhook, or asset routes.
• First use case: enable tracking on a staging site, browse a handful of pages, then query recent sessions/page views to prove the data is usable. Example:

use PragmaRX\Tracker\Vendor\Laravel\Models\Session;

$sessions = Session::with(['visitor', 'pageViews.route'])
    ->latest('started_at')
    ->limit(20)
    ->get();

If rows appear with page views, referrers, and visitor data, you have enough to build a simple internal dashboard. Start there rather than trying to replace a full analytics platform.

Implementation Patterns

• Use middleware-driven tracking for classic server-rendered pages. This is the package's sweet spot: every request in the selected route group produces a session/page-view record without controller code.
• Be selective with middleware. Apply it per route group or per environment so you can exclude admin panels, API health checks, asset routes, and anything containing sensitive query strings.
• Query the published Eloquent models for custom dashboards instead of depending only on the package UI. Typical panels are recent sessions, unique visitors, top routes, referrer breakdown, device/browser mix, and logged-in vs guest traffic.
• Build “top pages” style reports with aggregate queries over page views and routes:

use PragmaRX\Tracker\Vendor\Laravel\Models\PageView;
use Illuminate\Support\Facades\DB;

$topPages = PageView::query()
    ->select('route_id', DB::raw('count(*) as views'))
    ->with('route')
    ->groupBy('route_id')
    ->orderByDesc('views')
    ->limit(10)
    ->get();

• Associate sessions with authenticated users through the package config/user resolver. That lets you answer practical questions like “which pages do trial users hit before upgrading?” and “what did this support user’s last session look like?”
• For SPAs and JSON APIs, do not assume the middleware captures every client-side navigation. The auto-tracker sees HTTP requests, not front-end route changes. Add explicit tracking at meaningful API/controller boundaries, or record page views/events through the package models/service when the built-in request tracking is too coarse.
• Use event tracking for business actions rather than only page views: signup, checkout start, purchase, export, invite sent. If the package’s event API fits your version, use it; otherwise insert into the published event table through a small service class and keep the event names stable.
• Schedule pruning/archiving. Visitor tracking tables grow quickly. Keep raw sessions for a short window, aggregate older data into summary tables, and prune on a schedule.
• Treat this as an internal analytics/audit tool, not a compliance-ready analytics platform. Sanitize IPs where required, honor consent/Do Not Track, and avoid storing sensitive query parameters.

Gotchas and Tips

• Pin deliberately. v4.0.0 is the newest tag and targets PHP >= 7 / Laravel 7; the project has no listed dependents and no newer compatibility signal. On Laravel 8+ expect to fork, patch composer.json constraints, or backport schema/service-provider fixes yourself before relying on it.
• Upgrading from 3.x to 4.0.0 is a major version bump. The release notes only mention framework/PHP support, but major tags typically change namespaces, provider registration, config keys, or migration contents. Run the test suite, diff the published config and migrations, and re-verify middleware registration before deploying.
• Middleware ordering matters. The tracker needs the Laravel session and auth context to attach visitors/users correctly. Place it after StartSession and auth middleware; otherwise sessions may be anonymous or missing. Laravel 7's web group already handles this, but custom groups do not.
• Review migrations before running them. Older packages sometimes use schema types, indexes, or defaults that conflict with newer Laravel/MySQL/PostgreSQL conventions. Test on a copy of production data.
• Tracking is synchronous by default. Every tracked request writes to the database, which can hurt high-traffic apps. Use a separate database connection, sample traffic, queue writes if you customize the pipeline, and add indexes/pruning early.
• Behind load balancers/CDNs, configure trusted proxies so IPs and user agents are correct. Otherwise geo/device/referrer data will be misleading.
• Bots will pollute reports. Filter known bots/crawlers at the middleware or query layer, and exclude internal IPs and staging environments.
• GeoIP and user-agent parsing data can be stale. If geo/device accuracy matters, plan to update the underlying databases or replace that part of the pipeline.
• SPA and API projects are easy to mis-track. The package records the initial document/API request, not client-side route changes. Add manual tracking for meaningful front-end navigations and business events.
• After changing config/tracker.php, clear config cache with php artisan config:clear. If the package exposes routes/dashboard pages, also consider route caching behavior and protect those routes with auth/authorization.
• Debug by checking whether rows land in the session/page-view tables, then inspect the package log/error tables if present. Temporarily disable the middleware on one route to isolate ordering or exception issues.
• Extension points are mostly the published config, middleware, and models. For custom behavior, wrap the package middleware or build your own thin tracking service rather than editing vendor files. Because v4 is a fresh major on an otherwise low-activity package, keep your event names, config overrides, and dashboard queries in application code so swapping the package out later is a contained change.