README

A comprehensive visitor tracking package for Laravel applications with analytics, geolocation, and bot detection.

🚀 Zero External Dependencies - Uses only Laravel's built-in features and native PHP for all functionality.

Features

📊 Comprehensive Tracking - Track page views, unique visitors, and sessions
🤖 Native Bot Detection - Detect 100+ bots/crawlers without external packages
📱 Native Device Detection - Identify browsers, platforms, and device types using regex
🌍 Geolocation - Optional IP-based location tracking (using Laravel's HTTP client)
🔒 GDPR Compliant - GDPR Safe Mode for consent-free tracking, IP anonymization, DNT support
⚡ Performance - Queue support for async tracking, statistics caching
📈 Rich Statistics - Browser, platform, device, country, referrer analytics
🎯 Flexible Exclusions - Exclude paths, IPs, user agents, status codes
🔧 Zero Dependencies - Only uses Laravel's illuminate packages

Requirements

PHP 8.1+
Laravel 10.x, 11.x, or 12.x

Installation

composer require ghdj/laravel-visitor-tracker

Publish the configuration file:

php artisan vendor:publish --tag="visitor-tracker-config"

Run the migrations:

php artisan migrate

Configuration

The configuration file is located at config/visitor-tracker.php. Key options include:

return [
    // Enable/disable tracking globally
    'enabled' => env('VISITOR_TRACKER_ENABLED', true),
    
    // Paths to exclude from tracking
    'exclude' => [
        'paths' => ['api/*', 'admin/*'],
        'methods' => ['OPTIONS', 'HEAD'],
        'status_codes' => [301, 302, 404, 500],
        'ips' => [],
        'user_agents' => [],
    ],
    
    // Bot tracking
    'bots' => [
        'track' => false,
        'detect' => true,
        'additional_patterns' => [], // Add custom bot patterns
    ],
    
    // Custom parser patterns
    'parser' => [
        'additional_browsers' => [], // Add custom browser patterns
        'additional_platforms' => [], // Add custom platform patterns
    ],
    
    // Geolocation (optional - uses Laravel HTTP client)
    'geolocation' => [
        'enabled' => env('VISITOR_TRACKER_GEOLOCATION', false),
        'provider' => 'ip-api', // ip-api (free), ipinfo, ipapi
    ],
    
    // GDPR compliance
    'privacy' => [
        'gdpr_safe_mode' => env('VISITOR_TRACKER_GDPR_SAFE', false),
        'anonymize_ip' => env('VISITOR_TRACKER_ANONYMIZE_IP', false),
        'respect_dnt' => true,
    ],
    
    // Data retention
    'retention' => [
        'days' => 90,
    ],
    
    // Queue for async tracking
    'queue' => [
        'enabled' => env('VISITOR_TRACKER_QUEUE', false),
    ],
];

Usage

Middleware

Add the tracking middleware to your routes:

// In routes/web.php
Route::middleware(['track-visitor'])->group(function () {
    Route::get('/', [HomeController::class, 'index']);
    // ... more routes
});

// Or globally in bootstrap/app.php (Laravel 11)
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \Ghdj\VisitorTracker\Middleware\TrackVisitor::class,
    ]);
})

Using the Facade

use Ghdj\VisitorTracker\Facades\VisitorTracker;

// Get statistics
$stats = VisitorTracker::stats();

// Total visitors (unique)
$totalVisitors = $stats->totalVisitors();

// Total page views
$totalPageViews = $stats->totalPageViews();

// Currently online visitors
$onlineNow = $stats->onlineVisitors();

// Today's visitors
$todayVisitors = $stats->todayVisitors();

// Visitors in last N days
$weeklyVisitors = $stats->visitorsLastDays(7);

// Most visited pages
$topPages = $stats->mostVisitedPages(10);

// Top referrers
$topReferrers = $stats->topReferrers(10);

// Browser statistics
$browsers = $stats->browserStats();

