README

A lightweight, configurable Laravel package to log and monitor user activities in your application. Capture login, logout, CRUD actions, API requests, and more — complete with IP address, user agent, and custom properties.

✨ Features

✅ Automatic Activity Logging: Automatically logs user actions (login, logout, create, update, delete)
✅ Model Event Tracking: Tracks model events for specified models
✅ Rich Metadata: Records user ID, IP address, user agent, URL, timestamps
✅ Easy Querying: Easy-to-query activity logs (Activity::forUser($id)->recent())
✅ Highly Configurable: Enable/disable features via config
✅ Extendable: Hook into activity logging for custom actions
✅ Clean Schema: Clean database schema with optional JSON properties
✅ Console Commands: Built-in commands for cleanup and statistics
✅ Traits Available: Use LogsActivity trait for automatic model tracking
✅ Laravel 9-12 Compatible: Full support for Laravel 9.x, 10.x, 11.x, and 12.x
✅ PHP 8.1-8.3 Ready: Compatible with modern PHP versions

⚡ Installation

Install the package via Composer:

composer require varatech/activity-monitor

Publish the configuration and migration files:

php artisan vendor:publish --tag="activity-monitor-config"
php artisan vendor:publish --tag="activity-monitor-migrations"

Run the migrations:

php artisan migrate

🔧 Configuration

The package comes with a comprehensive configuration file. Here are the key options:

// config/activity-monitor.php
return [
    // Enable automatic request logging
    'log_all_requests' => env('ACTIVITY_LOG_ALL_REQUESTS', false),

    // Models to automatically track
    'track_models' => [
        App\Models\Post::class,
        App\Models\Order::class,
    ],

    // Authentication event logging
    'log_authentication_events' => [
        'login' => true,
        'logout' => true,
    ],

    // Model events to track
    'log_model_events' => [
        'created' => true,
        'updated' => true,
        'deleted' => true,
    ],

    // Properties to include with each log
    'log_properties' => [
        'ip_address' => true,
        'user_agent' => true,
        'url' => true,
        'method' => true,
    ],

    // Automatic cleanup settings
    'cleanup' => [
        'enabled' => false,
        'older_than_days' => 90,
    ],
];

🚀 Usage

Manual Activity Logging

use VaraTech\ActivityMonitor\Facades\ActivityMonitor;

// Basic activity logging
ActivityMonitor::log('custom_action', [
    'note' => 'Something important happened',
    'extra_data' => 'Additional context',
]);

// Log with subject (related model)
$post = Post::find(1);
ActivityMonitor::log('post_viewed', ['ip' => request()->ip()], $post, 'User viewed blog post');

// Log authentication events
ActivityMonitor::logAuth('login', auth()->user(), ['guard' => 'web']);

// Log HTTP requests
ActivityMonitor::logRequest(request(), ['custom_property' => 'value']);

Using the LogsActivity Trait

Add the trait to your models for automatic activity logging:

use VaraTech\ActivityMonitor\Traits\LogsActivity;

class Post extends Model
{
    use LogsActivity;
    
    // Now all created, updated, deleted events are automatically logged
}

// Manual logging on the model
$post = Post::find(1);
$post->logActivity('published', ['published_at' => now()], 'Post was published');

// Get all activities for a model
$activities = $post->activities;

Querying Activities

The Activity model comes with helpful query scopes:

use VaraTech\ActivityMonitor\Models\Activity;

// Get recent activities for a user
$recent = Activity::forUser(auth()->id())->recent(20)->get();

// Get activities by action
$logins = Activity::byAction('auth.login')->get();

// Get today's activities
$today = Activity::today()->get();

// Get activities for a specific model
$postActivities = Activity::forSubject($post)->get();

// Get activities within date range
$activities = Activity::betweenDates(
    Carbon::now()->subWeek(),
    Carbon::now()
)->get();

// Complex queries
$activities = Activity::forUser(auth()->id())
    ->byAction('model.updated')
    ->where('subject_type', Post::class)
    ->recent(50)
    ->get();

Working with Activity Properties

$activity = Activity::first();

// Get a property value
$ipAddress = $activity->getProperty('ip_address');
$customData = $activity->getProperty('custom_data', 'default_value');

// Check if property exists
if ($activity->hasProperty('user_agent')) {
    echo $activity->getProperty('user_agent');
}

// Access properties directly (JSON field)
$allProperties = $activity->properties;

🛠 Advanced Usage

Automatic Model Tracking

Configure models to be automatically tracked in your config:

