Download the PHP package pijler/user-devices without Composer

📱 Laravel User Devices

This package provides support for managing user devices in Laravel. Track login devices, detect new logins, send notifications, and allow users to block suspicious devices—useful for security monitoring, session management, and multi-device applications.

🧩 Features

• ✅ Device tracking: Automatic tracking of IP address, user agent, location, and session ID
• ✅ New login detection: Identifies first-time logins from new devices
• ✅ Email notifications: Sends alerts when a new device logs in, on login attempts, and on failed logins
• ✅ Configurable events: Enable or disable listeners per auth event (authenticated, attempting, failed)
• ✅ Location from IP: Optional geolocation via callback
• ✅ Block device: Signed links to block suspicious devices in all notification types (invalidates session when blocked)
• ✅ Integrated middleware: Protect routes from blocked devices
• ✅ Block login check: Prevent blocked devices from attempting login via isCurrentDeviceBlocked()
• ✅ Model trait: Simple Eloquent integration
• ✅ Flexible configuration: Custom models and callbacks

📦 Installation

You can install the package via Composer:

🗄️ Publishing

Publish the package config (optional):

Publish the package migrations:

Run the migrations:

⚙️ Configuration

Config File

DeviceCreator

The package works out-of-the-box, but you can customize the behavior:

The block link expiration uses auth.verification.expire (default 60 minutes), same as Laravel's email verification.

🧠 Usage

1. Using the HasUserDevices Trait

Add the HasUserDevices trait to your User model. Your User model must also use the Notifiable trait for notifications:

2. Saving User Devices

The package automatically saves user devices when auth events fire. No manual setup required—just add the HasUserDevices trait to your User model.

• Authenticated: Saves/updates device (IP, user agent, location, session ID). Sends notification only on first login from that device.
• Attempting: Same as above. Finds user by email in credentials (when events.attempting is enabled).
• Failed: Same as above. Uses user from event or resolves from credentials (when events.failed is enabled).

All three events use firstOrNew by IP + user agent, so the same device is updated across requests.

To skip saving the device entirely for a request (e.g. in middleware or controller before authentication):

To ignore only the new login notification (device is still saved, but no email is sent):

To control notifications globally (e.g. disable in local/staging, or custom logic per user/device):

3. Block Device Route

When a user receives the new login notification email, they can click a link to block the device. Register a route that handles this request. Blocking invalidates the device's session when using session-based auth. The route must be signed and named user-devices.block:

You can use any path you prefer as long as the route is named user-devices.block and includes the {id} and {hash} parameters. All three notification types (Authenticated, Attempting, Failed) include a block link in the email.

4. Check Blocked Device Before Login

To prevent blocked devices from attempting login, call isCurrentDeviceBlocked() after resolving the user (e.g. by email) and before validating the password. In a custom login controller or FormRequest:

Or in a FormRequest's authorize or custom validation:

5. Using the Middleware

The package includes middleware to block requests from devices the user has blocked:

When a blocked device tries to access a protected route, the middleware returns 423 Locked.

6. Working with the UserDevice Model

7. Sending Notifications Manually

8. Customizing Attempting & Failed Login Notifications

🧩 API Reference

DeviceCreator

UserDevice Model

HasUserDevices Trait

AuthenticatedLoginNotification

AttemptingLoginNotification & FailedLoginNotification

BlockDeviceRequest

📝 License

Open-source under the MIT license.

🚀 Thanks!