User Device Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   This runs migrations and publishes config/configuration files.

2. Service Providers: Ensure Moox\UserDevice\UserDeviceServiceProvider is registered in config/app.php under providers.

3. First Use Case: Track logins by injecting UserDeviceTracker into your LoginController or middleware:

   use Moox\UserDevice\Services\UserDeviceTracker;
   
   public function login(Request $request, UserDeviceTracker $tracker) {
       $user = auth()->login($request->user());
       $tracker->track($user, $request);
   }
   

4. Filament Integration: If using Filament, register the UserDeviceResource in your Filament admin panel:

   use Moox\UserDevice\Filament\UserDeviceResource;
   
   Filament::registerResources([
       UserDeviceResource::class,
   ]);
   

Implementation Patterns

Core Workflows

1. Tracking Devices: Use UserDeviceTracker to log device info (IP, user-agent, location) on login:

   $tracker->track($user, $request);
   

   • Automatically detects new devices and updates existing ones.

2. Location Service: Integrate LocationService for geolocation (requires geoip2/geoip2):

   $location = app(LocationService::class)->getLocation($request->ip());
   $tracker->track($user, $request, $location);
   

3. Admin Monitoring:

   • Access the Filament UserDeviceResource to view all logged devices.
   • Filter by user, device type, or login time.

Integration Tips

• Middleware: Wrap login routes with middleware to auto-track devices:

  Route::middleware(['track.user.device'])->group(function () {
      Auth::routes();
  });
  

  Add to app/Http/Kernel.php:

  'track.user.device' => \Moox\UserDevice\Http\Middleware\TrackUserDevice::class,
  

• Custom Fields: Extend the user_devices table via migrations or seeders:

  Schema::table('user_devices', function (Blueprint $table) {
      $table->string('device_model')->nullable();
  });
  

• Event Listeners: Listen for user.device.created or user.device.updated events to trigger notifications:

  Event::listen(UserDeviceCreated::class, function ($event) {
      // Send admin alert or user notification
  });
  

Gotchas and Tips

Pitfalls

1. Missing Dependencies:

   • geoip2/geoip2 is required for LocationService. Install via:

     composer require geoip2/geoip2
     

   • Ensure the GeoLite2 database is downloaded and configured in config/user-device.php.

2. Filament Compatibility:

   • If Filament isn’t installed, the UserDeviceResource will throw errors. Install Filament first:

     composer require filament/filament
     

3. Database Conflicts:

   • The package assumes a users table with id. Customize the user_id column in migrations if needed.

4. Rate Limiting:

   • High-traffic logins may slow queries. Add indexes to user_devices(user_id, ip):

     Schema::table('user_devices', function (Blueprint $table) {
         $table->index(['user_id', 'ip']);
     });
     

Debugging

• Logs: Enable debug mode in config/user-device.php to log tracker events:

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

  Check storage/logs/laravel.log for issues.

• Common Errors:

  • "Table not found": Run migrations after installation.
  • "Class not found": Ensure the service provider is registered.

Extension Points

1. Custom Device Policies: Override Moox\UserDevice\Policies\UserDevicePolicy to enforce rules (e.g., block unknown devices):

   public function allowLogin(User $user, Request $request) {
       $device = $user->devices()->where('ip', $request->ip())->first();
       return $device ? true : false; // Custom logic here
   }
   

2. Notifications: Extend Moox\UserDevice\Notifications\NewDeviceNotification to send alerts:

   class CustomDeviceNotification extends NewDeviceNotification {
       public function toMail($notifiable) {
           return (new MailMessage)
               ->line('New device detected!')
               ->action('Review Devices', url('/admin/devices'));
       }
   }
   

3. API Endpoints: Expose device data via API:

   Route::get('/user/devices', function (User $user) {
       return $user->devices()->with('location')->get();
   });