The basics

Here's a typical setup in a controller:

use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::partial('name'),
        AllowedFilter::exact('status'),
    )
    ->get();

With that in place, the package wires up two filters that clients can use through the query string.

A request to /users?filter[name]=john runs:

SELECT * FROM users WHERE LOWER(name) LIKE '%john%'

A request to /users?filter[status]=active runs:

SELECT * FROM users WHERE status = 'active'

And a request to /users?filter[name]=john&filter[status]=active runs:

SELECT * FROM users
WHERE LOWER(name) LIKE '%john%'
  AND status = 'active'

Multiple filters in the URL are joined with AND. That's the default and it's what you want most of the time.

The word "allowed" in allowedFilters is doing real work. If a client tries to filter by something you haven't whitelisted, the package throws an InvalidFilterQuery exception instead of silently ignoring it or, worse, letting it through. So a request to /users?filter[email]=acme.com against the controller above results in:

Spatie\QueryBuilder\Exceptions\InvalidFilterQuery
Requested filter(s) `email` are not allowed.
Allowed filter(s) are `name, status`.

The exception has a 400 Bad Request status code, so by default Laravel renders it as a clean error response to the client. You don't have to do anything special to get this behavior.

The new bit: grouping filters

Now imagine you want a single search box that matches across multiple columns. The user types "john" and you want to find rows where either the name or the email contains that value.

Before v7.3.0, you'd reach for a custom callback filter:

$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::exact('status'),
        AllowedFilter::callback('q', function ($query, $value) {
            $query->where('name', 'LIKE', "%{$value}%")
                ->orWhere('email', 'LIKE', "%{$value}%");
        }),
    )
    ->get();

Looks fine at a glance. But a request to /users?filter[status]=active&filter[q]=john runs:

SELECT * FROM users
WHERE status = 'active'
  AND name LIKE '%john%'
   OR email LIKE '%john%'

Spot the bug. The OR binds looser than the AND, so this matches every row whose email contains "john", including inactive users. To fix it, you have to wrap the callback's wheres in their own nested closure. It's an easy thing to forget, and it silently returns wrong data when you do.

In v7.3.0, this becomes a one-liner. Here's how you register a group filter:

$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::groupOr('q', [
            AllowedFilter::partial('name'),
            AllowedFilter::partial('email'),
        ]),
    )
    ->get();

A request to /users?filter[q]=john now runs:

SELECT * FROM users
WHERE (LOWER(name) LIKE '%john%' OR LOWER(email) LIKE '%john%')

The value john is passed to every member of the group, and the conjunction joins them. There's also AllowedFilter::groupAnd() if you want all members to match instead.

Combining group filters with regular filters

Groups compose cleanly with the rest of your filters. Here's a setup that has both a top-level status filter and a group:

$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::exact('status'),
        AllowedFilter::groupOr('q', [
            AllowedFilter::partial('name'),
            AllowedFilter::partial('email'),
        ]),
    )
    ->get();

A request to /users?filter[status]=active&filter[q]=john runs:

SELECT * FROM users
WHERE status = 'active'
  AND (LOWER(name) LIKE '%john%' OR LOWER(email) LIKE '%john%')

The whole group is wrapped in its own parentheses, so the OR can never leak into the status clause. That's the bug pattern that used to bite people who rolled their own callback filter for cross-column search.

You can also register multiple independent groups. Each one becomes its own wrapped scope, and they're joined with AND between them. The members can be any AllowedFilter type, so you can mix partial, exact, scope, and other filters in the same group.

In closing

The upgrade is fully non-breaking. All existing filter behavior is unchanged. The new feature is documented in the filtering docs, and the pull request by Birtan Taşkın has the full reasoning behind the design.

This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.

We just released v4, which adds a few things worth talking about. Let me walk you through them.

Generating slugs with an attribute

For most models, slug generation is mechanical. Pick a source field, pick a destination field, done. In v4, you can express that with an attribute on the model.

use Spatie\Sluggable\Attributes\Sluggable;
use Illuminate\Database\Eloquent\Model;

#[Sluggable(from: 'title', to: 'slug')]
class Post extends Model
{
}

That's it. No trait, no getSlugOptions() method. Save a Post and the package fills in the slug:

$post = Post::create(['title' => 'ActiveRecord is awesome']);

$post->slug; // "activerecord-is-awesome"

Self-healing URLs

Picture this. You publish a new post titled "Anouncing v4 of laravel-sluggable". The slug becomes anouncing-v4-of-laravel-sluggable, you share the link, a few people bookmark it. Five minutes later you notice the missing n and fix the title. The slug regenerates to announcing-v4-of-laravel-sluggable, and now everyone who clicked the first version hits a 404.

The usual answer is a redirects table: store the old slug, forward it to the new one. It works, but every rename adds a row, and after a while it's another moving piece to maintain.

Self-healing URLs solve this differently. The route key combines the slug with the primary key, so the slug is decorative and the id is what actually identifies the record.