// Platform/OS statistics
$platforms = $stats->platformStats();

// Device type statistics
$devices = $stats->deviceStats();

// Country statistics (requires geolocation)
$countries = $stats->countryStats();

// Summary of all stats
$summary = $stats->summary();

Using the Helper Function

// Get tracker instance
$tracker = visitor();

// Get statistics
$stats = visitor()->stats()->summary();
$online = visitor_stats()->onlineVisitors();

Blade Directives

<div class="stats">
    <p>Total Visitors: @totalVisitors</p>
    <p>Total Page Views: @totalPageViews</p>
    <p>Online Now: @onlineVisitors</p>
    <p>Today's Visitors: @todayVisitors</p>
</div>

Working with Models

use Ghdj\VisitorTracker\Models\Visitor;
use Ghdj\VisitorTracker\Models\Visit;

// Get all visitors
$visitors = Visitor::all();

// Get online visitors
$online = Visitor::online()->get();

// Get visitors excluding bots
$humans = Visitor::excludeBots()->get();

// Get authenticated visitors only
$authenticated = Visitor::authenticated()->get();

// Get visitors from date range
$recent = Visitor::between(now()->subWeek(), now())->get();

// Get visits for a specific path
$homeVisits = Visit::path('/')->get();

// Get visits with referrers
$referred = Visit::withReferrer()->get();

Using Native Services Directly

use Ghdj\VisitorTracker\Services\UserAgentParser;
use Ghdj\VisitorTracker\Services\BotDetector;

// Parse user agent
$parser = new UserAgentParser();
$result = $parser->parse($request->userAgent());
// Returns: ['browser' => 'Chrome', 'browser_version' => '120.0', 'platform' => 'Windows', ...]

// Detect bots
$detector = new BotDetector();
$isBot = $detector->isBot($request->userAgent());
$botName = $detector->getBotName($request->userAgent());
$category = $detector->getBotCategory($request->userAgent()); // search_engine, social_media, ai_bot, etc.

Adding Custom Patterns

// Add custom browser detection
$parser = new UserAgentParser();
$parser->addBrowserPatterns([
    'MyCustomBrowser' => '/MyCustomBrowser\/([0-9.]+)/',
]);

// Add custom bot detection
$detector = new BotDetector();
$detector->addPatterns(['mycustombot', 'anotherbot']);
$detector->addBotNames(['mycustombot' => 'My Custom Bot']);

// Or via config
// config/visitor-tracker.php
'parser' => [
    'additional_browsers' => [
        'MyBrowser' => '/MyBrowser\/([0-9.]+)/',
    ],
],
'bots' => [
    'additional_patterns' => ['mycustombot'],
],

Listening to Events

use Ghdj\VisitorTracker\Events\VisitorTracked;

// In EventServiceProvider or using Event facade
Event::listen(VisitorTracked::class, function (VisitorTracked $event) {
    $visitor = $event->visitor;
    $visit = $event->visit;
    
    // Custom logic here
    logger("New visit from {$visitor->ip} to {$visit->path}");
});

Artisan Commands

# Show visitor statistics
php artisan visitor-tracker:stats
php artisan visitor-tracker:stats --detailed

# Prune old data
php artisan visitor-tracker:prune
php artisan visitor-tracker:prune --days=30
php artisan visitor-tracker:prune --force

Scheduling Data Pruning

Add to your routes/console.php or scheduler:

use Illuminate\Support\Facades\Schedule;

Schedule::command('visitor-tracker:prune --force')->daily();

Dashboard Authentication

The dashboard is always protected. Choose an authentication method based on your site:

Option 1: Token Authentication (Sites Without Login)

For sites without user authentication, use a secret token:

# Add to your .env file (NEVER commit this!)
VISITOR_TRACKER_TOKEN=your-secret-token-here

Enable the dashboard in config/visitor-tracker.php:

'dashboard' => [
    'enabled' => true,
    'token' => env('VISITOR_TRACKER_TOKEN'),
    'middleware' => ['web'], // No 'auth' needed
],

