herca / activity-log
Activity logging package for Laravel
Requires
- php: ^8.0
- illuminate/database: ^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
Requires (Dev)
- orchestra/testbench: ^6.0|^7.0|^8.0|^9.0|^10.0|^11.0
- phpunit/phpunit: ^9.0|^10.0|^11.0|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is not auto-updated.
Last update: 2026-11-18 04:19:26 UTC
README
A lightweight Laravel package for recording model activity logs, both automatically and manually.
Features
- Automatic logging for
created,updated, anddeletedmodel events, plusrestoredon models usingSoftDeletes - Manual logging through a fluent
ActivityLoggerservice - Polymorphic relation between the logged model and activity entries
- Snapshot support for
attributes(current values) andold(previous values of the changed attributes) - Request correlation through
request_id - Optional actor tracking through
created_by - Configurable ignored attributes
Installation
Install the package with Composer in your Laravel application:
composer require herca/activity-log
Register the service provider if your Laravel version does not support package auto-discovery.
Publish Assets
Publish the configuration:
php artisan vendor:publish --tag=activity-log-config
Publish the migration:
php artisan vendor:publish --tag=activity-log-migrations
Run migrations:
php artisan migrate
Basic Usage
Add the LogActivity trait to any Eloquent model you want to track.
<?php namespace App\Models; use Herca\ActivityLog\Traits\LogActivity; use Illuminate\Database\Eloquent\Model; class Post extends Model { use LogActivity; }
Once attached, the model will automatically record activity for:
createdupdateddeletedrestored(only when the model usesSoftDeletes)
Restoring a model logs a single restored entry. The updated event that Laravel fires during restore() is not logged.
Manual Logging
You can also create manual activity entries using the helper:
activity_log($post) ->causedBy(auth()->user()) ->withNote('Post published manually') ->withSnapshot([ 'attributes' => $post->getAttributes(), 'old' => ['status' => 'draft'], ]) ->log('published');
If your model uses the provided contract/trait API, you can also log directly from the model:
$post->logActivity('published', [ 'note' => 'Published from admin panel', 'status' => 'published', 'old' => ['status' => 'draft'], ]);
note, old, and attributes (replaces the stored model attributes) are reserved keys. Every other key is a new value and is merged into attributes. A changes array from older versions is merged the same way.
Snapshot Format
Every snapshot has two keys:
{
"attributes": {"title": "Published", "status": "published"},
"old": {"title": "Draft"}
}
attributes: the model values after the event, without ignored attributes.old: the previous values of the changed attributes. It is empty forcreated. The changed attributes are the keys ofold, compared againstattributes.
Snapshots written before v1.1.0 also contain a changes key. It duplicated data that is already in attributes, so it is no longer stored.
Controlling Logging
You can enable or disable logging at runtime:
$post->disableLogging(); $post->enableLogging(); $post->setLogActivityEnabled(false);
You can also manage ignored attributes:
$post->setLogIgnoreAttributes(['updated_at', 'last_seen_at']); $post->addLogIgnoreAttribute('synced_at'); $post->removeLogIgnoreAttribute('synced_at'); $post->clearRuntimeLogIgnoreAttributes();
Activity Model
The package stores logs with fields such as:
typesnapshotnoterequest_idrelated_idcreated_bycreated_at
Each activity entry belongs to a subject through a polymorphic relation, and to the user that caused it through createdBy():
$post->activities()->with('createdBy')->latest()->get();
createdBy() uses the user_model config value, or auth.providers.users.model when it is null.
To use your own activity model, extend Herca\ActivityLog\Models\ActivityLog and set it as the model config value. The activities() relation and the logger both use that class.
Request ID Resolution
The package resolves request_id in this order:
get_request_id()helper when enabled- Request headers such as
X-Request-IdorX-Correlation-Id - Request attribute
request_id - A generated ULID or ordered UUID
Events
An ActivityLogged event is dispatched whenever a new activity record is stored. You can listen to this event to trigger notifications, auditing workflows, or downstream processing.
Notes
- Review the config file after publishing to customize table name, model class, user model, and ignored attributes.
- A model's
$logIgnoreAttributesreplacesdefault_ignore_attributesfrom the config instead of being merged with it.
License
This package is open-sourced under the MIT license.