Why we built Scotty

Even though services like Laravel Cloud make it possible to never think about servers again, I still prefer deploying to my own servers for some projects. I know my way around them, I can pick whichever server provider I want, and I have full control over the environment.

Tools like Laravel Forge have built-in deploy functionality, and it works well. But I've always preferred running deploy scripts manually from my terminal. I want to see exactly what's happening while it runs, and when something goes wrong, I want to be staring at the output the moment it happens, not clicking through a web UI to find a log.

For years, I used Laravel Envoy for this. It does the job, but I wanted nicer output while tasks are running, and the ability to pause execution mid-deploy. Envoy uses a Blade-based file format, which works fine for us. But not everyone wants to write Blade syntax for their deploy scripts. So Scotty also offers a plain bash format for people who prefer that.

Scotty was built with the help of AI, using the Envoy codebase as a source. Even though Scotty is a rebuild from scratch, in spirit it is a fork of Envoy. Credits to Laravel for providing the foundation. You can read the full acknowledgement in the Scotty repo.

Using Scotty

Defining tasks and deploying

You define your tasks in a Scotty.sh file. It's just plain bash with some annotation comments. Your editor highlights it correctly, you get full shell support out of the box. Here's what that looks like:

#!/usr/bin/env scotty

# @servers remote=deployer@your-server.com

# @task on:remote
deploy() {
    cd /var/www/my-app
    git pull origin main
    php artisan migrate --force
}

Deploy with a single command:

scotty run deploy

Scotty connects to your server, runs each task in order, and shows you what's happening in real time. Each task displays its name, a step counter, elapsed time, and the command currently being executed. When everything finishes, you get a summary table with timing for each step.

These screenshots are from deploying this very blog. You can find the deploy file on GitHub.

If a task fails, its output is shown and execution stops right there so you can investigate.

Writing plain bash instead of Blade

In addition to being able to read Envoy.blade.php files, Scotty introduces a new Scotty.sh format. Every line is real bash. Tasks are just bash functions with a # @task annotation that tells Scotty which server to run them on. Macros group tasks into a sequence. Variables are plain bash variables, available everywhere.

Because it's all valid bash, you can use helper functions, computed values like $(date +%Y%m%d-%H%M%S), and any shell construct you'd normally use. No Blade directives, no PHP @setup blocks, no {{ $variable }} interpolation.

You can also pass variables from the command line. Running scotty run deploy --branch=develop makes $BRANCH available in your tasks. The key is automatically uppercased.

You can list all available tasks and macros with scotty tasks:

Pausing, resuming, and pretending

You can press p at any time during execution to pause after the current task finishes. Press Enter to resume, or Ctrl+C to cancel. This is handy when you want to check something on the server mid-deploy before continuing.

There's also a pretend mode (scotty run deploy --pretend) that shows you exactly which SSH commands would be executed without actually running them. And a summary mode (scotty run deploy --summary) that hides task output and only shows results.

Validating your setup with doctor

Before your first deploy to a new server, you can run scotty doctor to validate your setup. It checks that your file parses correctly, verifies SSH connectivity to each server, and confirms that tools like php, composer, node, and git are available on the remote machine.

Migrating from Envoy

If you're already using Laravel Envoy, Scotty can read your Envoy.blade.php file directly. No changes needed. Just run scotty run deploy and it works. From there, you can gradually migrate to the Scotty.sh format if you want to, or keep using Blade.

If you're new to all of this, the Your first deploy script page in the docs walks you through everything step by step.

In closing

Scotty gives you a clean, modern way to run deploy scripts and other SSH tasks from your terminal. Plain bash, beautiful output, and full control over every step.

You can find the full documentation on our docs site and the source code on GitHub. This is one of the many tools and packages we've created 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.

Our query builder takes care of all of that. It reads query parameters from the URL, translates them into the right Eloquent queries, and makes sure only the things you've explicitly allowed can be queried.

// GET /users?filter[name]=John&include=posts&sort=-created_at

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name')
    ->allowedIncludes('posts')
    ->allowedSorts('created_at')
    ->get();

// select * from users where name = 'John' order by created_at desc

This major version requires PHP 8.3+ and Laravel 12 or higher, and brings a cleaner API along with some features we've been wanting to add for a while.

Let me walk you through how the package works and what's new.

Using the package

The idea is simple: your API consumers pass query parameters in the URL, and the package translates those into the right Eloquent query. You just define what's allowed.

Say you have a User model and you want to let API consumers filter by name. Here's all you need:

use Spatie\QueryBuilder\QueryBuilder;

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name')
    ->get();

Now when someone requests /users?filter[name]=John, the package adds the appropriate WHERE clause to the query:

select * from users where name = 'John'

Only the filters you've explicitly allowed will work. If someone tries /users?filter[secret_column]=something, the package throws an InvalidFilterQuery exception. Your database schema stays hidden from API consumers.

You can allow multiple filters at once and combine them with sorting:

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email')
    ->allowedSorts('name', 'created_at')
    ->get();