use Spatie\Sluggable\Attributes\Sluggable;
use Spatie\Sluggable\HasSlug;
use Illuminate\Database\Eloquent\Model;

#[Sluggable(from: 'title', to: 'slug', selfHealing: true)]
class Post extends Model
{
    use HasSlug;
}

If your post has slug hello-world and id 5, the URL becomes /posts/hello-world-5. Rename the post to Greetings, World and the canonical URL becomes /posts/greetings-world-5. Old links keep working because the package can still find the record by id, and it sends a permanent redirect to the new canonical URL.

The redirect status code is 308 Permanent Redirect. In v3 it was 301. The reason for the change is that 301 is allowed to silently downgrade PUT, PATCH, and DELETE to GET when followed, which gets you a 405 Method Not Allowed if the new URL doesn't accept GET. 308 keeps the method intact.

Overridable actions

Slug generation and the self-healing URL format are now expressed as three actions: one for generating the slug, one for building the self-healing route key, and one for parsing it back out. All three can be swapped through config/sluggable.php. The example below customizes the two self-healing actions; the slug generator stays on its default behavior.

The use case I had in mind was self-healing URLs that put the id first. Say you want /posts/5-hello-world instead of /posts/hello-world-5. Extend the default builder action and put the identifier in front:

namespace App\Sluggable;

use Spatie\Sluggable\Actions\BuildSelfHealingRouteKeyAction;

class IdFirstBuildAction extends BuildSelfHealingRouteKeyAction
{
    public function execute(string $slug, int|string $identifier, string $separator): string
    {
        if ($slug === '') {
            return (string) $identifier;
        }

        return "{$identifier}{$separator}{$slug}";
    }
}

The extractor needs the inverse logic. The default action looks for the last separator, because slugs can contain the separator themselves, so swap it for one that reads the identifier from the front:

namespace App\Sluggable;

use Illuminate\Support\Str;
use Spatie\Sluggable\Actions\ExtractIdentifierFromSelfHealingRouteKeyAction;

class IdFirstExtractAction extends ExtractIdentifierFromSelfHealingRouteKeyAction
{
    public function execute(string $value, string $separator): array
    {
        $identifier = Str::before($value, $separator);

        if ($identifier === $value || ! ctype_digit($identifier)) {
            return ['slug' => $value, 'identifier' => null];
        }

        return [
            'slug' => Str::after($value, $separator),
            'identifier' => $identifier,
        ];
    }
}

Str::before returns the original string when the separator isn't present, which is how the no-separator case is detected. The ctype_digit check rejects values where the prefix isn't numeric, so models with non-numeric primary keys like ULIDs need to swap that for a regex.

Wire both into the config and you're done:

// config/sluggable.php
'build_self_healing_route_key' => App\Sluggable\IdFirstBuildAction::class,
'extract_identifier_from_self_healing_route_key' => App\Sluggable\IdFirstExtractAction::class,

The full reference, including a simpler uppercase variant and a custom slug generator, lives in the overriding actions docs.

A bundled Boost skill

Laravel Boost is an MCP server from the Laravel team that exposes your application's installed packages and versions to your AI assistant, so prompts produce code that fits your stack instead of generic Laravel snippets. Packages can bundle their own Boost skills, and Boost discovers them automatically.

This package ships with a sluggable-development skill that walks your assistant through adding a sluggable model: picking the source field, deciding whether you need self-healing URLs, generating the migration, and dropping the attribute or trait on the model. If you have Boost installed, this is the easiest way to add a new sluggable model to your project.

In closing

You can find the package on GitHub and the full documentation on our docs site. Coming from v3? The upgrade guide covers the breaking changes (mostly minimum versions and a callable to Closure migration).

This is one of many packages we've built at Spatie. If you want to support our open source work, consider picking up one of our paid products.

In Flare, Mailcoach, and Oh Dear we use it to build audit logs, so we can track what users are doing: who changed a setting, who deleted a project, who invited a team member. If you need something similar in your app, this package makes it easy.

This major release requires PHP 8.4+ and Laravel 12+, and brings a cleaner API, a better database schema, and customizable internals. Let me walk you through what the package can do and what's new in v5.

Using the package

At its core, the package lets you log what happens in your application. The simplest usage looks like this:

activity()->log('Look mum, I logged something');

You can retrieve all logged activities using the Activity model:

use Spatie\Activitylog\Models\Activity;

$lastActivity = Activity::all()->last();

// returns 'Look mum, I logged something'
$lastActivity->description;

Most of the time you want to know two things: what was affected, and who did it. The package calls these the subject and the causer. You can also attach custom properties for any extra context you need:

activity()
   ->performedOn($article)
   ->causedBy($user)
   ->withProperties(['via' => 'admin-panel'])
   ->log('edited');

$lastActivity = Activity::all()->last();

// the article that was edited
$lastActivity->subject;

// the user who edited it
$lastActivity->causer;

// 'admin-panel'
$lastActivity->getProperty('via');

The Activity model provides query scopes to filter your activity log:

Activity::forSubject($newsItem)->get();
Activity::causedBy($user)->get();
Activity::forEvent('updated')->get();
Activity::inLog('payment')->get();

