Laravel Activity Log

https://spatie.be/docs/laravel-activitylog/v5
Admin
Laravel Activity Log is a package that provides easy-to-use functions to log user activities and...
Tokens:14,374
Snippets:125
Trust Score:9.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example of logging JSON sub-keys

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Demonstrates creating and updating a model with JSON attributes, and then inspecting the logged attribute changes to see how specific sub-keys are recorded.

```php
// Create a news item.
$newsItem = NewsItem::create([
    'name' => 'Title',
    'preferences' => [
        'notifications' => [
            'status' => 'off',
        ],
        'hero_url' => ''
    ],
]);

// Update the json object
$newsItem->update([
    'preferences' => [
        'notifications' => [
            'status' => 'on',
        ],
        'hero_url' => 'http://example.com/hero.png'
    ],
]);

$lastActivity = Activity::latest()->first();

$lastActivity->attribute_changes->toArray();
```

--------------------------------

### Basic Model Setup with LogsActivity Trait

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Use the `LogsActivity` trait in your Eloquent model to enable automatic logging of created, updated, and deleted events. No initial configuration is needed for basic logging.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;

class NewsItem extends Model
{
    use LogsActivity;
}
```

--------------------------------

### Logging Model Creation Event

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

When a model is created, an activity log entry is generated. This example shows how to retrieve the last activity log and inspect its properties like `description` and `subject`.

```php
$newsItem = NewsItem::create([
   'name' => 'original name',
   'text' => 'Lorem'
]);

//creating the newsItem will cause an activity to be logged
$activity = Activity::all()->last();

$activity->description; //returns 'created'
$activity->subject; //returns the instance of NewsItem that was created
$activity->attribute_changes; //returns a collection containing ['attributes' => ['name' => 'original name', 'text' => 'Lorem']];
```

--------------------------------

### Logging Model Update Event

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Updating a model instance triggers an activity log. This example demonstrates how to update a model, retrieve the latest activity, and check its `description` and `subject`.

```php
$newsItem->name = 'updated name';
$newsItem->save();

//updating the newsItem will cause an activity to be logged
$activity = Activity::all()->last();

$activity->description; //returns 'updated'
$activity->subject; //returns the instance of NewsItem that was updated
```

--------------------------------

### Example output of JSON sub-key logging

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Shows the structure of the logged attribute changes when specific JSON sub-keys are targeted, highlighting the 'attributes' and 'old' values for the logged keys.

```json
// output
[
    "attributes" => [
        "preferences" => [
            "notifications" => [
                "status" => "on",
            ],
            "hero_url" => "http://example.com/hero.png",
        ],
    ],
    "old" => [
        "preferences" => [
            "notifications" => [
                "status" => "off",
            ],
            "hero_url" => "",
        ],
    ],
]
```

--------------------------------

### Configuring Logged Attributes with LogOptions

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Override the `getActivitylogOptions()` method to return a `LogOptions` instance. Use `LogOptions::defaults()` and fluent methods like `logOnly()` to specify which attributes should be logged. This example logs only 'name' and 'text'.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;

class NewsItem extends Model
{
    use LogsActivity;

    protected $fillable = ['name', 'text'];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
        ->logOnly(['name', 'text']);
    }
}
```

--------------------------------

### Customize activity description for events

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Provide a callback to `setDescriptionForEvent` to dynamically set the activity description based on the event name. This example sets a custom description for created, updated, and deleted events.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;

class NewsItem extends Model
{
    use LogsActivity;

    protected $fillable = ['name', 'text'];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
        ->setDescriptionForEvent(fn(string $eventName) => "This model has been {$eventName}");
    }
}
```

--------------------------------

### Log only specific events

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Configure a model to log only specific Eloquent events by setting the static `$recordEvents` property. This example logs only the 'deleted' event.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;

class NewsItem extends Model
{
    use LogsActivity;

    //only the `deleted` event will get logged automatically
    protected static $recordEvents = ['deleted'];
}
```

--------------------------------

### Retrieve activities caused by a model

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Use the `activitiesAsCauser()` relationship provided by the `CausesActivity` trait to get all activities caused by a specific model instance.

```php
Auth::user()->activitiesAsCauser;
```

--------------------------------

### Configure logging to skip if only certain attributes change

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Use `dontLogIfAttributesChangedOnly` to prevent activity logging when only specified attributes are modified. This example prevents logging if only the 'text' attribute changes.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;

class NewsItem extends Model
{
    use LogsActivity;

