Laravel Request Analytics Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require me-shaon/laravel-request-analytics
   php artisan request-analytics:install
   

   The installer handles migrations, config, and assets automatically.

2. First Use Case:

   • Access the dashboard at /analytics (or your configured path)
   • Verify real-time tracking by visiting your site and observing metrics update

3. Where to Look First:

   • Config: config/request-analytics.php (adjust paths, middleware, geolocation)
   • Middleware: app/Http/Kernel.php (ensure RequestAnalyticsMiddleware is registered)
   • Dashboard: /analytics (default route)

Implementation Patterns

Core Workflow

1. Middleware Integration:

   // app/Http/Kernel.php
   protected $middlewareGroups = [
       'web' => [
           // ...
           \MeShaon\RequestAnalytics\Http\Middleware\RequestAnalyticsMiddleware::class,
       ],
   ];
   

   • Automatically captures requests for configured routes (web/API).

2. Queue-Based Processing (for high-traffic sites):

   // config/request-analytics.php
   'queue' => [
       'enabled' => true,
       'on_queue' => 'analytics',
   ],
   

   • Offloads analytics processing to a queue (e.g., php artisan queue:work).

3. Custom Metrics:

   // Track custom events (e.g., form submissions)
   use MeShaon\RequestAnalytics\Facades\RequestAnalytics;
   
   RequestAnalytics::trackEvent('form_submitted', ['form_id' => 123]);
   

4. API Access:

   // Fetch analytics data programmatically
   $visitors = \MeShaon\RequestAnalytics\Models\RequestAnalytics::query()
       ->where('created_at', '>=', now()->subDays(7))
       ->count();
   

Integration Tips

• Authentication: Use request-analytics.access middleware to restrict dashboard access:

  'middleware' => [
      'web' => [
          'auth',
          'request-analytics.access',
      ],
  ],
  

• Geolocation: Enable and configure your preferred provider (e.g., MaxMind for accuracy):

  'geolocation' => [
      'provider' => 'maxmind',
      'maxmind' => [
          'type' => 'database',
          'database_path' => storage_path('app/GeoLite2-City.mmdb'),
      ],
  ],
  

• Exclude Paths: Filter out admin or API routes:

  'ignore-paths' => [
      'admin/*',
      'api/v1/*',
  ],
  

Gotchas and Tips

Pitfalls

1. Double Tracking:

   • Ensure RequestAnalyticsMiddleware is not added twice (e.g., in both web and api groups if unintended).
   • Fix: Check app/Http/Kernel.php for duplicate middleware entries.

2. Queue Stuck Jobs:

   • If queue.enabled = true, monitor the analytics queue for failed jobs:

     php artisan queue:failed-table
     php artisan queue:retry <job-id>
     

   • Tip: Use queue:work --sleep=3 --tries=3 for resilience.

3. Geolocation Failures:

   • Free providers (e.g., ipapi) have rate limits. Cache responses:

     'cache' => [
         'ttl' => 15, // Cache geolocation for 15 minutes
     ],
     

4. Pruning Issues:

   • If model:prune fails, verify the model namespace in config/request-analytics.php matches MeShaon\RequestAnalytics\Models\RequestAnalytics.

Debugging

• Log Requests: Enable debug mode in config:

  'debug' => [
      'enabled' => true,
      'log_path' => storage_path('logs/request-analytics.log'),
  ],
  

• Check Captured Data: Inspect raw analytics data:

  php artisan tinker
  >>> \MeShaon\RequestAnalytics\Models\RequestAnalytics::first();
  

Extension Points

1. Custom Fields: Extend the RequestAnalytics model to add custom attributes:

   // app/Models/RequestAnalytics.php
   use MeShaon\RequestAnalytics\Models\RequestAnalytics as BaseAnalytics;
   
   class RequestAnalytics extends BaseAnalytics {
       protected $casts = [
           'custom_field' => 'string',
       ];
   }
   

2. Override Views: Publish and modify dashboard templates:

   php artisan vendor:publish --tag="request-analytics-views"
   

   • Edit files in resources/views/vendor/request-analytics/.

3. API Extensions: Add custom endpoints by extending the AnalyticsController:

   // app/Http/Controllers/AnalyticsController.php
   use MeShaon\RequestAnalytics\Http\Controllers\AnalyticsController as BaseController;
   
   class AnalyticsController extends BaseController {
       public function customReport() {
           return response()->json(['custom_data' => '...']);
       }
   }
   

Performance Tips

• Batch Inserts: For high-traffic sites, use chunked inserts:

  \MeShaon\RequestAnalytics\Models\RequestAnalytics::insert([
      ['path' => '/home', 'ip' => '192.168.1.1', 'created_at' => now()],
      // ... more records
  ]);
  

• Indexing: Add indexes to frequently queried columns:

  Schema::table('request_analytics', function (Blueprint $table) {
      $table->index('path');
      $table->index('created_at');
  });
  

Privacy Compliance

• GDPR: Anonymize IPs and implement data retention policies:

  'privacy' => [
      'anonymize_ip' => true,
  ],
  'pruning' => [
      'days' => 30, // Retain data for 30 days
  ],
  

• User Requests: Add a route to delete user data:

  Route::get('/analytics/delete-my-data', [AnalyticsController::class, 'deleteUserData']);