Spatie Laravel Activity Log v5: What Changed and How to Upgrade

Spatie's laravel-activitylog package hit v5.0.0 on March 25, 2026. If you are running it in a Laravel application, this is not a routine minor bump - it is a significant breaking release that requires migration work. The batch system has been removed entirely, the database schema has changed, several methods have been renamed, and PHP 8.4 and Laravel 12 are now the minimum requirements.

This post covers everything that changed, why, and what you need to do to upgrade.

Minimum requirements

v5 requires PHP 8.4 and Laravel 12. If your application is still on an earlier version of either, you will need to upgrade those first. The package now uses PHP 8.4 features directly - array_find() replaces Arr::first() in several places, and strict typing and short nullable notation are used throughout.

New HasActivity trait

One of the quality-of-life improvements in v5 is a new HasActivity trait that combines LogsActivity and CausesActivity into a single include. If your models were already using both traits, this is a straightforward replacement:

Before:

use Spatie\Activitylog\Traits\LogsActivity;
use Spatie\Activitylog\Traits\CausesActivity;

class User extends Model
{
    use LogsActivity, CausesActivity;
}

After:

use Spatie\Activitylog\Traits\HasActivity;

class User extends Model
{
    use HasActivity;
}

The individual traits still exist if you only need one of them.

getActivitylogOptions() is now optional

In v4, any model using LogsActivity had to implement getActivitylogOptions(). In v5 this is optional - if you omit it, the package applies LogOptions::defaults() automatically. For models where you were implementing the method only to call LogOptions::defaults() anyway, you can now remove it entirely.

Method renames

Several methods have been renamed for clarity and consistency. These are direct renames with no change in behaviour:

• activities() on a model is now activitiesAsSubject()
• actions() on a model is now activitiesAsCauser()
• dontSubmitEmptyLogs() is now dontLogEmptyChanges()
• withoutLogs() is now withoutLogging()
• getExtraProperty() on the Activity model is now getProperty()
• ActivityLogStatus class is now ActivitylogStatus (lowercase 'g' for consistent casing)

The batch system has been removed

The most significant removal in v5 is the batch system. LogBatch, the LogBatch facade, Activity::batch(), and the batch-related query scopes (scopeHasBatch(), scopeForBatch()) are all gone. The batch_uuid column has been removed from the database schema.

If your application relies on batch grouping - for instance, correlating multiple activity records that resulted from a single user action - you will need to handle this differently. The most straightforward approach is to add your own column or use the properties column (now clean user-owned space, as discussed below) to store a correlation identifier.

Restructured database schema

The activity_log table schema has changed in two important ways.

First, the batch_uuid column is removed (as mentioned above).

Second, model attribute tracking has been moved out of the properties column into a new dedicated attribute_changes column. In v4, the properties column mixed two concerns: user-supplied custom data, and the package's own record of which model attributes changed (the attributes and old keys). This made it awkward to add custom properties without colliding with the package's own data structure.

In v5, properties is exclusively user-owned. The attributes/old tracking data lives in attribute_changes. Code that accessed change data via $activity->changes() should now access $activity->attribute_changes directly.

v5 ships a new consolidated migration. The three separate migrations from v4 are replaced with a single migration file. When upgrading, you will need to run the new migration to add the attribute_changes column and remove batch_uuid.

New ActivityEvent enum

v5 introduces an ActivityEvent enum with four cases: Created, Updated, Deleted, and Restored. These replace the plain string event names ('created', 'updated', etc.) used in v4. If you are querying activity logs by event type in your application code, you can now use the enum for type safety.

Scoped causer overrides

The CauserResolver facade has been removed. In its place, Activity::defaultCauser() provides a cleaner API for overriding the causer in a scoped context:

// Scoped override - reverts after the callback
Activity::defaultCauser($adminUser, function () {
    // activities logged here will have $adminUser as causer
});

// Global override - applies until changed
Activity::defaultCauser($adminUser);

How to upgrade

The upgrade path requires several steps:

1. Confirm your application meets the PHP 8.4 and Laravel 12 minimum requirements
2. Update the package: composer require spatie/laravel-activitylog:^5.0
3. Run the new migration to update the database schema
4. Replace any use of LogsActivity, CausesActivity with HasActivity (optional but tidier)
5. Update method calls: activities(), actions(), dontSubmitEmptyLogs(), withoutLogs(), getExtraProperty()
6. Update the ActivityLogStatus class name if referenced directly
7. Remove any use of LogBatch or batch-related scopes and replace with your own correlation strategy
8. Update any code accessing $activity->changes() to use $activity->attribute_changes
9. Replace CauserResolver facade usage with Activity::defaultCauser()

Spatie maintains an UPGRADING.md file in the repository with the full v4 to v5 guide - worth reading alongside this post before starting the migration in a production application.

Is it worth upgrading?

If you are starting a new project on PHP 8.4 and Laravel 12, use v5 from the outset. The cleaner schema separation between user data and package data in the properties/attribute_changes split is a genuine improvement, and the HasActivity trait and optional getActivitylogOptions() reduce boilerplate.

For existing applications, the batch system removal is the main consideration. If you are using batches actively, plan that migration before upgrading. If you are not using batches, the rename changes are mechanical, the schema migration is straightforward, and the upgrade is well worth making to stay current with Spatie's support cycle.

Are you running laravel-activitylog in production, and does the batch removal affect you?