Laravel Devices Laravel Package

Getting Started

1. Install the package via Composer:

   composer require diego-ninja/laravel-devices
   

2. Publish the config and migrations:

   php artisan vendor:publish --tag=laravel-devices-config
   php artisan vendor:publish --tag=laravel-devices-migrations
   php artisan migrate
   

3. First use case: Enable 2FA for users — the package ships with working 2FA endpoints (/api/2fa/*). After enabling it in your auth flow (e.g., post-login), you’ll get QR codes and code verification out of the box.

4. Start here: Check config/devices.php to enable/disable features (fingerprinting, caching, routes) and review the API docs in the repo. Ensure your User model uses the HasDevices trait and implements CanVerifyDevices.

Implementation Patterns

• Session & device tracking on login: In your LoginController, call trackDevice() after successful authentication:

  $request->user()->trackDevice($request);
  

  This automatically records browser, OS, device type, location, and IP — and assigns a unique device UUID.

• Frontend integration: Use the provided Vue/React helpers (or roll your own) to show a “Manage Devices” UI. Example: Display device list via GET /api/devices and let users sign out from inactive sessions with POST /api/devices/signout.

• 2FA workflow: On sensitive actions (e.g., changing email), lock the current session using lockSession() and prompt the user to verify the 2FA code via POST /api/2fa/verify. Once verified, session unlocks.

• Device verification & hijack detection: Call $device->verify() on first trusted usage (e.g., after successful 2FA) and later mark devices as hijacked ($device->hijack()) if suspicious behavior is detected.

• Extend with custom fingerprinting: Override DeviceFingerprinter in config/devices.php to integrate FingerprintJS or ThumbmarkJS for enhanced browser fingerprinting.

Gotchas and Tips

• Session locking ≠ 2FA: Locking a session (e.g., during 2FA setup) doesn’t require a second factor yet — you must manually call lockSession() on the current device and unlock it only after verifying the code.

• Cache is critical: The package uses caching (default device_cache_ttl = 15 mins). If you’re debugging, clear php artisan cache:clear --tag=devices.

• Migrations may conflict: If using a custom users table with UUIDs, adjust migrations to match your primary key type before running them. The package expects string UUIDs.

• Device detection quirks: Fallback user-agent parsing (without JS fingerprinting) may misidentify modern browsers. Always test on Safari/iOS where sec-ch-ua headers are inconsistent.

• Security tip: Never expose device uuid directly in public responses without checking ownership. Use the included DeviceResource which safely filters sensitive data.

• Extensibility hooks: Implement your own DeviceValidator, SessionHandler, or LocationResolver by swapping concrete bindings in providers/AppServiceProvider. Use devices.* events (DeviceVerified, SessionBlocked, etc.) for audit logging.