// or combine them
Activity::forSubject($newsItem)
    ->causedBy($user)
    ->forEvent('updated')
    ->get();

Automatic model event logging

Imagine you want to track whenever a model is created, updated, or deleted. Just add the LogsActivity trait to your model. In v5, that's all you need for basic logging:

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

class NewsItem extends Model
{
    use LogsActivity;
}

That's it. No getActivitylogOptions() method needed. Now imagine you also want to track which attributes changed. Override the method and tell it what to watch:

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']);
    }
}

Now when you update a news item, the package tracks exactly what changed:

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

$activity = Activity::all()->last();
$activity->attribute_changes;
// [
//     'attributes' => [
//         'name' => 'updated name',
//         'text' => 'Lorem',
//     ],
//     'old' => [
//         'name' => 'original name',
//         'text' => 'Lorem',
//     ],
// ]

You can log all fillable attributes with logFillable(), all unguarded attributes with logUnguarded(), or use logAll() combined with logExcept() to log everything except sensitive fields like passwords.

If you only want to see what actually changed rather than all tracked attributes, chain logOnlyDirty().

Running code before an activity is saved

When a model event is logged, you can hook into the process by defining a beforeActivityLogged() method on your model:

class NewsItem extends Model
{
    use LogsActivity;

    public function beforeActivityLogged(Activity $activity, string $eventName): void
    {
        $activity->properties = $activity->properties->merge([
            'ip_address' => request()->ip(),
        ]);
    }
}

This runs right before the activity is persisted, giving you a chance to enrich it with extra data.

Customizable action classes

The core operations of the package (logging activities and cleaning old records) are now handled by action classes. You can extend these and swap them in via config.

For example, say you want to save activities to the queue instead of writing them to the database during the request. Extend the action and override the save() method:

use Spatie\Activitylog\Actions\LogActivityAction;

class QueuedLogAction extends LogActivityAction
{
    protected function save(Model $activity): void
    {
        dispatch(new SaveActivityJob($activity->toArray()));
    }
}

Then tell the package to use your custom action in config/activitylog.php:

'actions' => [
    'log_activity' => QueuedLogAction::class,
],

You can also override transformChanges() to manipulate the changes array before saving. Here's an example that redacts password changes so they never end up in your activity log:

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Arr;
use Spatie\Activitylog\Actions\LogActivityAction;

class RedactSensitiveFieldsAction extends LogActivityAction
{
    protected function transformChanges(Model $activity): void
    {
        $changes = $activity->attribute_changes?->toArray() ?? [];

        Arr::forget($changes, ['attributes.password', 'old.password']);

        $activity->attribute_changes = collect($changes);
    }
}

Buffering activities

Say you have an endpoint that updates product prices in bulk. Each product update triggers a model event, and each model event logs an activity. With 200 products, that's 200 INSERT queries just for activity logging.

foreach ($products as $product) {
    // each update triggers an activity INSERT query
    $product->update(['price' => $newPrices[$product->id]]);
}

With buffering enabled, the package collects all those activities in memory during the request and inserts them in a single bulk query after the response has been sent to the client. Your user gets a fast response, and the database does one insert instead of 200.

Buffering is off by default. You can enable it in the config/activitylog.php config file. No other code changes needed. All existing logging code (both automatic model event logging and manual activity()->log() calls) will be buffered automatically.

Under the hood, the ActivityBuffer class collects activities in an array and inserts them all at once when flushed:

class ActivityBuffer
{
    protected array $pending = [];

    public function add(Model $activity): void
    {
        $this->pending[] = $this->prepareForInsert($activity);
    }

    public function flush(): void
    {
        if (empty($this->pending)) {
            return;
        }

        $modelClass = Config::activityModel();
        $modelClass::query()->insert($this->pending);

        $this->pending = [];
    }
}

The service provider takes care of flushing the buffer at the right time:

protected function registerActivityBufferFlushing(): void
{
    // flush after the response has been sent
    $this->app->terminating(fn () => app(ActivityBuffer::class)->flush());

    // flush after each queued job
    $this->app['events']->listen(
        [JobProcessed::class, JobFailed::class],
        fn () => app(ActivityBuffer::class)->flush(),
    );

    // safety net if the application terminates unexpectedly
    register_shutdown_function(function () {
        try {
            app(ActivityBuffer::class)->flush();
        } catch (\Throwable) {
        }
    });
}

One thing to be aware of: buffered activities won't have a database ID until the buffer is flushed. If you need to read back the activity ID immediately after logging, don't enable buffering.

This works with Octane (the buffer is a scoped binding, so it resets between requests) and queues out of the box.

In closing

v5 doesn't bring a lot of new features, but it modernizes the package, cleans up the internals, and makes the things that were hard to customize in v4 easy to swap out. If you're upgrading from v4, be aware that there are quite a few breaking changes. Check the upgrade guide for the full list.

You can find the complete documentation at spatie.be/docs/laravel-activitylog and the source code on GitHub.

This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.