A request to /users?filter[name]=John&sort=-created_at now filters by name and sorts by created_at descending (the - prefix means descending).

Including relationships works the same way. If you want consumers to be able to eager-load a user's posts:

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email')
    ->allowedIncludes('posts', 'permissions')
    ->allowedSorts('name', 'created_at')
    ->get();

A request to /users?include=posts&filter[name]=John&sort=-created_at now returns users named John, sorted by creation date, with their posts eager-loaded.

You can also select specific fields to keep your responses lean:

$users = QueryBuilder::for(User::class)
    ->allowedFields('id', 'name', 'email')
    ->allowedIncludes('posts')
    ->get();

With /users?fields=id,email&include=posts, only the id and email columns are selected.

The QueryBuilder extends Laravel's default Eloquent builder, so all your favorite methods still work. You can combine it with existing queries:

$query = User::where('active', true);

$users = QueryBuilder::for($query)
    ->withTrashed()
    ->allowedFilters('name')
    ->allowedIncludes('posts', 'permissions')
    ->where('score', '>', 42)
    ->get();

The query parameter names follow the JSON API specification as closely as possible. This means you get a consistent, well-documented API surface without having to think about naming conventions.

What's new in v7

Variadic parameters

All the allowed* methods now accept variadic arguments instead of arrays.

// Before (v6)
QueryBuilder::for(User::class)
    ->allowedFilters(['name', 'email'])
    ->allowedSorts(['name'])
    ->allowedIncludes(['posts']);

// After (v7)
QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email')
    ->allowedSorts('name')
    ->allowedIncludes('posts');

If you have a dynamic list, use the spread operator:

$filters = ['name', 'email'];
QueryBuilder::for(User::class)->allowedFilters(...$filters);

Aggregate includes

This is the biggest new feature. You can now include aggregate values for related models using AllowedInclude::min(), AllowedInclude::max(), AllowedInclude::sum(), and AllowedInclude::avg(). Under the hood, these map to Laravel's withMin(), withMax(), withSum() and withAvg() methods.

use Spatie\QueryBuilder\AllowedInclude;

$users = QueryBuilder::for(User::class)
    ->allowedIncludes(
        'posts',
        AllowedInclude::count('postsCount'),
        AllowedInclude::sum('postsViewsSum', 'posts', 'views'),
        AllowedInclude::avg('postsViewsAvg', 'posts', 'views'),
    )
    ->get();

A request to /users?include=posts,postsCount,postsViewsSum now returns users with their posts, the post count, and the total views across all posts.

You can constrain these aggregates too. For example, to only count published posts:

use Spatie\QueryBuilder\AllowedInclude;
use Illuminate\Database\Eloquent\Builder;

$users = QueryBuilder::for(User::class)
    ->allowedIncludes(
        AllowedInclude::count(
            'publishedPostsCount',
            'posts',
            fn (Builder $query) => $query->where('published', true)
        ),
        AllowedInclude::sum(
            'publishedPostsViewsSum',
            'posts',
            'views',
            constraint: fn (Builder $query) => $query->where('published', true)
        ),
    )
    ->get();

All four aggregate types support these constraint closures, making it possible to build endpoints that return computed data alongside your models without writing custom query logic.

A perfect match for Laravel's JSON:API resources

Laravel 13 is adding built-in support for JSON:API resources. These new JsonApiResource classes handle the serialization side: they produce responses compliant with the JSON:API specification.

You create one by adding the --json-api flag:

php artisan make:resource PostResource --json-api

This generates a resource class where you define attributes and relationships:

use Illuminate\Http\Resources\JsonApi\JsonApiResource;

class PostResource extends JsonApiResource
{
    public $attributes = [
        'title',
        'body',
        'created_at',
    ];

    public $relationships = [
        'author',
        'comments',
    ];
}

Return it from your controller, and Laravel produces a fully compliant JSON:API response:

{
    "data": {
        "id": "1",
        "type": "posts",
        "attributes": {
            "title": "Hello World",
            "body": "This is my first post."
        },
        "relationships": {
            "author": {
                "data": { "id": "1", "type": "users" }
            }
        }
    },
    "included": [
        {
            "id": "1",
            "type": "users",
            "attributes": { "name": "Taylor Otwell" }
        }
    ]
}

Clients can request specific fields and includes via query parameters like /api/posts?fields[posts]=title&include=author. Laravel's JSON:API resources handle all of that on the response side.

The Laravel docs explicitly mention our package as a companion:

Laravel's JSON:API resources handle the serialization of your responses. If you also need to parse incoming JSON:API query parameters such as filters and sorts, Spatie's Laravel Query Builder is a great companion package.

So while Laravel's new JSON:API resources take care of the output format, our query builder handles the input side: parsing filter, sort, include and fields parameters from the request and translating them into the right Eloquent queries. Together they give you a full JSON:API implementation with very little boilerplate.

In closing

To upgrade from v6, check the upgrade guide. The changes are mostly mechanical. Check the guide for the full list.

You can find the full source code and documentation on GitHub. We also have extensive documentation on the Spatie website.

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.