PHPackages                             baligs/user-device-activity - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. baligs/user-device-activity

ActiveLibrary[Utility & Helpers](/categories/utility)

baligs/user-device-activity
===========================

Laravel package for tracking user device activities with multi-device management

v1.0.0(4mo ago)01↓100%MITPHPPHP ^8.0

Since Mar 20Pushed 4mo agoCompare

[ Source](https://github.com/baligs/user-device-activity)[ Packagist](https://packagist.org/packages/baligs/user-device-activity)[ RSS](/packages/baligs-user-device-activity/feed)WikiDiscussions main Synced 4mo ago

READMEChangelogDependencies (3)Versions (2)Used By (0)

User Device Activity Manager
============================

[](#user-device-activity-manager)

A powerful Laravel 9+ package for tracking user device activities, managing multi-device sessions, and monitoring user login statistics.

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
    - [Helper Class](#using-the-helper-class)
    - [Traits](#using-traits)
    - [Login Controller Integration](#login-controller-integration)
    - [Middleware](#middleware)
- [Statistics](#statistics)
- [Dashboard](#dashboard)
- [API Endpoints](#api-endpoints)
- [Artisan Commands](#artisan-commands)
- [Troubleshooting](#troubleshooting)

---

Features
--------

[](#features)

- **Multi-Device Session Management**

    - Track devices separately for web and API guards
    - View all devices a user is logged in from
    - Logout specific device, current device, or all devices at once
- **Comprehensive Activity Logging**

    - Login/logout events
    - Device information (OS, browser, device type)
    - IP address and geolocation
    - Session duration and activity timestamps
- **Statistics Dashboard (20+ Stats)**

    - Active sessions count
    - Logins by country, OS, browser, device type
    - Top active users
    - Login success rate
    - Session duration statistics
    - Hourly/daily activity trends
- **Configurable Data Retention**

    - Set how long to keep data (days/years)
    - Auto-cleanup old records
    - Manual cleanup command
- **SQLite Support**

    - Lightweight database for activity storage
    - Easy to setup and maintain

---

Requirements
------------

[](#requirements)

- PHP 8.0+
- Laravel 9.0, 10.0, or 11.0
- SQLite PHP extension (for SQLite storage)
- `jenssegers/agent` package (for device detection)

---

Installation
------------

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require baligs/user-device-activity
```

### Step 2: Run Install Command (Recommended)

[](#step-2-run-install-command-recommended)

```
php artisan device-activity:install
```

This command will:

- Create SQLite database file
- Publish configuration
- Publish migrations
- Run migrations

### Step 3: Configure Environment

[](#step-3-configure-environment)

Add to your `.env` file:

```
# Database
DEVICE_ACTIVITY_DB_CONNECTION=sqlite
DEVICE_ACTIVITY_DB_PATH=database/user_device_activity.sqlite

# Retention (keep data for 365 days)
DEVICE_ACTIVITY_RETENTION_DAYS=365

# Session limits
DEVICE_ACTIVITY_MULTIPLE_SESSIONS=true
DEVICE_ACTIVITY_MAX_SESSIONS=5

# IP Lookup (for country detection)
DEVICE_ACTIVITY_IP_LOOKUP=true
```

### Manual Installation

[](#manual-installation)

If you prefer manual setup:

```
# 1. Publish configuration
php artisan vendor:publish --provider="Baligs\UserDeviceActivity\Providers\UserDeviceActivityServiceProvider" --tag="user-device-activity-config"

# 2. Publish migrations
php artisan vendor:publish --provider="Baligs\UserDeviceActivity\Providers\UserDeviceActivityServiceProvider" --tag="user-device-activity-migrations"

# 3. Publish views (optional - for custom dashboard)
php artisan vendor:publish --provider="Baligs\UserDeviceActivity\Providers\UserDeviceActivityServiceProvider" --tag="user-device-activity-views"

# 4. Create SQLite database
touch database/user_device_activity.sqlite

# 5. Run migrations
php artisan migrate
```

---

Configuration
-------------

[](#configuration)

Edit `config/user-device-activity.php`:

### Database Configuration

[](#database-configuration)

```
'database' => [
    'connection' => env('DEVICE_ACTIVITY_DB_CONNECTION', 'sqlite'),
    'database_path' => env('DEVICE_ACTIVITY_DB_PATH', database_path('user_device_activity.sqlite')),
],
```

### Retention Settings

[](#retention-settings)

```
'retention' => [
    'enabled' => env('DEVICE_ACTIVITY_RETENTION_ENABLED', true),
    'days' => env('DEVICE_ACTIVITY_RETENTION_DAYS', 365),
    'cleanup_batch_size' => 1000,
],
```

### Guard Configuration

[](#guard-configuration)

```
'guards' => [
    'web' => [
        'enabled' => true,
        'session_lifetime' => 120,
        'track_ip' => true,
        'track_user_agent' => true,
        'track_device_type' => true,
        'track_os' => true,
        'track_browser' => true,
        'track_country' => true,
    ],
    'api' => [
        'enabled' => true,
        'token_lifetime' => 20160,
        'track_ip' => true,
        'track_user_agent' => true,
        'track_device_type' => true,
        'track_os' => true,
        'track_browser' => true,
        'track_country' => true,
    ],
],
```

### Features

[](#features-1)

```
'features' => [
    'allow_multiple_sessions' => env('DEVICE_ACTIVITY_MULTIPLE_SESSIONS', true),
    'max_sessions_per_user' => env('DEVICE_ACTIVITY_MAX_SESSIONS', 5),
    'notify_on_new_login' => env('DEVICE_ACTIVITY_NOTIFY_NEW_LOGIN', false),
    'auto_cleanup' => env('DEVICE_ACTIVITY_AUTO_CLEANUP', true),
],
```

### IP Lookup

[](#ip-lookup)

```
'ip_lookup' => [
    'enabled' => env('DEVICE_ACTIVITY_IP_LOOKUP', true),
    'service' => env('DEVICE_ACTIVITY_IP_SERVICE', 'ip-api.com'),
],
```

---

Usage
-----

[](#usage)

### Using the Helper Class

[](#using-the-helper-class)

The `DeviceActivityHelper` provides a simple interface for all device activity operations.

#### Create Session (Track Login)

[](#create-session-track-login)

```
use Baligs\UserDeviceActivity\Helpers\DeviceActivityHelper;

// In your LoginController
public function login(Request $request)
{
    if (Auth::attempt($credentials)) {
        $request->session()->regenerate();

        // Track the login session
        $session = DeviceActivityHelper::createSession(Auth::user(), 'web');

        return redirect()->intended('/dashboard');
    }
}
```

#### Get User Sessions

[](#get-user-sessions)

```
// Get all sessions for a user
$sessions = DeviceActivityHelper::getUserSessions($user->id, 'web');

// Get only active sessions
$activeSessions = DeviceActivityHelper::getActiveUserDevices($user->id, 'web');

// Get current session
$currentSession = DeviceActivityHelper::getCurrentSession('web');

// Get session by ID
$session = DeviceActivityHelper::getSessionById($sessionId);
```

#### Logout Operations

[](#logout-operations)

```
// Logout specific device
DeviceActivityHelper::logoutSession($sessionId);

// Logout current session
DeviceActivityHelper::logoutCurrentSession('web');

// Logout all sessions (for a specific guard)
$count = DeviceActivityHelper::logoutAllSessions($user->id, 'web');

// Logout all devices (across all guards)
$count = DeviceActivityHelper::logoutAllDevices($user->id);
```

#### Check User Status

[](#check-user-status)

```
// Check if user is online (active in last 5 minutes)
$isOnline = DeviceActivityHelper::isUserOnline($user->id);

// Check if session is active
$isActive = DeviceActivityHelper::isSessionActive($sessionId);

// Get last login info
$lastLogin = DeviceActivityHelper::getLastLogin($user->id, 'web');
$lastLoginTime = DeviceActivityHelper::getLastLoginTime($user->id, 'web');
```

#### Log Custom Activity

[](#log-custom-activity)

```
DeviceActivityHelper::logActivity('profile_update', $user->id, 'web', [
    'field' => 'email',
    'old_value' => 'old@example.com',
    'new_value' => 'new@example.com',
]);
```

---

### Using Traits

[](#using-traits)

Add the `HasDeviceActivity` trait to your User model for convenient methods:

```
// app/Models/User.php
use Baligs\UserDeviceActivity\Traits\HasDeviceActivity;

class User extends Authenticatable
{
    use HasDeviceActivity;
}
```

Now you can use:

```
// Get user's active sessions
$user->getActiveSessions('web');

// Get all sessions
$user->getAllSessions('web');

// Get last login
$user->getLastLogin('web');

// Check if online
$user->isOnline();

// Get activity stats
$stats = $user->getActivityStats('web', 30);

// Get recent activities
$activities = $user->getRecentActivities(50, 'web');

// Logout methods
$user->logoutAllSessions('web');
$user->logoutAllDevices();
```

---

### Login Controller Integration

[](#login-controller-integration)

Here's a complete example of integrating the package with your login controller:

```
// app/Http/Controllers/Auth/LoginController.php
use Baligs\UserDeviceActivity\Helpers\DeviceActivityHelper;

class LoginController extends Controller
{
    public function login(Request $request)
    {
        $this->validateLogin($request);

        if (Auth::attempt($this->credentials($request))) {
            $request->session()->regenerate();

            // Track device activity on login
            DeviceActivityHelper::createSession(Auth::user(), 'web');

            return $this->sendLoginResponse($request);
        }

        // Track failed login attempt
        DeviceActivityHelper::logActivity('login_failed', 0, 'web', [
            'email' => $request->email,
            'ip' => $request->ip(),
        ]);

        return $this->sendFailedLoginResponse($request);
    }

    public function logout(Request $request)
    {
        // Track logout before logging out
        DeviceActivityHelper::logoutCurrentSession('web');

        Auth::logout();
        $request->session()->invalidate();
        $request->session()->regenerateToken();

        return redirect('/');
    }
}
```

For API authentication (Sanctum):

```
// app/Http/Controllers/Auth/ApiAuthController.php
use Baligs\UserDeviceActivity\Helpers\DeviceActivityHelper;
use Laravel\Sanctum\Sanctum;

public function login(Request $request)
{
    $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    $user = User::where('email', $request->email)->first();

    if (!$user || !Hash::check($request->password, $user->password)) {
        DeviceActivityHelper::logActivity('login_failed', 0, 'api', [
            'email' => $request->email,
        ]);
        return response()->json(['error' => 'Invalid credentials'], 401);
    }

    // Create Sanctum token
    $token = $user->createToken('api-token')->plainTextToken;

    // Track the session
    DeviceActivityHelper::createSession($user, 'api', $token);

    return response()->json([
        'user' => $user,
        'token' => $token,
    ]);
}

public function logout(Request $request)
{
    // Revoke current token
    $request->user()->currentAccessToken()->delete();

    // Track logout
    DeviceActivityHelper::logoutCurrentSession('api');

    return response()->json(['message' => 'Logged out']);
}
```

---

### Middleware

[](#middleware)

The package provides middleware to automatically track page views:

```
// routes/web.php
Route::middleware(['auth', 'track.device.activity:web'])->group(function () {
    // All routes here will have activity tracked
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

// routes/api.php
Route::middleware(['auth:sanctum', 'track.device.activity:api'])->group(function () {
    // API routes with activity tracking
    Route::get('/user/profile', [ProfileController::class, 'show']);
});
```

---

Statistics
----------

[](#statistics)

### Get Overview Stats

[](#get-overview-stats)

```
$stats = DeviceActivityHelper::getOverviewStats(30);
// Returns: total_active_sessions, total_logins, unique_users, etc.
```

### Get All Stats

[](#get-all-stats)

```
$allStats = DeviceActivityHelper::getAllStats(30);
// Returns comprehensive stats including all categories
```

### Get Specific Stats

[](#get-specific-stats)

```
// By Country
$byCountry = DeviceActivityHelper::getLoginsByCountry(30);

// By Device Type
$byDeviceType = DeviceActivityHelper::getActiveUsersByDeviceType(30);

// By Operating System
$byOS = DeviceActivityHelper::getActiveUsersByOS(30);

// By Browser
$byBrowser = DeviceActivityHelper::getActiveUsersByBrowser(30);

// Top Active Users
$topUsers = DeviceActivityHelper::getTopActiveUsers(30, 10);

// Login Success Rate
$successRate = DeviceActivityHelper::getLoginSuccessRate(30);
// Returns: total_attempts, successful, failed, success_rate

// Session Stats
$sessionStats = DeviceActivityHelper::getSessionStats(30);
// Returns: total_sessions, active_sessions, completed_sessions, avg_duration_minutes

// Guard Stats
$guardStats = DeviceActivityHelper::getGuardStats(30);

// Logins by Day
$loginsByDay = DeviceActivityHelper::getLoginsByDay(30);

// Hourly Activity
$hourlyActivity = DeviceActivityHelper::getHourlyActivity(7);

// Recent Logins
$recentLogins = DeviceActivityHelper::getRecentLogins(20);

// Activity Breakdown
$breakdown = DeviceActivityHelper::getActivityBreakdown(30);
```

---

Dashboard
---------

[](#dashboard)

Access the dashboard at: `/admin/device-activity`

### Dashboard Pages

[](#dashboard-pages)

RouteDescription`/admin/device-activity`Main dashboard with all stats`/admin/device-activity/sessions`View all sessions`/admin/device-activity/activities`View all activities`/admin/device-activity/user/{id}/devices`View user's devices### Dashboard Statistics (20 Types)

[](#dashboard-statistics-20-types)

1. **Active Sessions** - Total active sessions
2. **Total Logins** - Successful logins count
3. **Unique Users** - Distinct users
4. **Countries** - Unique countries count
5. **Online Now** - Currently online users
6. **Total Logouts** - Logout events count
7. **Failed Logins** - Failed login attempts
8. **Devices Logged Out** - Manual device logouts
9. **By Device Type** - Desktop/Mobile/Tablet
10. **By Operating System** - Windows/Mac/Linux/Android/iOS
11. **By Browser** - Chrome/Firefox/Safari/Edge
12. **Login Success Rate** - Success percentage
13. **Guard Statistics** - Web vs API usage
14. **Session Statistics** - Session counts & duration
15. **Activity Breakdown** - All activity types
16. **Top Countries** - Most active countries
17. **Top Active Users** - Most active users
18. **Recent Logins** - Latest login activities
19. **Hourly Activity** - Activity by hour
20. **Logins by Day** - Daily login trends

---

API Endpoints
-------------

[](#api-endpoints)

### Session Endpoints

[](#session-endpoints)

```
GET    /api/device-activity/sessions
       - List all sessions for current user

GET    /api/device-activity/sessions/active
       - List active sessions only

GET    /api/device-activity/sessions/current
       - Get current session

GET    /api/device-activity/sessions/{id}
       - Get specific session

DELETE /api/device-activity/sessions/{id}
       - Logout specific session

POST   /api/device-activity/sessions/{id}/logout
       - Logout specific session

POST   /api/device-activity/sessions/logout-current
       - Logout current session

POST   /api/device-activity/sessions/logout-all
       - Logout all sessions for current user

POST   /api/device-activity/sessions/logout-all-devices
       - Logout all devices (all guards)

GET    /api/device-activity/sessions/stats
       - Get user's activity stats

```

### Stats Endpoints

[](#stats-endpoints)

```
GET    /api/device-activity/stats/overview
       - Overview statistics

GET    /api/device-activity/stats/by-country
       - Logins by country

GET    /api/device-activity/stats/by-device-type
       - By device type

GET    /api/device-activity/stats/by-os
       - By operating system

GET    /api/device-activity/stats/by-browser
       - By browser

GET    /api/device-activity/stats/top-users
       - Top active users

GET    /api/device-activity/stats/logins-by-day
       - Daily login trends

GET    /api/device-activity/stats/activity-breakdown
       - All activity types

GET    /api/device-activity/stats/hourly-activity
       - Hourly activity

GET    /api/device-activity/stats/session-stats
       - Session statistics

GET    /api/device-activity/stats/guard-stats
       - Guard statistics

GET    /api/device-activity/stats/login-success-rate
       - Login success rate

GET    /api/device-activity/stats/all
       - All statistics combined

```

### Example API Response

[](#example-api-response)

```
{
    "success": true,
    "data": {
        "total_active_sessions": 15,
        "total_logins": 245,
        "total_logouts": 230,
        "unique_users": 42,
        "unique_countries": 8,
        "failed_logins": 12,
        "online_users": 5,
        "devices_logged_out": 8
    }
}
```

---

Artisan Commands
----------------

[](#artisan-commands)

### Install Package

[](#install-package)

```
php artisan device-activity:install
```

### Cleanup Old Data

[](#cleanup-old-data)

```
# Cleanup using default retention days
php artisan device-activity:cleanup

# Cleanup data older than 30 days
php artisan device-activity:cleanup --days=30
```

### Auto Cleanup

[](#auto-cleanup)

Enable automatic cleanup in config:

```
// config/user-device-activity.php
'features' => [
    'auto_cleanup' => true, // Runs daily at midnight
],
```

Or add to your `app/Console/Kernel.php`:

```
protected function schedule(Schedule $schedule): void
{
    $schedule->command('device-activity:cleanup')->daily();
}
```

---

Troubleshooting
---------------

[](#troubleshooting)

### Database Connection Issues

[](#database-connection-issues)

**Error: "could not find driver"**

- Make sure SQLite PHP extension is enabled
- Or configure MySQL/PostgreSQL in config

**Error: "Database does not exist"**

- Create the SQLite file: `touch database/user_device_activity.sqlite`
- Or ensure MySQL database exists

### IP Lookup Not Working

[](#ip-lookup-not-working)

**Country shows as "Unknown"**

- Check if `DEVICE_ACTIVITY_IP_LOOKUP=true` in .env
- Verify internet connection (IP lookup requires external API)
- Localhost (127.0.0.1) won't show country info

### Sessions Not Tracking

[](#sessions-not-tracking)

**Login not creating session**

- Ensure `DeviceActivityHelper::createSession()` is called after successful login
- Check if user object has `id` property

**Middleware not tracking**

- Add `track.device.activity:web` or `track.device.activity:api` middleware
- Ensure middleware runs after authentication

### Helper Class Issues

[](#helper-class-issues)

**Helper methods not found**

- Clear cache: `php artisan config:clear`
- Check if package is registered in `config/app.php`

### Permission Issues

[](#permission-issues)

**Cannot create database file**

```
chmod 775 database
touch database/user_device_activity.sqlite
chmod 664 database/user_device_activity.sqlite
```

---

Support
-------

[](#support)

For issues or feature requests, visit:

- GitHub:
- Packagist:

---

License
-------

[](#license)

MIT License - Copyright (c) 2024 baligs

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance75

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

141d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c7606e3c9b188a0725f394c41cf3a3250f234df640b0416ba509aa097227fb9a?d=identicon)[baligs](/maintainers/baligs)

---

Top Contributors

[![baligs](https://avatars.githubusercontent.com/u/92466611?v=4)](https://github.com/baligs "baligs (1 commits)")

### Embed Badge

![Health badge](/badges/baligs-user-device-activity/health.svg)

```
[![Health](https://phpackages.com/badges/baligs-user-device-activity/health.svg)](https://phpackages.com/packages/baligs-user-device-activity)
```

###  Alternatives

[laravel/octane

Supercharge your Laravel application's performance.

4.0k28.5M253](/packages/laravel-octane)[friendsoftypo3/content-blocks

TYPO3 CMS Content Blocks - Content Types API | Define reusable components via YAML

103574.3k64](/packages/friendsoftypo3-content-blocks)[flarum/core

Delightfully simple forum software.

211.5M2.4k](/packages/flarum-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)