User Session Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Run these commands in your Laravel project:

   composer require moox/user-session
   php artisan mooxuser-session:install
   

   This publishes migrations, config, and sets up the Filament resource for session monitoring.

2. First Use Case After installation, access the Filament admin panel (if configured) to view active user sessions via the Sessions resource. This provides a real-time dashboard of logged-in users, their devices, and session metadata.

3. Where to Look First

   • Config File: config/moox-user-session.php – Adjust session tracking settings (e.g., retention policies, user model bindings).
   • Migrations: Check database/migrations/ for session-related tables (e.g., user_sessions, session_devices).
   • Filament Resource: Locate the auto-generated resource in app/Filament/Resources/UserSessionResource.php to customize columns, filters, or actions.

Implementation Patterns

Core Workflows

1. Session Tracking Integration

   • Automatic Tracking: The package hooks into Laravel’s session middleware to log session creation/termination. No manual intervention is needed for basic usage.
   • Custom User Models: Extend the SessionRelationService to support polymorphic user relationships (e.g., User, Admin, Vendor):

     // config/moox-user-session.php
     'user_models' => [
         \App\Models\User::class,
         \App\Models\Admin::class,
     ],
     

2. Filament Dashboard Customization

   • Override Resource: Publish and modify the Filament resource:

     php artisan vendor:publish --tag="user-session-filament-resource"
     

   • Add Custom Actions: Extend the resource to include actions like "Force Logout" or "Ban Session":

     // app/Filament/Resources/UserSessionResource.php
     public static function getPages(): array
     {
         return [
             'index' => Pages\ListUserSessions::class,
             'view' => Pages\ViewUserSession::class,
             // Add custom pages (e.g., for session termination)
             'terminate' => Pages\TerminateUserSession::class,
         ];
     }
     

3. Device Integration

   • Pair with Moox User Device to enrich session data with device fingerprints (IP, user agent, etc.). Example:

     use Moox\UserDevice\Services\UserDeviceService;
     
     $deviceService = app(UserDeviceService::class);
     $device = $deviceService->getDeviceFromRequest(request());
     $session->device()->associate($device);
     $session->save();
     

4. Session Retention Policies

   • Configure automatic cleanup of stale sessions via the config/moox-user-session.php:

     'retention' => [
         'days' => 30, // Delete sessions older than 30 days
         'queue' => 'default', // Use a queue for cleanup jobs
     ],
     

   • Run the cleanup manually:

     php artisan mooxuser-session:cleanup
     

Gotchas and Tips

Pitfalls

1. Middleware Conflicts

   • If sessions aren’t being logged, ensure moox/user-session middleware (LogSessionActivity) is placed after Laravel’s web middleware in app/Http/Kernel.php:

     'web' => [
         \Illuminate\Session\Middleware\AuthenticateSession::class,
         \Moox\UserSession\Http\Middleware\LogSessionActivity::class, // <-- Add here
     ],
     

2. Polymorphic User Models

   • Forgetting to register all user models in the config will cause SessionRelationService to fail silently. Always verify:

     php artisan mooxuser-session:test-relations
     

3. Filament Permissions

   • The Sessions resource requires Filament permissions. If unauthorized, check:
     • config/filament.php for policy bindings.
     • The canAccess() method in UserSessionResource.

4. Database Bloat

   • Sessions tables can grow large. Monitor user_sessions and session_devices tables. Use the retention config to automate cleanup.

Debugging Tips

1. Log Session Events Enable debug logging in config/moox-user-session.php:

   'debug' => env('MOOX_USER_SESSION_DEBUG', false),
   

   Check storage/logs/laravel.log for session lifecycle events.

2. Test Session Tracking Use the artisan command to verify session logging:

   php artisan mooxuser-session:test
   

   This simulates a session and checks if it’s recorded.

3. Query Performance Optimize Filament queries by adding indexes to foreign keys in migrations:

   $table->foreignId('user_id')->constrained()->index();
   $table->foreignId('device_id')->constrained()->index();
   

Extension Points

1. Custom Session Data Extend the UserSession model to store additional fields:

   // app/Models/UserSession.php
   protected $casts = [
       'metadata' => 'json',
   ];
   

   Access via:

   $session->metadata['custom_key'] = 'value';
   

2. Event Listeners Listen for session events to trigger actions (e.g., notifications):

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \Moox\UserSession\Events\SessionStarted::class => [
           \App\Listeners\SendSessionNotification::class,
       ],
   ];
   

3. API Endpoints Expose session data via Laravel API routes:

   // routes/api.php
   Route::middleware('auth:sanctum')->get('/user/sessions', [SessionController::class, 'index']);
   

   Use the SessionRelationService to fetch sessions for the authenticated user:

   $sessions = app(\Moox\UserSession\Services\SessionRelationService::class)
       ->forUser(auth()->user());