heccubernny/activity-tracker

A lightweight Laravel package to track user and model activities

v1.0.2 2025-09-20 23:48 UTC

Requires

• php: >=8.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0

MIT

• Ikubanni Paul

README

⚠️ Note: This package is currently in development and not yet production-ready. Some bugs and issues may still exist. Use at your own risk.

A lightweight Laravel package to track user and model activities for web and API applications.

This package allows you to automatically track model events (created, updated, deleted) and route visits, as well as manually log custom activities. It supports both JWT-based API authentication and web session authentication.

Installation

Install via Composer:

composer require heccubernny/activity-tracker

Publish configuration and migrations:

php artisan vendor:publish --provider="Heccubernny\ActivityTracker\ActivityServiceProvider" --tag="activitytracker-config"

php artisan vendor:publish --provider="Heccubernny\ActivityTracker\ActivityServiceProvider" --tag="activitytracker-migrations"

php artisan migrate

Middleware Setup

Register the middleware in app/Http/Kernel.php:

protected $routeMiddleware = [
    // ...
    'activity.log' => \Heccubernny\ActivityTracker\Middleware\LogRouteActivity::class,
];

Apply middleware to routes:

Route::get('/dashboard', function () {
    // ...
})->middleware('activity.log:visited-dashboard');

You can optionally pass a subject (model) to associate with the activity:

Route::get('/posts/{post}', function (App\Models\Post $post) {
    // ...
})->middleware(\Heccubernny\ActivityTracker\Middleware\LogRouteActivity::class.':view-post,' . $post->id);

Automatic Model Logging

Add the LogsActivity trait to any model you want to track:

use Heccubernny\ActivityTracker\Traits\LogsActivity;

class Post extends Model
{
    use LogsActivity;
}

By default, it tracks:

• created

• updated

• deleted

and logs:

• subject_id

• subject_type

• user_id

• user_type

• description

• properties (full model attributes)

• ip_address, url, method, agent

Manual Logging

Use the activity() facade for custom events:

activity()->log([
    'name' => 'exported-report',
    'description' => 'User exported the monthly sales report',
    'properties' => ['report' => 'monthly-sales'],
    // Optional: user_id, user_type, subject_id, subject_type
]);

or directly on a model

$post->logActivity('published', ['description' => 'Published via admin panel']);

Configuration (Optional)

You can set the activity retention in your .env:

ACTIVITY_RETENTION_DAYS=null

• null keeps logs forever.

• Set to a number of days to automatically purge old logs.

Example Usage

Manual logging:

activity()->log([
    'name' => 'exported-report',
    'description' => 'User exported the monthly sales report',
    'properties' => ['report' => 'monthly-sales'],
]);

Automatic model logging:

$post = Post::find(1);
$post->logActivity('published', ['description' => 'Published via admin panel']);

Route-based logging:

Route::get('/dashboard', function () {
    // ...
})->middleware('activity.log:visited-dashboard');

Credits

Special thanks to Nuno Maduro for his dry repository it was the skeleton inspiration.

License: MIT