Laravel Activity Log Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require shkiper/laravel-activity-log
   

2. Publish config and migrations:

   php artisan vendor:publish --provider="Shkiper\ActivityLog\ActivityLogServiceProvider"
   

3. Run migrations (default uses mysql):

   php artisan migrate
   

First Use Case: Logging Model Changes

Add the LogsActivity trait to a model (e.g., User):

use Shkiper\ActivityLog\Traits\LogsActivity;

class User extends Model
{
    use LogsActivity;

    protected static $logAttributes = ['name', 'email']; // Fields to log
    protected static $logName = 'user'; // Log entry identifier
}

Now, any created, updated, or deleted events on User will auto-log to the activity_log table.

Implementation Patterns

1. Model-Level Logging

• Basic Logging: Use $logAttributes to specify fields (e.g., ['name', 'email']).
• Event Filtering: Restrict logging to specific events (e.g., $logEvents = ['created', 'updated']).
• Dirty Attributes: Enable $logOnlyDirty = true to log only changed fields.

2. Custom Log Entries

Override getActivityLogDescription() for custom descriptions:

public function getActivityLogDescription(): string
{
    return "User {$this->name} updated their email to {$this->email}";
}

3. Asynchronous Logging

Configure queue settings in config/activity-log.php:

'driver' => 'queue',
'queue' => 'activity-log',

Dispatch logs via ActivityLog::dispatch() in observers/events.

4. Multi-Driver Support

Switch storage backends (e.g., MongoDB/ClickHouse) by updating config/activity-log.php:

'driver' => 'mongodb',
'connection' => 'mongodb',

5. Querying Logs

Use the ActivityLog facade to fetch logs:

// Get all logs for a model
ActivityLog::query()
    ->where('subject_type', User::class)
    ->where('subject_id', 1)
    ->get();

6. Integration with Observers

Pair with Laravel observers for granular control:

class UserObserver
{
    public function saved(User $user)
    {
        if ($user->wasChanged('email')) {
            ActivityLog::log($user, 'custom_event', ['old_email' => $user->getOriginal('email')]);
        }
    }
}

Gotchas and Tips

Pitfalls

1. Missing Migrations: Forgetting to run php artisan migrate after publishing will break logging.
2. Queue Stuck Jobs: If using async logging, monitor the activity-log queue for failures.
3. Overhead: Logging all fields ($logAttributes = ['*']) can bloat storage. Use $logOnlyDirty to optimize.
4. Driver Mismatch: Ensure the configured driver (e.g., mongodb) matches your setup.

Debugging

• Check Logs: Verify entries in activity_log table or MongoDB collection.
• Queue Debugging: Use php artisan queue:work --queue=activity-log --verbose to debug async issues.
• Event Conflicts: If logs aren’t firing, check for observer/event collisions (e.g., saved vs updating).

Tips

1. Exclude Sensitive Data: Avoid logging password or api_token fields.
2. Custom Fields: Add metadata via $logExtra:

   protected static $logExtra = ['ip_address', 'user_agent'];
   

3. Soft Deletes: Ensure deleted_at is logged if using soft deletes:

   protected static $logAttributes = ['*'];
   

4. Performance: For high-traffic models, batch logs or use a separate queue.
5. Testing: Mock ActivityLog in tests:

   $this->partialMock(ActivityLog::class, ['log']);
   

Extension Points

• Custom Drivers: Extend Shkiper\ActivityLog\Contracts\ActivityLogDriver for new storage backends.
• Log Formatting: Override ActivityLog::formatLog() to modify log structure.
• Webhooks: Trigger external actions (e.g., Slack) via ActivityLog::afterLog().