    protected $fillable = ['name', 'text'];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
        ->logOnly(['name', 'text'])
        ->dontLogIfAttributesChangedOnly(['text']);
    }
}
```

--------------------------------

### Exclude specific events from logging

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Configure a model to exclude specific Eloquent events from being logged by setting the static `$doNotRecordEvents` property. This example excludes the 'created' event.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;

class NewsItem extends Model
{
    use LogsActivity;

    //the `created` event will not be logged
    protected static $doNotRecordEvents = ['created'];
}
```

--------------------------------

### Verify custom description after creation

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

After creating a model with a custom description configuration, retrieve the activity log to verify that the description matches the configured callback.

```php
$newsItem = NewsItem::create([
   'name' => 'original name',
   'text' => 'Lorem'
]);

//creating the newsItem will cause an activity to be logged
$activity = Activity::all()->last();

$activity->description; //returns 'This model has been created'
```

--------------------------------

### Enable and Disable Logging for Model Updates

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Demonstrates how to disable logging for specific updates and then re-enable it using `disableLogging()` and `enableLogging()` methods on a model instance.

```php
$newsItem = NewsItem::create([
   'name' => 'original name',
   'text' => 'Lorem'
]);

// Updating with logging disabled
$newsItem->disableLogging();

$newsItem->update(['name' => 'The new name is not logged']);

// Updating with logging enabled
$newsItem->enableLogging();

$newsItem->update(['name' => 'The new name is logged']);
```

--------------------------------

### Log Activities on Pivot Models

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Configure a custom pivot model to enable activity logging. This requires adding an `id` primary key to the pivot table and setting `$incrementing` to `true` on the pivot model.

```php
use Illuminate\Database\Eloquent\Relations\Pivot;
use Spatie\Activitylog\Models\Concerns\LogsActivity;

final class PivotModel extends Pivot
{
    use LogsActivity;

    public $incrementing = true;
}
```

--------------------------------

### Customize Activity Description Before Logging

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Implement the `beforeActivityLogged` method on a model to modify the `Activity` object before it is saved. This allows for dynamic setting of properties like `description` based on the event name.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Contracts\Activity;
use Spatie\Activitylog\Models\Concerns\LogsActivity;

class NewsItem extends Model
{
    use LogsActivity;

    public function beforeActivityLogged(Activity $activity, string $eventName)
    {
        $activity->description = "activity.logs.message.{$eventName}";
    }
}
```

--------------------------------

### Using the HasActivity trait for models

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Combine `LogsActivity` and `CausesActivity` by using the `HasActivity` trait. This provides `activities()`, `activitiesAsSubject()`, and `activitiesAsCauser()` relationships. Ensure the `getActivitylogOptions()` method is implemented to define logging behavior.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\HasActivity;
use Spatie\Activitylog\Support\LogOptions;

class User extends Model
{
    use HasActivity;

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
        ->logFillable();
    }
}
```

--------------------------------

### Querying activities by subject, causer, and event

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

The `Activity` model offers query scopes to filter activities. You can filter by subject, causer, and event type, and combine these scopes for more specific queries.

```php
use Spatie\Activitylog\Models\Activity;

// get all activities for a specific subject
Activity::forSubject($newsItem)->get();

// get all activities caused by a specific user
Activity::causedBy($user)->get();

// get all activities for a specific event
Activity::forEvent('updated')->get();

// these scopes can be combined
Activity::forSubject($newsItem)->causedBy($user)->forEvent('updated')->get();
```

--------------------------------

### Log only specific attributes

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Use `logOnly` to specify which attributes should be logged. This is useful when you only want to track changes to a subset of model attributes.

```php
use Spatie\Activitylog\Support\LogOptions;

public function getActivitylogOptions(): LogOptions
{
    return LogOptions::defaults()
        ->logOnly(['name', 'text']);
}
```

--------------------------------

### Prevent logging empty changes

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Use `dontLogEmptyChanges` to prevent the package from storing logs when no specified attributes have actually changed. This is useful in conjunction with `logOnly`.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;

class NewsItem extends Model
{
    use LogsActivity;

    protected $fillable = ['name', 'text'];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
        ->logOnly(['text'])
        ->logOnlyDirty()
        ->dontLogEmptyChanges();
    }
}
```

--------------------------------

### Logging All Fillable Attributes

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

To log changes to all attributes defined in the `$fillable` property, chain the `->logFillable()` method on the `LogOptions` instance.

```php
return LogOptions::defaults()
    ->logFillable();
