README

A powerful and easy-to-use Laravel package for automatically tracking model changes and user activities within your application. This package provides automatic model tracking and manual activity logging capabilities.

Requirements

PHP 7.4 or higher
Laravel 8.0 or higher
MySQL 5.7+ or PostgreSQL 9.6+

Installation

To install the Activity Logger Package, you can use Composer:

composer require loctracker/activity-logger

Configuration

After installation, publish the configuration and migrations:

php artisan vendor:publish --provider="Loctracker\ActivityLogger\ActivityLoggerServiceProvider"

Then run the migrations:

php artisan migrate

Configuration Options

The package can be configured through the config/activity-logger.php file. Here are all available options:

return [
    // The logging channel to use for activity logs
    'log_channel' => env('ACTIVITY_LOG_CHANNEL', 'stack'),

    // Log level for activities
    'log_level' => env('ACTIVITY_LOG_LEVEL', 'info'),

    // The model used for storing activity logs
    'activity_model' => \Loctracker\ActivityLogger\Models\ActivityLog::class,

    // Database table name for activity logs
    'table_name' => 'activity_logs',

    // Routes that should not be logged
    'ignore_routes' => [
        'horizon*',
        'nova*',
        '_debugbar*',
        'sanctum*',
        'telescope*',
    ],

    // Model events to log
    'log_events' => [
        'created' => true,
        'updated' => true,
        'deleted' => true,
        'restored' => true,
    ],

    // Default properties to log for each activity
    'default_log_properties' => [
        'ip_address' => true,    // Log IP address
        'user_agent' => true,    // Log browser user agent
        'request_method' => true, // Log HTTP method
        'request_url' => true,    // Log full URL
    ],

    // Maximum size for the properties JSON column
    'properties_max_size' => 100000,

    // Enable automatic logging of authentication events
    'log_auth_events' => true,

    // Cleanup configuration for old records
    'cleanup' => [
        'enabled' => false,
        'keep_logs_for_days' => 365,
        'chunk_size' => 1000,
    ],

    // Date format for activity timestamps
    'date_format' => 'Y-m-d H:i:s',

    // Queue configuration for logging activities
    'queue' => [
        'enabled' => false,
        'connection' => env('QUEUE_CONNECTION', 'sync'),
        'queue' => 'activity-logs',
    ],

    // Default attributes to log for all models
    'log_attributes' => ['title', 'content', 'status'],

    // Default attributes to exclude from logging
    'log_except' => ['password', 'remember_token'],

    // Fields that should always be masked in the log
    'sensitive_fields' => ['password', 'credit_card', 'api_key'],
];

Usage

Automatic Model Activity Logging

Simply add the LogsActivity trait to any model you want to track:

use Loctracker\ActivityLogger\Traits\LogsActivity;

class Post extends Model
{
    use LogsActivity;

    // Optional: specify which attributes to log
    protected static $logAttributes = ['title', 'content', 'status'];

    // OR specify which attributes to exclude from logging
    protected static $logExcept = ['password', 'remember_token'];
}

Now all create/update/delete operations on this model will be automatically logged!

Configuring Attribute Logging

You can configure which attributes to log in three ways:

In your model using properties:

use Loctracker\ActivityLogger\Traits\LogsActivity;

class Post extends Model
{
    use LogsActivity;

    // Option 1: Specify which attributes to log
    protected static $logAttributes = ['title', 'content', 'status'];

    // Option 2: Specify which attributes to exclude from logging
    protected static $logExcept = ['password', 'remember_token'];
}

In the configuration file for all models:

// config/activity-logger.php

return [
    // Default attributes to log for all models
    'log_attributes' => ['title', 'content', 'status'],

    // Default attributes to exclude from logging
    'log_except' => ['password', 'remember_token'],

    // Fields that should always be masked in the log
    'sensitive_fields' => ['password', 'credit_card', 'api_key'],
];

Let the package log all attributes (default behavior if no configuration is provided)

The priority order is:

Model-specific configuration ($logAttributes or $logExcept in the model)
Global configuration in config/activity-logger.php
Log all attributes if no configuration is found

Sensitive fields defined in sensitive_fields will always be masked with '******' in the logs, regardless of how attributes are configured.

Retrieving Logs for a Model

// Get all activities for a specific post
$post = Post::find(1);
$activities = $post->activities;

// Each activity contains:
foreach ($activities as $activity) {
    echo $activity->action;        // 'created', 'updated', 'deleted'
    echo $activity->description;   // 'Post created 1', 'Post updated 1'
    echo $activity->causer;        // User who performed the action
    echo $activity->properties;    // Changed attributes and their values
}

Manual Logging

You can also log activities manually using the facade:

use Loctracker\ActivityLogger\Facades\ActivityLogger;

// Simple log
ActivityLogger::log(
    'custom-action',
    'Custom activity description',
    $model // optional
);

// Log with additional properties
ActivityLogger::withProperties(['key' => 'value'])
    ->log('custom-action', 'Custom activity with properties', $model);

// Log with specific causer
ActivityLogger::causedBy($user)
    ->log('custom-action', 'Activity by specific user', $model);

Cleanup Old Records

To clean up old activity logs, you can use the provided artisan command:

php artisan activitylog:clean

This command will delete records older than the configured retention period (keep_logs_for_days).

Customization

Custom Activity Model

You can use your own activity model by specifying it in the configuration:

'activity_model' => \App\Models\CustomActivityLog::class

Your custom model should extend the base ActivityLog model or implement the same interface.

Queue Configuration

To improve performance, you can enable queued logging:

'queue' => [
    'enabled' => true,
    'connection' => 'redis',
    'queue' => 'activity-logs',
]

This will process the activity logging in the background.

Testing

To run the tests for the Activity Logger Package, use PHPUnit:

vendor/bin/phpunit

License

This package is open-source and available under the MIT License. See the LICENSE file for more information.

Contributing

Contributions are welcome! If you would like to contribute:

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please make sure to update tests as appropriate and follow the existing coding style.

motakabbir / activity-logger

Maintainers

Details