// config/activity-monitor.php
'track_models' => [
    App\Models\User::class,
    App\Models\Post::class,
    App\Models\Order::class,
],

Request Logging

Enable automatic request logging:

// .env
ACTIVITY_LOG_ALL_REQUESTS=true

Or in config:

'log_all_requests' => true,

Console Commands

View Activity Statistics

# Show stats for the last 30 days
php artisan activity-monitor:stats

# Show stats for the last 7 days
php artisan activity-monitor:stats --days=7

# Show stats for a specific user
php artisan activity-monitor:stats --user=123

Clean Up Old Activities

# Clean up activities older than configured days
php artisan activity-monitor:cleanup

# Clean up activities older than 30 days
php artisan activity-monitor:cleanup --days=30

# Dry run (see what would be deleted)
php artisan activity-monitor:cleanup --dry-run

📊 Database Schema

The activities table includes these fields:

🎯 Example Use Cases

Audit Trails for Admin Actions

// In your admin controller
public function deleteUser(User $user)
{
    ActivityMonitor::log('admin.user_deleted', [
        'deleted_user_id' => $user->id,
        'deleted_user_email' => $user->email,
        'reason' => request('reason'),
    ], $user, "Admin deleted user: {$user->email}");
    
    $user->delete();
}

Security Monitoring

// Track suspicious login attempts
Event::listen(\Illuminate\Auth\Events\Failed::class, function ($event) {
    ActivityMonitor::log('auth.failed', [
        'email' => $event->credentials['email'] ?? null,
        'ip_address' => request()->ip(),
        'user_agent' => request()->userAgent(),
    ], null, 'Failed login attempt');
});

API Usage Analytics

// In your API middleware
public function handle($request, Closure $next)
{
    $response = $next($request);
    
    if ($request->is('api/*')) {
        ActivityMonitor::logRequest($request, [
            'api_version' => $request->header('API-Version'),
            'response_time' => microtime(true) - LARAVEL_START,
            'response_status' => $response->getStatusCode(),
        ]);
    }
    
    return $response;
}

User Behavior Tracking

// Track user interactions
class PostController extends Controller
{
    public function show(Post $post)
    {
        $post->logActivity('viewed', [
            'referrer' => request()->header('referer'),
            'read_time_estimate' => strlen(strip_tags($post->content)) / 200, // words per minute
        ], 'User viewed blog post');
        
        return view('posts.show', compact('post'));
    }
}

🔒 Security

If you discover any security-related issues, please email constantinomsigwa@gmail.com instead of using the issue tracker.

🧪 Testing

composer test

📈 Performance Tips

1. Selective Logging: Only enable the logging you need
2. Database Indexing: The migration includes proper indexes for common queries
3. Regular Cleanup: Use the cleanup command or enable automatic cleanup
4. Async Processing: Consider queuing activity logging for high-traffic applications

🤝 Contributing

Please see CONTRIBUTING.md for details.

📝 Changelog

Please see CHANGELOG.md for more information on what has changed recently.

📄 License

The MIT License (MIT). Please see License File for more information.

🏢 About VaraAI

Vara-AI Tech is a technology company specializing in Laravel packages and SaaS solutions. We're building a comprehensive ecosystem of Laravel tools to help developers build better applications faster.

🚀 Our Laravel Package Ecosystem

• 🔐 Laravel SaaS Auth - Complete SaaS authentication system
• 📱 VaraSMS - SMS integration package
• ⚡ Recharge Meter - Utility management system
• 📊 Activity Monitor - User activity logging (this package)

🌐 Connect with VaraAI

• Organization: github.com/VaraAI
• Website: varaai.tech
• YouTube: Vara AI Tech
• Location: Korea, South
• Management: iPROTE Technology Company Limited

🌟 Credits

• Vara-AI Tech - Lead Developer
• VaraAI Organization - Package Maintainer
• iPROTE Technology Company Limited - Management
• All Contributors

📞 Contact & Support

• 🌐 Website: varaai.tech
• 📧 Email: constantinomsigwa@gmail.com
• 🐙 GitHub: @VaraAI
• 📺 YouTube: @vara-ai-tech
• 🐛 Issues: Report Issues
• 💬 Discussions: GitHub Discussions

🔮 Roadmap

• Dashboard UI for activity logs
• Export functionality (CSV, JSON)
• Real-time broadcasting (WebSockets)
• Notifications on critical actions
• Advanced filtering and search
• Performance optimizations
• Multi-tenant support