v5: PHP 8.4+, Laravel 11+, modernized API

[freekmurze]

Summary

v5 major release. Modernized API, simplified configuration, swappable action classes, PHP 8.4+/Laravel 12+.

Breaking Changes

Schema

• attribute_changes column (new, json): tracked model changes ({"attributes": {...}, "old": {...}})
• properties column: now exclusively custom user data (via withProperties())
• batch_uuid column: removed (batch system dropped)

Batch system removed

LogBatch, LogBatch facade, batch scopes all removed. Group activities with custom properties if needed.

Trait collision fix (#215, #115, #18, #224)

• activities() -> activitiesAsSubject()
• actions() -> activitiesAsCauser()
• New HasActivity trait combines both

CauserResolver facade removed

Use Activity::defaultCauser() instead.

Config simplified

• Env vars: ACTIVITY_LOGGER_* -> ACTIVITYLOG_*
• delete_records_older_than_days -> clean_after_days
• subject_returns_soft_deleted_models -> include_soft_deleted_subjects
• table_name and database_connection removed (use custom model)
• New actions config for swappable action classes

Renamed methods

v4	v5
$activity->changes()	$activity->attribute_changes
getExtraProperty()	getProperty()
dontSubmitEmptyLogs()	dontLogEmptyChanges()
withoutLogs()	withoutLogging()
$model->activities (LogsActivity)	$model->activitiesAsSubject
$model->actions (CausesActivity)	$model->activitiesAsCauser

Other breaking changes

• getActivitylogOptions() now optional (defaults to no attribute tracking)
• PHP 8.4+, Laravel 12+, Pest 4+ required
• Single consolidated migration
• Activity contract simplified to 3 methods (scopes removed from interface)

New Features

Action classes

Core operations extracted into overridable action classes:

• LogActivityAction (protected methods: resolveDescription, tapActivity, save)
• CleanActivityLogAction (protected methods: getCutOffDate, deleteOldActivities)

Swappable via config, validated by ActivitylogConfig helper.

ActivityEvent enum

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

Activity::defaultCauser() (#582, #649, #661)

Scoped or global causer override.

Global excluded columns (#1100, #460)

default_except_attributes config option.

LogOptions serialization fix (#1450)

Safely strips closures during serialization.

Boost v2 skill

resources/boost/guidelines/core.blade.php for Laravel Boost auto-discovery.

Modernization

• Str::uuid() replaces ramsey/uuid
• array_find() (PHP 8.4)
• Casts as casts() method
• $table->id(), no down() in migration
• Strict comparisons, typed parameters, dead code removed

Related

Issues: #215, #115, #18, #224, #1371, #1450, #582, #649, #661, #460
Discussions: #1063, #1100

[habibalkhabbaz]

I would suggest naming it activity_logs to match Laravel naming conventions

[Abdulmajeed-Jamaan]

Would like buffer behaviour to bulk insert logs to database, just like how laravel nightwatch do

[pxlrbt]

We heavily rely on the batch system. Any reason it gets dropped?

[freekmurze]

@pxlrbt

The batch system was removed in v5 to simplify the package. It added a lot of complexity for a feature that most users didn't need.

The good news is that you can rebuild it in userland with very little code, using the beforeLogging hook.

1. Add the column:

Schema::table('activity_log', function (Blueprint $table) {
    $table->uuid('batch_uuid')->nullable()->index();
});

2. Register the hook in your service provider:

use Illuminate\Support\Str;
use Spatie\Activitylog\Facades\Activity;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $batchUuid = null;

        Activity::beforeLogging(function ($activity) use (&$batchUuid) {
            if ($batchUuid) {
                $activity->batch_uuid = $batchUuid;
            }
        });
    }
}

3. Start and end batches wherever you need them:

$batchUuid = (string) Str::uuid();

$author = Author::create(['name' => 'Philip K. Dick']);
$book = Book::create(['title' => 'A Scanner Darkly', 'author_id' => $author->id]);
$book->update(['title' => 'Updated title']);

$batchUuid = null;

All activities between setting and clearing $batchUuid share the same UUID. This works for both manual activity()->log() calls and automatic model event logging via the LogsActivity trait.

To query by batch:

Activity::where('batch_uuid', $uuid)->get();

No custom model needed. See the beforeLogging hook docs for more details.

[freekmurze]

We've added this! Enable it with a single env variable:

ACTIVITYLOG_BUFFER_ENABLED=true

All activities are then collected in memory during the request and inserted in a single bulk query after the response is sent. No code changes needed.

Docs: https://github.com/spatie/laravel-activitylog/blob/v5/docs/advanced-usage/buffering.md

[pxlrbt]

@freekmurze Thanks for that detailed explanation.