Search by

herca / activity-log

herca

Activity logging package for Laravel

Package info

github.com/metcore/activity-log

pkg:composer/herca/activity-log

Statistics

Installs: 22

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.1.0 2026-11-04 03:52 UTC

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, and deleted model events, plus restored on models using SoftDeletes
  • Manual logging through a fluent ActivityLogger service
  • Polymorphic relation between the logged model and activity entries
  • Snapshot support for attributes (current values) and old (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:

  • created
  • updated
  • deleted
  • restored (only when the model uses SoftDeletes)

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 for created. The changed attributes are the keys of old, compared against attributes.

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:

  • type
  • snapshot
  • note
  • request_id
  • related_id
  • created_by
  • created_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:

  1. get_request_id() helper when enabled
  2. Request headers such as X-Request-Id or X-Correlation-Id
  3. Request attribute request_id
  4. 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 $logIgnoreAttributes replaces default_ignore_attributes from the config instead of being merged with it.

License

This package is open-sourced under the MIT license.