```

--------------------------------

### Log only dirty attributes

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Employ `logOnlyDirty` to ensure that only attributes that have actually changed during an update are recorded in the activity log. This is useful for reducing log verbosity.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;

class NewsItem extends Model
{
    use LogsActivity;

    protected $fillable = ['name', 'text'];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
        ->logOnlyDirty();
    }
}
```

--------------------------------

### Logging All Guarded Attributes

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

If you use `$guarded` instead of `$fillable`, you can log all attributes not listed in `$guarded` by chaining the `->logUnguarded()` method.

```php
return LogOptions::defaults()
    ->logUnguarded();
```

--------------------------------

### Exclude attributes from log output

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Use `logExcept` to exclude specific attributes from appearing in the logged changes, even when using wildcard logging like `logAll`. This is useful for sensitive or irrelevant fields.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;

class NewsItem extends Model
{
    use LogsActivity;

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
        ->logAll()
        ->logExcept(['password', 'remember_token']);
    }
}
```

--------------------------------

### Using the ActivityEvent enum

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

The `ActivityEvent` enum provides constants for built-in event types like Created, Updated, Deleted, and Restored. Use these constants when querying activities or manually logging events.

```php
use Spatie\Activitylog\Enums\ActivityEvent;

ActivityEvent::Created;
ActivityEvent::Updated;
ActivityEvent::Deleted;
ActivityEvent::Restored;
```

```php
use Spatie\Activitylog\Models\Activity;

Activity::forEvent(ActivityEvent::Created)->get();

activity()->event(ActivityEvent::Updated)->log('...');
```

--------------------------------

### Set a custom log name for a model

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Use the `useLogName` method within `getActivitylogOptions` to assign a specific log name to activities generated by a model, differentiating them from the default log.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;

class NewsItem extends Model
{
    use LogsActivity;

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
        ->useLogName('system');
    }
}
```

--------------------------------

### Log only dirty attributes

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Use `logOnlyDirty` to log only attributes that have actually changed during an update. This prevents logging attributes that were updated but retained their original value.

```php
use Spatie\Activitylog\Support\LogOptions;

public function getActivitylogOptions(): LogOptions
{
    return LogOptions::defaults()
        ->logOnly(['name', 'text'])
        ->logOnlyDirty();
}
```

--------------------------------

### Log specific JSON attribute sub-keys

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Use arrow notation in `logOnly` to log changes to specific sub-keys within a JSON column. Ensure the JSON column is cast to a collection.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;

class NewsItem extends Model
{
    use LogsActivity;

    protected $fillable = ['preferences', 'name'];

    protected $casts = [
        'preferences' => 'collection' // casting the JSON database column
    ];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
        ->logOnly(['preferences->notifications->status', 'preferences->hero_url']);
    }
}
```

--------------------------------

### Viewing logged activity after deletion

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

After deleting a model, you can retrieve the last logged activity to inspect its properties like description and attribute changes.

```php
$newsItem->delete();

//deleting the newsItem will cause an activity to be logged
$activity = Activity::all()->last();

$activity->description; //returns 'deleted'
$activity->attribute_changes; //returns a collection containing ['old' => ['name' => 'updated name', 'text' => 'Lorem']];
```

--------------------------------

### Log attributes of related models

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Log attributes from directly related models using dot notation in `logOnly`. Ensure the relationship is defined in your model.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;

class NewsItem extends Model
{
    use LogsActivity;

    protected $fillable = ['name', 'text', 'user_id'];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
        ->logOnly(['name', 'text', 'user.name']);
    }

    public function user()
    {
        return $this->belongsTo(User::class);
    }
}
```

--------------------------------

### Disabling logging for a model instance

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

Use the `disableLogging()` method on a model instance to prevent logging for specific operations like updates. This method only affects the current instance.

```php
$newsItem = NewsItem::create([
   'name' => 'original name',
   'text' => 'Lorem'
]);

// Updating with logging disabled
$newsItem->disableLogging();

$newsItem->update(['name' => 'The new name is not logged']);
```

--------------------------------

### Inspecting Attribute Changes on Update

Source: https://spatie.be/docs/laravel-activitylog/v5/advanced-usage/logging-model-events

After a model update, the `attribute_changes` property on the activity log contains details about the modified attributes. It includes both the new and old values for the changed fields.

```php
Calling $activity->attribute_changes will return a collection containing:

[
   'attributes' => [
        'name' => 'updated name',
        'text' => 'Lorem',
    ],
    'old' => [
        'name' => 'original name',
        'text' => 'Lorem',
    ],
];
```
Tokens:
Raw