README

Trackora

A powerful Laravel package to track and analyze website visitors with detailed statistics, browser detection, geolocation, and a beautiful dashboard with light/dark mode support.

Features

Track website visitors automatically with middleware
Browser and platform detection
Device type detection (Desktop, Mobile, Tablet)
Geolocation support (country, city)
Unique visitor tracking per day
Beautiful responsive dashboard with statistics
Light/Dark mode toggle with persistent preference
Export data to CSV or JSON
Configurable data retention
Bot/crawler filtering
API endpoint for statistics

Requirements

PHP 8.1+
Laravel 10.0+

Installation

Install the package via Composer:

composer require ibrahim-eng12/trackora

Publish the configuration, migration, and asset files:

php artisan vendor:publish --tag=trackora-config
php artisan vendor:publish --tag=trackora-migrations
php artisan vendor:publish --tag=trackora-assets

Run the migrations:

php artisan migrate

Usage

Automatic Tracking with Middleware

Add the tracking middleware to your routes or middleware groups:

Option 1: Global middleware (in bootstrap/app.php for Laravel 11+):

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \IbrahimEng12\Trackora\Http\Middleware\TrackVisitor::class,
    ]);
})

Option 2: Route middleware (in app/Http/Kernel.php for Laravel 10):

protected $middlewareGroups = [
    'web' => [
        // ... other middleware
        \IbrahimEng12\Trackora\Http\Middleware\TrackVisitor::class,
    ],
];

Option 3: Per-route middleware:

Route::middleware(['trackora.track'])->group(function () {
    // Your routes here
});

Manual Tracking

You can also track visitors manually:

use IbrahimEng12\Trackora\Models\Visitor;

// Track current request
Visitor::track($request);

// Track with custom page
Visitor::track($request, 'custom-page-name');

Configuration

After publishing, the configuration file will be available at config/trackora.php:

return [
    // URL prefix for dashboard (e.g., /trackora)
    'route_prefix' => 'trackora', // You can change the ROUTE for the Trackora dashboard of trackora HERE!
    // Middleware for dashboard routes
    'middleware' => ['web', 'auth'], // here you can add Role middleware like role:admin to allow only admin auth access
    // Users allowed to access dashboard (empty = all authenticated users)
    'allowed_users' => [], // here you can add IDs like 1 OR 1, 2  to allow only these users dashboard access
    // Enable/disable tracking globally
    'enabled' => env('TRACKORA_ENABLED', true),

    // Track authenticated users
    'track_authenticated' => true,

    // Track bots/crawlers
    'track_bots' => false,

    // Paths to exclude from tracking (supports wildcards)
    'excluded_paths' => [
        'admin/*',
        'api/*',
        'livewire/*',
        '_debugbar/*',
    ],

    // IPs to exclude from tracking
    'excluded_ips' => [],

    // Geolocation settings
    'geolocation' => [
        'enabled' => true,
        'provider' => 'ip-api',
    ],

    // Data retention (days, null = forever)
    'retention_days' => 90,

    // Database table name
    'table_name' => 'trackora_visits',

    // Dashboard settings
    'dashboard' => [
        'per_page' => 25,
        'default_period' => 30,
        'chart_colors' => [
            'primary' => '#3b82f6',
            'secondary' => '#10b981',
        ],
    ],
];

Accessing the Dashboard

Visit /trackora (or your configured route prefix) to access the dashboard.

Statistics Methods

The Visitor model provides several static methods for statistics:

use IbrahimEng12\Trackora\Models\Visitor;

// Counts
Visitor::getTotalCount();           // Total visits
Visitor::getUniqueCount();          // Unique visitors
Visitor::getTodayCount();           // Today's visits
Visitor::getTodayUniqueCount();     // Today's unique visitors
Visitor::getCountByDate('2024-01-15');
Visitor::getCountBetweenDates('2024-01-01', '2024-01-31');

// Analytics
Visitor::getTopPages(10);           // Top visited pages
Visitor::getTopBrowsers(10);        // Browser statistics
Visitor::getTopPlatforms(10);       // Platform statistics
Visitor::getDeviceTypeStats();      // Device type breakdown
Visitor::getDailyStats(30);         // Daily stats for N days
Visitor::getTopCountries(10);       // Country statistics
Visitor::getTopCities(10);          // City statistics
Visitor::getTopReferrers(10);       // Referrer statistics

// Maintenance
Visitor::purgeOldRecords();         // Purge based on retention_days config

API Endpoint

The package provides a JSON API endpoint at /trackora/stats:

GET /trackora/stats?period=30

Response:

{
    "total_visits": 1250,
    "unique_visitors": 850,
    "today_visits": 45,
    "today_unique": 32,
    "daily_stats": [...],
    "top_pages": [...],
    "top_browsers": [...],
    "top_platforms": [...],
    "device_stats": [...],
    "top_countries": [...]
}

Customizing Views

Publish the views to customize the dashboard:

php artisan vendor:publish --tag=trackora-views

Views will be published to resources/views/vendor/trackora/.

Publishing Assets

If you need to customize the dashboard assets (logo, etc.):

php artisan vendor:publish --tag=trackora-assets

Assets will be published to public/vendor/trackora/.

Restricting Dashboard Access

By User ID or Email

Add specific user IDs or emails to the allowed_users config:

'allowed_users' => [
    1,                          // User ID
    'admin@example.com',        // Email
],

By Custom Logic

Create your own middleware that extends AuthorizeTrackoraDashboard:

namespace App\Http\Middleware;

use IbrahimEng12\Trackora\Http\Middleware\AuthorizeTrackoraDashboard;

class CustomTrackoraAuthorization extends AuthorizeTrackoraDashboard
{
    protected function isAuthorized($request): bool
    {
        return $request->user()?->isAdmin();
    }
}

Scheduled Cleanup

To automatically purge old records, add this to your scheduler:

// In app/Console/Kernel.php or routes/console.php
Schedule::call(function () {
    \IbrahimEng12\Trackora\Models\Visitor::purgeOldRecords();
})->daily();

License

MIT License. See LICENSE for details.

ibrahim-eng12 / trackora

Maintainers

Details