README

A Laravel package to collect request and visitor geo/device analytics and store them in a trackings table.

What This Package Does

• Tracks each request (path, query params, IP, browser, OS, device).
• Enriches request data using an external IP geo provider.
• Stores full provider response for debugging and analytics.
• Links tracking rows to authenticated users through a polymorphic relation.
• Exposes helper methods through a facade:
  • Tracker::track()
  • Tracker::browser()
  • Tracker::os()
  • Tracker::device()

Supported Drivers

• geoplugin
• ipgeo
• ipwhois

Each driver returns a TrackingResponse object that is mapped into database columns.

Requirements

• PHP 8.2+
• Laravel application

Installation

1. Require the package.

   composer require mosamy/tracking

2. Run migrations.

   php artisan migrate

3. Configure environment variables in your application .env.

   TRACKING_ENABLED=true TRACKING_DRIVER=geoplugin TRACKING_IP=

   IPGEO_API_KEY= IPWHOIS_API_KEY=

   TRACKING_ESTIMATE_ELAPSED_TIME_INTERVAL=10 TRACKING_ENABLE_ESTIMATE_ELAPSED_TIME=true

Configuration

Config file path inside package:

• config/tracking.php

Config keys:

• enabled
  • Boolean flag for enabling/disabling tracking.
• driver
  • Active driver key, one of: geoplugin, ipgeo, ipwhois.
• ip
  • Optional forced IP for testing. If set, middleware overrides REMOTE_ADDR.
• estimate_elapsed_time_interval
  • Polling interval in seconds for the elapsed-time Livewire component. Default: 10.
• enable_estimate_elapsed_time
  • Boolean flag to enable or disable elapsed-time tracking. Default: true.
• drivers
  • Driver classes and API keys.

Driver config example:

• geoplugin
  • class: Mosamy\Tracking\Trackers\Geoplugin
• ipgeo
  • class: Mosamy\Tracking\Trackers\Ipgeo
  • api_key: from IPGeolocation
• ipwhois
  • class: Mosamy\Tracking\Trackers\Ipwhois
  • api_key: from ipwhois.pro

Enable Request Tracking

Apply middleware to routes you want to track.

Laravel 11+ (bootstrap/app.php)

->withMiddleware(function ($middleware) {

   $middleware->append(\Mosamy\Tracking\Middleware\TrackingMiddleware::class);

})

Laravel 10 and below (app/Http/Kernel.php)

• Add to web middleware group, api group, or global middleware based on your need.

How Tracking Works

1. TrackingMiddleware runs for incoming request.
2. If TRACKING_IP is set, request REMOTE_ADDR is overridden.
3. Middleware calls Tracker::track().
4. TrackerManager resolves configured driver from config.
5. Driver fetches geo data and builds TrackingResponse.
6. TrackerManager stores data using Mosamy\Tracking\Models\Tracking.
7. If user is authenticated, model boot hook associates user morph relation.

Manual Usage

You can call tracking manually in your own code.

use Mosamy\Tracking\Facades\Tracker;

Tracker::track();

You can also detect user agent details:

Tracker::browser(); Tracker::os(); Tracker::device();

Database Schema

Migration creates table: trackings

Columns:

• id
• path
• params (json)
• elapsed_time
• ip
• continent
• continent_code
• country
• country_code
• city
• city_code
• latitude
• longitude
• timezone
• currency_code
• currency_symbol
• browser
• os
• device
• session
• response (json)
• meta (json)
• user_type
• user_id
• created_at
• updated_at

Tracking Model

Model: Mosamy\Tracking\Models\Tracking

Features:

• Casts params, response, meta to arrays.
• Morph relation:
  • user()
• Query scopes:
  • forPage(page)
  • fromTo(from, to)

Examples:

use Mosamy\Tracking\Models\Tracking;

Tracking::query()->forPage('products')->get(); Tracking::query()->fromTo('2026-04-01', '2026-04-07')->get();

Drivers Behavior

Geoplugin:

• Calls http://www.geoplugin.net/json.gp with request IP.
• Maps geoplugin_* fields into normalized columns.

Ipgeo:

• Calls https://api.ipgeolocation.io/ipgeo with apiKey.
• Maps continent, country, city, timezone, currency info.

Ipwhois:

• Calls http://ipwhois.pro/{ip} with key.
• Maps continent, country, city, timezone, currency info.

Response DTO

DTO: Mosamy\Tracking\DTO\TrackingResponse

Contains normalized camelCase properties and provides toArray() that maps to snake_case database columns.

It also automatically enriches meta with:

• user_agent
• referer
• method
• host

Elapsed Time Tracking

The package ships a Livewire component that periodically increments elapsed_time on the active tracking row while the visitor is on the page.

Include it once in your layout (after @livewireScripts):

<livewire:tracking::estimate-elapsed-time poll-interval="10" />

The component uses poll-interval (seconds) as its polling cadence. If omitted it falls back to the estimate_elapsed_time_interval config value.

The feature is fully opt-in. Set TRACKING_ENABLE_ESTIMATE_ELAPSED_TIME=false (or enable_estimate_elapsed_time in config) to disable the polling without removing the component tag.

The component matches the current tracking row using the session column, which is populated automatically by the middleware from Laravel's session ID.

Common Use Cases

• Visitor analytics by page and period.
• Geo distribution dashboards.
• Fraud and abuse monitoring by IP/device.
• User activity insights tied to authenticated accounts.

Support

For support, please contact dev.mohamed.samy@gmail.com.

Author

Created by Mohamed Samy