Getting started
Usage
Logging events
In general, the underlying spatie/laravel-activitylog package allows two things:
- Automatically log model events on Eloquent models.
- Log custom events & associate them with Eloquent models.
When logging events, there are four main properties relevant to each activity log:
| Property | Description |
|---|---|
| Subject | The Eloquent model on which the event was logged. |
| Causer |
The Eloquent model for (usually) the User that caused the event, or null when no user was logged.
|
| Event |
The programmatic name of the event as a verb in the past tense. Examples: created, updated, deleted, restored, but can also be custom events like published, unpublished, archived, verified, etc.
|
| Description | Most of the time identical to the event name, but can also be a human-readable description. |
Besides automatically logging model events, the Spatie Activitylog package also allows you to log custom events and associate them with your Eloquent models. Below, we cover how to log custom events and how to log activity in batches.
Logging custom events
It is required to always include an event name in the activity. For example, let's say that we want to log a 'published' event on a Post model. We can do this as follows:
$post = Post::find(1);
$johnDoe = User::firstWhere('email', '[email protected]');
$post->touched('published_at');
activity()
->performedOn($post)
->causedBy($johnDoe) // Not necessary if there is an authenticated user.
->event('published')
->log('published');By default, this will show an item in the timeline with the following description:
John Doe published the post.
Displaying/logging custom descriptions
Usually, the description of the activity (the string passed to the ->log('...') method) will be the same as the event name. If that is the case, then the package will automatically construct a nice human-readable string.
If you want to log a custom description instead, you can do that as well:
activity()
->performedOn($post)
->event('published')
->log('This is a custom description');Keep in mind though that this description is stored directly in the database and therefore also not translatable. If you want to use a custom description that is translatable, use the ->eventDescription() method on the component instead (see Customizing timeline items).
If you want, you can use inline markdown to apply formatting like bold or italic.
Logging activity in batches
The Spatie Activitylog package allows you to log activity in batches. You can consider a batch as a group of actions that are performed together in one go. Each timeline can display the batches and the linked activities.
You can start a new batch as follows:
LogBatch::startBatch();
$post->touch('published_at');
$post->tweet()->create(['content' => 'Check out my new blog post ✍️']);
$post->draftPosts->each(fn (DraftPost $draftPost) => $draftPost->delete());
LogBatch::endBatch();You can also start and end a batch using a closure, similar to a database transaction:
LogBatch::withinBatch(function () {
// ...
});This is the basics about batches, but there are some gotchas relating to e.g. queue jobs. You can read more about that in the documentation.
For information about logging model events and how to set it up, see the Spatie documentation. I would recommend to enable logging these model events first, and using them as the basis of your timelines.