Access the dashboard via:

URL: /admin/visitor-tracker?token=your-secret-token-here
Header: X-Visitor-Tracker-Token: your-secret-token-here
Bearer: Authorization: Bearer your-secret-token-here

Option 2: Laravel Auth (Sites With Login)

For sites with user authentication:

'dashboard' => [
    'enabled' => true,
    'middleware' => ['web', 'auth'],
],

Option 3: Gate Authorization (Role-Based Access)

For admin-only access with Laravel Gates:

// In AuthServiceProvider
Gate::define('view-visitor-stats', function ($user) {
    return $user->is_admin;
});

// In config/visitor-tracker.php
'dashboard' => [
    'enabled' => true,
    'middleware' => ['web', 'auth'],
    'gate' => 'view-visitor-stats',
],

Geolocation Providers

All providers use Laravel's built-in HTTP client - no external packages required.

ip-api.com (Free, No API Key)

VISITOR_TRACKER_GEOLOCATION=true
VISITOR_TRACKER_GEO_PROVIDER=ip-api

ipinfo.io

VISITOR_TRACKER_GEOLOCATION=true
VISITOR_TRACKER_GEO_PROVIDER=ipinfo
VISITOR_TRACKER_GEO_API_KEY=your_api_key

Queue Support

For high-traffic sites, enable queue processing:

VISITOR_TRACKER_QUEUE=true
VISITOR_TRACKER_QUEUE_CONNECTION=redis
VISITOR_TRACKER_QUEUE_NAME=tracking

GDPR Safe Mode

To track anonymous aggregate statistics without requiring user consent, enable GDPR Safe Mode:

VISITOR_TRACKER_GDPR_SAFE=true

When enabled, the following personal data is NOT collected:

Data	Status	Notes
IP Address	❌ Not stored	Not even anonymized
User ID	❌ Not stored	No link to authenticated users
Persistent Cookie	❌ Not used	Session-only identification
Full User Agent	❌ Not stored	Only parsed for aggregate stats
City / Region	❌ Not stored	Only country-level location
Coordinates	❌ Not stored	No lat/long

What IS still collected (anonymous, aggregate data):

Data	Purpose
Page view counts	Traffic analytics
Browser name	Chrome, Firefox, etc.
Platform name	Windows, macOS, etc.
Device type	Mobile, desktop, tablet
Country	Broad geographic distribution
Referrer domain	Traffic sources

// Check if GDPR safe mode is enabled
if (VisitorTracker::isGdprSafeMode()) {
    // No personal data being collected
}

Detected Browsers

Chrome, Firefox, Safari, Edge, Opera, Brave, Vivaldi, Samsung Browser, UC Browser, Yandex, IE, and more.

Detected Platforms

Windows (XP through 11), macOS, iOS, Android, Linux, Ubuntu, Chrome OS, FreeBSD.

Detected Bots

100+ bot patterns including:

Search Engines: Google, Bing, Yahoo, DuckDuckGo, Baidu, Yandex
Social Media: Facebook, Twitter, LinkedIn, Pinterest, Slack, Discord
AI/LLM: GPTBot, ClaudeBot, Anthropic, CCBot, Perplexity
SEO Tools: Ahrefs, SEMrush, Moz, Majestic
Monitoring: UptimeRobot, Pingdom, DataDog, New Relic
HTTP Clients: cURL, Wget, Python Requests, Postman, Axios

Testing

composer test

Code Quality

# Run code style fixer
composer format

# Run static analysis
composer analyse

Why Zero Dependencies?

Smaller footprint - No additional packages to install or maintain
Better performance - Native regex is fast and efficient
Full control - Easily extend patterns via configuration
Security - Less attack surface, no supply chain concerns
Reliability - Only depends on Laravel core packages

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

The MIT License (MIT). Please see License File for more information.

ghdj / laravel-visitor-tracker

Maintainers

Details