DEV Community: Hafiz

Slow Job Alerts in Laravel 13.40: What whenJobRunsLongerThan Catches and What It Misses

Hafiz — Thu, 12 Nov 2026 05:15:13 +0000

Laravel 13.40 shipped on 3 November with Queue::whenJobRunsLongerThan(), a one-liner that tells you when a queued job runs slower than it should. The scheduler got a twin, Schedule::whenTaskRunsLongerThan(), in the same release. The queue docs don't cover either one yet, so I tested them.

On a fresh Laravel 13.40.0 install with the database queue driver and PHP 8.3, I pushed five jobs through one worker: a fast one, a slow one, one that fails, one that releases itself, and one that runs past the worker's --timeout. Four did what you'd expect. The fifth is the one to know about before you build alerting on this. All output below is real.

What 13.40 added

PR #62141 adds the queue version. You register it once, in a service provider:

use Carbon\CarbonInterval;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Queue;

public function boot(): void
{
    Queue::whenJobRunsLongerThan(CarbonInterval::seconds(2), function ($job, $duration) {
        Log::warning("{$job->resolveName()} took {$duration}ms");
    });
}

$duration is in milliseconds. It comes from the JobAttempted event, which gained a duration property in 13.39. And that event is the whole mechanism. This is the core of the method in QueueManager:

$this->app['events']->listen(Events\JobAttempted::class, function ($event) use ($threshold, $handler) {
    if (! is_null($event->duration) && $event->duration > $threshold) {
        $handler($event->job, $event->duration);
    }
});

So it isn't a timer. Nothing happens when a running job crosses the threshold. The check runs once, after the attempt is over, and only if a duration was recorded.

Five jobs through one worker

The test app registers two thresholds side by side. One uses CarbonInterval::seconds(2). The other passes a plain 5, which is easy to type when you mean five seconds:

Queue::whenJobRunsLongerThan(CarbonInterval::seconds(2), function ($job, $duration) {
    Log::warning("[2s threshold] {$job->resolveName()} took {$duration}ms");
});

Queue::whenJobRunsLongerThan(5, function ($job, $duration) {
    Log::warning("[plain 5] {$job->resolveName()} took {$duration}ms");
});

The job sleeps, then optionally throws or releases itself:

public function handle(): void
{
    usleep((int) ($this->seconds * 1_000_000));

    match ($this->mode) {
        'fail' => throw new RuntimeException('Failed after sleeping'),
        'release' => $this->release(60),
        default => null,
    };
}

The first run is a 0.5 second job, then three 3 second jobs. One finishes, one throws, one releases itself.

$ php artisan queue:work --tries=1 --stop-when-empty
 2026-11-06 11:20:35 App\Jobs\SleepJob .. RUNNING
 2026-11-06 11:20:36 App\Jobs\SleepJob .. 514.71ms DONE
 2026-11-06 11:20:36 App\Jobs\SleepJob .. RUNNING
 2026-11-06 11:20:39 App\Jobs\SleepJob .. 3s DONE
 2026-11-06 11:20:39 App\Jobs\SleepJob .. RUNNING
 2026-11-06 11:20:42 App\Jobs\SleepJob .. 3s FAIL
 2026-11-06 11:20:42 App\Jobs\SleepJob .. RUNNING
 2026-11-06 11:20:45 App\Jobs\SleepJob .. 3s RELEASED
 2026-11-06 11:20:48 Worker STOPPED Queue empty
$ grep WARNING storage/logs/laravel.log
[2026-11-06 11:20:36] local.WARNING: [plain 5] App\Jobs\SleepJob took 513.2ms
[2026-11-06 11:20:39] local.WARNING: [2s threshold] App\Jobs\SleepJob took 3009.45ms
[2026-11-06 11:20:39] local.WARNING: [plain 5] App\Jobs\SleepJob took 3009.45ms
[2026-11-06 11:20:42] local.WARNING: [2s threshold] App\Jobs\SleepJob took 3003.32ms
[2026-11-06 11:20:42] local.WARNING: [plain 5] App\Jobs\SleepJob took 3003.32ms
[2026-11-06 11:20:45] local.WARNING: [2s threshold] App\Jobs\SleepJob took 3005.84ms
[2026-11-06 11:20:45] local.WARNING: [plain 5] App\Jobs\SleepJob took 3005.84ms

The 2 second threshold fired for all three slow jobs, including the one that failed and the one that was released. A job that keeps failing slowly and retrying is exactly what you'd want flagged. (13.40 also changed the worker output to say RELEASED instead of DONE, which you can see on the last job.)

The plain 5 fired for the 514ms job. That's the unit trap. A plain number is milliseconds here, so whenJobRunsLongerThan(5, ...) means five milliseconds, and it will fire for almost every job you run.

And the sync driver behaves the same way. SleepJob::dispatchSync(3) logged took 3006.12ms on both thresholds, because the sync queue dispatches JobAttempted with a duration too.

The scheduler version counts in seconds

PR #62233 adds Schedule::whenTaskRunsLongerThan(). Same shape, different unit:

use Illuminate\Console\Scheduling\Event;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Schedule;

Schedule::whenTaskRunsLongerThan(2, function (Event $task, float $runtime) {
    Log::warning("{$task->getSummaryForDisplay()} took {$runtime}s");
});

Here a plain 2 means two seconds. So the same number in your queue setup and your scheduler setup means two different things, a thousand times apart. Pass a CarbonInterval to both and the problem goes away. The queue version converts it with totalMilliseconds and the scheduler version with totalSeconds, so CarbonInterval::seconds(30) means 30 seconds in both places.

The job that hits the timeout

The fifth job sleeps for 10 seconds on a worker started with --timeout=5. It's the slowest job in the whole test, by a distance.

$ php artisan queue:work --tries=1 --timeout=5
 2026-11-06 11:20:18 App\Jobs\SleepJob .. RUNNING
 2026-11-06 11:20:23 App\Jobs\SleepJob .. 5s FAIL
 2026-11-06 11:20:23 Worker STOPPED Job timed out
$ echo $?
137
$ grep WARNING storage/logs/laravel.log
[2026-11-06 11:20:23] local.WARNING: [timed out] App\Jobs\SleepJob after 5s

Only the JobTimedOut listener wrote anything. The worker exited with code 137, which is 128 plus signal 9, SIGKILL. The order inside Worker::registerTimeoutHandler() explains it. The SIGALRM handler marks the job as failed (it's in failed_jobs as a TimeoutExceededException), dispatches JobTimedOut, then calls kill(), which sends SIGKILL to its own process. JobAttempted is dispatched from the finally block in Worker::process(), and a process killed with SIGKILL never reaches a finally block. No JobAttempted means no duration, and no duration means no alert.

What I'd register instead

Keep the slow job alert, but don't make it your only timeout signal. This is the setup I'd put in AppServiceProvider:

use Carbon\CarbonInterval;
use Illuminate\Queue\Events\JobTimedOut;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Queue;

public function boot(): void
{
    // Jobs that finish, but slower than they should
    Queue::whenJobRunsLongerThan(CarbonInterval::seconds(30), function ($job, $duration) {
        Log::warning("Slow job: {$job->resolveName()} took {$duration}ms");
    });

    // Jobs the worker had to kill
    Event::listen(JobTimedOut::class, function (JobTimedOut $event) {
        Log::error("Job timed out: {$event->job->resolveName()} after {$event->timeout}s");
    });
}

Pass a CarbonInterval, never a plain number. It means the same thing in both APIs.
Set the threshold well under your timeout. The alert only sees jobs that finish, so it's an early warning. With the default --timeout=60, a 30 second threshold tells you a job is drifting toward the limit while it still completes. The timeout itself has to stay below retry_after, which the 10,000 tasks post explains.
Listen for JobTimedOut for the jobs that don't finish. The worker dispatches it on every timeout, before the kill, whether or not the job has retries left. Keep the listener quick, though. It runs inside a process that's about to kill itself.

A timeout isn't the only way a worker dies before it can tidy up. A deploy sends SIGTERM and then SIGKILL after the grace period, which I walked through in the queue worker SIGTERM post.

Background scheduled tasks are never measured

The scheduler version listens for ScheduledTaskFinished and ScheduledTaskFailed. schedule:run times each task by wrapping the call that starts it, and for a task with runInBackground() that call returns as soon as the process is spawned. Two tasks, a 3 second one in the foreground and a 4 second one in the background:

$ php artisan schedule:run
 2026-11-06 11:20:51 Running ['artisan' app:slow-task 3] .. 3s DONE
 2026-11-06 11:20:55 Running ['artisan' app:slow-task 4] in background  5.56ms DONE
$ grep WARNING storage/logs/laravel.log
[2026-11-06 11:20:55] local.WARNING: [schedule 2] '/opt/homebrew/Cellar/php@8.3/8.3.22/bin/php' 'artisan' app:slow-task 3 > '/dev/null' 2>&1 took 3.23s

The foreground task fired at 3.23s. The background one never did. The scheduler recorded the 5.56ms it took to start the process, not the four seconds the command ran, and nothing compares the real runtime later. If a long task has to run in the background, time it inside the command itself. (Background tasks in the docs covers how they run.)

FAQ

Does whenJobRunsLongerThan fire while the job is still running?

No. It listens for JobAttempted, which the worker dispatches after an attempt ends. A job stuck at minute 20 of a 30 minute timeout produces nothing until it finishes.

What unit does the threshold use?

Milliseconds for Queue::whenJobRunsLongerThan() and seconds for Schedule::whenTaskRunsLongerThan(). Both convert a CarbonInterval correctly, so use one.

Does it alert on a job that hits the worker timeout?

No. The worker kills its own process with SIGKILL before JobAttempted is dispatched. Listen for JobTimedOut instead, which fires just before the kill. The queue timeout docs cover how the timeout itself works.

Does it work with Horizon?

I didn't run Horizon for this test. Horizon's horizon:work command extends Laravel's own queue:work command (I checked in Horizon 5.50.1), so jobs go through the same Worker class and the same timeout path. I'd expect the same results, but confirm on your setup. If you're still choosing between the two, Horizon vs Cloud's managed queues covers the trade-offs.

Does it work with the sync driver?

Yes. The sync queue dispatches JobAttempted with a duration too, so a slow dispatchSync() call triggers it.

A slow alert needs a timeout listener next to it

whenJobRunsLongerThan is a good alert for jobs that finish slowly, and it costs one line. But it can't see the job that never finishes, and that's the one that hurts. And if you use the scheduler version, a task with runInBackground() is invisible to it.

Herd 2 Workspaces for Parallel Coding Agents: What Is Isolated and What Is Not

Hafiz — Mon, 09 Nov 2026 05:15:08 +0000

Herd 2 came out on 5 November, and its headline feature is workspaces: "isolated copies of a site that live on their own git branch and are served on their own domain." The pitch is parallel coding agents. Give each agent its own copy of the app and let them work without stepping on each other.

I ran parallel Claude Code sessions on git worktrees back in March, and the files were never the hard part. The hard part was everything the files point at. So I installed Herd 2.1.0 (Homebrew already ships 2.1), created a fresh Laravel 13.40 app, made five workspaces from it and tried to break them. Herd prints a database warning every time you create one, so I tested whether it holds. And the database wasn't the only thing two copies of the app ended up sharing. All output below is real.

What a workspace actually is

The app lives in ~/Herd/orders, so Herd serves it at orders.test. One command creates a workspace:

$ herd workspace feature-a
✓ Creating Workspace
✓ Cloning Directory (this can take a moment)
✓ Linking Site
✓ Updating .env
✓ Finishing Up
Workspace [feature-a] is ready at [http://feature-a.orders.test].
 WARNING  The workspace shares the database of [orders] — migrations and destructive operations affect the parent site.
  Pass `--database=clone` for a copy of the parent database or `--database=empty` for a fresh one.
  cd "/Users/hafizzeeshanriaz/Library/Application Support/Herd/devtools/clones/8543c00e/feature-a-aa198b31"

It isn't a git worktree. Herd makes a copy-on-write clone of the whole folder (APFS clones files without duplicating the bytes until one side changes them), puts it in Herd's own application support folder, and gives it a full .git directory on a new branch named after the workspace. The new site answers at feature-a.orders.test straight away.

The clone takes everything, untracked files included. So the workspace has its own .env and its own vendor/. Herd then rewrites the .env, but only the keys that already exist. Here's the whole difference between the two files:

$ diff .env <workspace>/.env
5c5
< APP_URL=http://localhost:8000
---
> APP_URL=http://feature-a.orders.test

One line. Herd's workspace docs say it also touches SESSION_DOMAIN, SANCTUM_STATEFUL_DOMAINS and DB_DATABASE when those are set, and only DB_DATABASE when the workspace gets its own database. A fresh Laravel app sets none of them.

The database warning, tested

Every herd workspace run ends with the same warning: the workspace shares the parent's database, so migrations and destructive operations affect the parent site. herd workspaces agrees and lists feature-a with a database of shared. So I put one user in the parent and ran the most destructive command an agent is likely to run.

$ php artisan tinker --execute="echo App\\Models\\User::count();"   # parent
1
$ cd <workspace> && php artisan migrate:fresh --force
 Dropping all tables .. 4.81ms DONE
 INFO Preparing database.
 Creating migration table .. 2.00ms DONE
 INFO Running migrations.
 0001_01_01_000000_create_users_table .. 3.35ms DONE
 0001_01_01_000001_create_cache_table .. 1.65ms DONE
$ php artisan tinker --execute="echo App\\Models\\User::count();"   # parent again
1

The parent still has its user. Laravel's default SQLite connection doesn't set DB_DATABASE, so each app reads database/database.sqlite relative to its own folder, and the clone took its own copy of that file (different inode, same 98,304 bytes). Herd's warning describes the database Herd thinks it's sharing. The app was never sharing it.

With an absolute database path

That changes the moment DB_DATABASE holds a value that means the same thing in both folders. An absolute SQLite path does. So does the database name of every MySQL or PostgreSQL app, and Herd copies the .env as-is in shared mode. I added an absolute path to the parent's .env and created a second workspace:

DB_CONNECTION=sqlite
DB_DATABASE=/Users/hafizzeeshanriaz/Herd/orders/database/database.sqlite

$ php artisan tinker --execute="echo App\\Models\\User::count();"   # parent
1
$ cd <workspace feature-b> && php artisan migrate:fresh --force
 Dropping all tables .. 3.29ms DONE
 INFO Preparing database.
 Creating migration table .. 2.10ms DONE
$ php artisan tinker --execute="echo App\\Models\\User::count();"   # parent again
0

Gone. The workspace dropped every table in the parent's database. I only tested SQLite, because Herd's MySQL and PostgreSQL services need Herd Pro, but the mechanism is the same .env line. A DB_DATABASE=orders on MySQL points both sites at the same orders database.

--database=clone fixes it. Herd copies the database and points the workspace at the copy:

$ herd workspace feature-c --database=clone
✓ Creating Workspace
✓ Cloning Directory (this can take a moment)
✓ Linking Site
✓ Preparing Database
✓ Updating .env
✓ Finishing Up
Workspace [feature-c] is ready at [http://feature-c.orders.test].
The workspace uses its own SQLite database — a copy of the parent site's.
  cd "/Users/hafizzeeshanriaz/Library/Application Support/Herd/devtools/clones/8543c00e/feature-c-fe2986fe"
$ cd <workspace feature-c> && php artisan migrate:fresh --force
 Dropping all tables .. 3.26ms DONE
$ php artisan tinker --execute="echo App\\Models\\User::count();"   # parent
1

The workspace's .env now has DB_DATABASE set to the copy inside the workspace folder, so migrate:fresh wiped the copy and left the parent alone. There's also --database=empty, which creates a fresh database and runs your migrations unless you pass --no-migrate.

Herd Studio, the browser panel Herd 2 adds for running agents next to a site, shows the same list. The cloned workspace gets a DB copy badge. The others get nothing, feature-a included, even though it was the one with its own database all along.

The queue goes wherever the database goes

This is the one I didn't expect. A fresh Laravel app uses QUEUE_CONNECTION=database, so a shared database also means a shared jobs table. In a shared workspace, I did what an agent building a feature would do. I created a job class that only exists in the workspace and dispatched it. Then I ran the parent site's worker:

$ cd <workspace feature-b> && php artisan tinker --execute="App\\Jobs\\SendWeeklyReport::dispatch();"
$ cd ~/Herd/orders && php artisan queue:work --once   # the parent site's worker
 2026-11-06 12:17:24 App\Jobs\SendWeeklyReport .. RUNNING
 2026-11-06 12:17:24 App\Jobs\SendWeeklyReport .. 2.44ms FAIL
$ php artisan queue:failed   # parent
 2026-11-06 12:17:24 01e3dde9-e667-4bd1-8971-f810f14bc45d database@default App\Jobs\SendWeeklyReport

The parent's worker picked up the workspace's job and failed on it, because the class only exists in the workspace. The exception in the parent's failed_jobs reads:

ErrorException: Illuminate\Queue\CallQueuedHandler::commandShouldBeDebounced(): The script tried to access a property on an incomplete object. Please ensure tha

It's the same class of bug as a tenant's job running in the wrong tenant. The job is fine. It just ran in the wrong app. With two agents changing job payloads in parallel, the failures land in the parent's failed_jobs, and the parent never dispatched any of them.

Unpushed commits are left out

The last surprise isn't about the database. Herd's settings have workspaceBaseFromOrigin turned on (Settings → Advanced in the app), so a workspace starts from the last pushed state of your branch. I pushed main, committed an Invoice model without pushing, then created two workspaces:

$ git log --oneline -2
97a52bc Add Invoice model (not pushed)
c8084d6 Fresh Laravel app
$ git status -sb | head -1
## main...origin/main [ahead 1]
$ herd workspace feature-d
Workspace [feature-d] is ready at [http://feature-d.orders.test].
 WARNING  The workspace shares the database of [orders] — migrations and destructive operations affect the parent site.
 WARNING  The workspace starts from the last pushed state of [main] — your 1 unpushed commit(s) are not included. Push first or re-create it with `herd workspace --local` if you need them.
$ cd <workspace feature-d> && git log --oneline -2 && ls app/Models
c8084d6 Fresh Laravel app
User.php
$ herd workspace feature-e --local
Workspace [feature-e] is ready at [http://feature-e.orders.test].
$ cd <workspace feature-e> && ls app/Models
Invoice.php
User.php

Herd does warn about it, and --local includes the unpushed commit. But an agent handed a workspace without that flag starts from code that's missing your latest commit, and nothing in the workspace itself tells it so.

How I'd set it up for agents

Four of the six results come down to one line in .env.

Create every agent workspace with --database=clone. It isolated the database in the setup where shared mode wiped the parent, and the queue follows, since the jobs table lives in that database. --database=empty gives a fresh one instead.
Don't read the warning as the answer. It said "shared" for a workspace that wasn't, and it would say the same for one that was. Check DB_DATABASE in the workspace's .env instead.
Push first, or pass --local. Otherwise the agent works on your last pushed commit.
Delete workspaces when the agent is done. herd workspace:delete drops a workspace's own database unless you pass --keep-database. Deleting a shared workspace left the parent's database alone in my test, and Herd kept the branch in the parent repository.

If you start agents from Herd Studio instead of the CLI, the choice moves into a menu under the prompt box. A new workspace there takes its database mode from Herd's settings, under Workspaces, so check that setting before you start an agent there.

One caveat for my own setup. Herd only runs on macOS and Windows, and its FAQ says Linux isn't ready yet. I moved my day-to-day development to a remote dev box at the end of August, so workspaces only help me when I'm working on the Mac.

FAQ

Are Herd 2 workspaces git worktrees?

Not by default. herd workspace makes a copy-on-write clone of the folder with a full .git directory on a new branch. Herd can also serve a worktree you created yourself with git worktree add, and herd workspaces lists those as worktrees that aren't served yet.

Do Herd 2 workspaces need Herd Pro?

Not for what I tested. Workspaces, --database=clone and the delete command all worked on the free version of Herd 2.1.0 with SQLite. The MySQL and PostgreSQL services themselves are part of Herd Pro.

Does each workspace get its own database?

Only with --database=clone or --database=empty. The default is shared, which shares whatever DB_DATABASE points at. For Laravel's default SQLite file inside the project, that happens to be a separate copy anyway.

Does deleting a workspace delete my database?

A workspace with its own database has that database dropped unless you pass --keep-database. Deleting a shared workspace didn't touch the parent's database in my test.

Can two agents run migrations at the same time?

Yes, if each workspace has its own database. In shared mode they both migrate the parent's database, and the second migrate:fresh wipes whatever the first one just built.

Isolated files, shared state

Workspaces isolate the code well. Every workspace got its own files, branch and domain, with no setup. The database and the queue are only as isolated as DB_DATABASE makes them, and Herd's warning can't tell you which case you're in.

One Request Waited 5 Seconds to Clean Up Laravel Sessions. Here Is What 13.39's session:garbage-collect Changes

Hafiz — Thu, 05 Nov 2026 05:15:09 +0000

I put a million expired sessions into the sessions table of a fresh Laravel 13.39 app and set the session lottery to always win. The next page view took 5.2 seconds. Every other page view took 6 milliseconds.

That's the lottery. By default, about 2 in every 100 requests that start a session also clean up expired sessions, and they do it before your route runs. Laravel 13.39 added session:garbage-collect so a scheduled job can do that work instead. I measured both on the default setup, the database session driver on SQLite. The command fixed the unlucky-visitor problem and created a new one. All output below is real.

How the lottery works

The StartSession middleware starts the session, then rolls the dice, then calls your route:

$request->setLaravelSession(
    $this->startSession($request, $session)
);

$this->collectGarbage($session);

$response = $next($request);

collectGarbage() checks the lottery value in config/session.php, which ships as [2, 100]. On a win, the database handler runs one query:

return $this->getQuery()->where('last_activity', '<=', $this->currentTime() - $lifetime)->delete();

The skeleton's migration indexes last_activity, so finding the expired rows is cheap. Deleting them is not, once there are enough of them.

Where a million expired sessions come from

Any request to a web route without a session cookie gets a new session, and the database driver writes it as a row. I sent 50 requests with plain curl, then 50 more that kept their cookies:

rows before: 0
after 50 requests without cookies: 50
after 50 more with one cookie jar: 51

Crawlers, uptime monitors and most scripts don't keep cookies. Each hit is a row that sits there until it expires and something deletes it. With steady traffic and the lottery on, cleanup runs often enough that each win only has a few rows to delete. A backlog builds when cleanup stops, for example when the lottery is set to [0, 100] with nothing scheduled in its place, or on an old table that was never cleaned.

I seeded a backlog directly in SQLite, with rows shaped like real ones (same payload size, a crawler user agent, last_activity three days back):

seeded in 2.4s
1000051|1000000
db size: 404M

That's 1,000,000 expired rows and 51 live ones, in a 404 MB database file.

What the winning request pays

With the lottery off, page views took 6 to 10 milliseconds. Then I set it to [100, 100], so the next request would win:

lottery [0,100], 5 requests: 0.010s 0.006s 0.006s 0.006s 0.006s
lottery [100,100], request that runs the cleanup: 5.199s
rows after: 57
next requests (nothing left to delete): 0.007s 0.006s 0.006s

I reseeded and ran the winning request twice more, at 6.26 and 5.40 seconds. Then I tried smaller backlogs, each seeded fresh:

Expired rows	Lottery-winning request
1,000	8 ms
10,000	27 ms
100,000	223 ms
1,000,000	5.2 to 6.3 s

Up to a few thousand rows, nobody notices. At a million, one visitor stares at a blank page for five seconds and never knows why. If you've seen a random slow request in your logs that you couldn't reproduce, a lottery win is a candidate.

What session:garbage-collect changes

The new command runs the same handler method on your schedule instead of inside a request:

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('session:garbage-collect')->hourly();

Then turn the lottery off in config/session.php, so requests stop doing it as well:

'lottery' => [0, 100],

On the same million-row backlog, the command did the work in about the same time, with no visitor attached to it:

$ php artisan session:garbage-collect
 INFO Session garbage collector ran successfully.
real 5.84

It doesn't report how many rows it deleted. Count the table before and after if you want to know.

On SQLite, the scheduler doesn't save your visitors

I ran the command again on the full backlog and sent a request every 200 milliseconds while it worked:

request 1: 200 0.009059s
request 2: 200 5.231497s
request 3: 200 5.032121s
request 4: 200 4.831341s
request 5: 200 4.627754s

Request 1 got in before the delete started. The other four waited for it to finish. Every web request writes its session at the end, and SQLite allows one writer at a time, so a five-second DELETE holds up every page view that arrives during it. Moving the cleanup to the scheduler turned one unlucky visitor into everyone who showed up in those five seconds.

That only bites with a big backlog. Run the command often enough that each run deletes a few thousand rows, and each one takes milliseconds, as the table above shows. The problem is the first run on a table that already has a backlog.

I only measured SQLite here, which is what a new Laravel app uses out of the box. MySQL and PostgreSQL don't lock the whole database for a delete, so check your own driver before assuming either result.

Clear an existing backlog in chunks

For the first cleanup, delete in batches and pause between them, so other writes get a turn:

// routes/console.php
use Illuminate\Support\Facades\DB;

Artisan::command('sessions:prune-chunked {--chunk=5000}', function () {
    $cutoff = now()->subMinutes(config('session.lifetime'))->getTimestamp();
    $deleted = 0;

    do {
        $batch = DB::table('sessions')
            ->where('last_activity', '<=', $cutoff)
            ->limit((int) $this->option('chunk'))
            ->delete();

        $deleted += $batch;
        usleep(50_000);
    } while ($batch > 0);

    $this->info("Deleted {$deleted} expired sessions.");
});

Same million rows, same requests arriving every half second while it ran:

request 1: 200 0.017038s
request 2: 200 0.028787s
request 3: 200 0.027196s
request 4: 200 0.026492s
request 5: 200 0.029231s
request 6: 200 0.030707s
request 7: 200 0.028865s
request 8: 200 0.027779s
Deleted 1000000 expired sessions.
real 17.41

It took 17 seconds instead of 6, and no request went over 31 milliseconds.

Run it once, then let session:garbage-collect keep the table small from then on. If chunked deletes are new to you, the same idea shows up in my query optimization post, and the indexing guide covers why the last_activity index matters for the where half of it. Six Eloquent patterns that quietly skip an index shows how that half can go wrong.

The file driver pays even when nothing has expired

The file driver cleans up with Symfony Finder. It walks every file in storage/framework/sessions and checks each modification time. I created 100,000 session files and ran the command twice, first with all of them fresh, then with all of them three days old:

$ SESSION_DRIVER=file php artisan session:garbage-collect   # 100,000 fresh files
real 0.98
files left: 100000

$ SESSION_DRIVER=file php artisan session:garbage-collect   # 100,000 expired files
real 12.67
files left: 0

Almost a second to delete nothing. On the file driver, every lottery win pays for that scan, however few sessions have actually expired. Twelve seconds to delete them all. That's the strongest case for the new command on the file driver, because the scan cost never goes away.

What I'd set up

For the database and file drivers:

// config/session.php
'lottery' => [0, 100],

// routes/console.php
Schedule::command('session:garbage-collect')->everyFifteenMinutes();

Every fifteen minutes keeps each run small on a busy site. If you run several servers against one database, add ->onOneServer(), which needs a cache store that supports atomic locks. With the file driver, each server has its own sessions folder, so the command runs on each one. If the table already has a backlog, run the chunked version once first.

Or skip the question. The cache-backed drivers, Redis among them, write each session with a TTL, and their gc() method returns 0. Expired sessions disappear on their own. If you already run Redis for queues or cache, it's a one-line .env change.

FAQ

What does Laravel's session lottery do?

On each request that starts a session, Laravel rolls the lottery odds from config/session.php, [2, 100] by default. On a win, it deletes expired sessions before your route runs, so that request waits for the delete.

How do I turn off the session lottery?

Set 'lottery' => [0, 100] in config/session.php. Then schedule session:garbage-collect, which Laravel 13.39 added, or expired sessions will pile up forever with the database and file drivers.

Does session:garbage-collect work with Redis sessions?

It runs, but it has nothing to do. The cache-backed handlers store sessions with a TTL, so they expire on their own, and their gc() method returns 0.

Why is my sessions table so big?

Every request without a session cookie creates a new row, and crawlers, uptime checks and scripts rarely send cookies. Rows stay until cleanup deletes them, so if the lottery is off and nothing is scheduled, the table only grows.

Is the first run of session:garbage-collect safe on a big table?

On SQLite with a big backlog, not during traffic. A single delete of a million rows held up every request for about five seconds in my test. Clear the backlog in chunks first, then let the scheduled command keep up.

Conclusion

On SQLite, moving the cleanup to the scheduler is only half the fix. Check how many expired rows you have before the first scheduled run. If the answer is in the hundreds of thousands, clear them in chunks once, then let a small, frequent session:garbage-collect keep it from happening again.

Composer 2.11's Cooldown in a Laravel App: Safer Updates, Except When the Update Is the Security Fix

Hafiz — Mon, 02 Nov 2026 05:15:09 +0000

On 31 October I turned on Composer 2.11's new cooldown in a Laravel 13 project, set it to seven days, and ran composer update. It failed. Three days earlier Symfony had shipped a fix for CVE-2026-45070 in symfony/mime. The cooldown was holding the fix back, and Composer's advisory policy was blocking every older version. My project had nothing it was allowed to install.

The release notes do say the cooldown applies to security fixes too. What they can't show is how fast that bites. The cooldown gives malware scanners time to flag a malicious version before composer update ever offers it to you. But the same rule applies to the version that fixes your vulnerability.

I tried it on a clean Laravel project with Composer 2.11.1, with laravel/framework locked at 13.37.0. Here's what it changed, where it broke, and the setup I'd use. All output below is real.

What the cooldown does

Composer 2.11.0 shipped on 29 October, and 2.11.1 followed a day later. The cooldown is part of the policy config. It's off by default, and it takes effect once you set a period:

composer config policy.cooldown.period "7 days"

"config": {
    "policy": {
        "cooldown": {
            "period": "7 days"
        }
    }
}

The period takes values like "6 hours", "1 day" or "1 week", measured from the publish time the repository reports for each version. It applies when Composer resolves dependencies, so update, require and create-project. composer install still installs exactly what's in composer.lock. Dev versions like dev-main are never withheld.

What it did to a Laravel 13 project

13.39.0 came out on 27 October, four days before I ran this. With a seven-day period, updating the framework stopped one release short:

$ composer update laravel/framework
Loading composer repositories with package information
31 package version(s) withheld by the cooldown policy (run with -vv to list them).
Updating dependencies
Lock file operations: 0 installs, 1 update, 0 removals
  - Upgrading laravel/framework (v13.37.0 => v13.38.0)

31 versions for one package, because the list also counts the illuminate/* packages Laravel publishes alongside each release, a few seconds apart. -vv lists them:

31 package version(s) withheld by the cooldown policy:
  - laravel/framework (v13.39.0) published 2026-10-27T14:05:37+00:00, available in 3 days 4 hours
  - illuminate/bus (v13.39.0) published 2026-10-27T14:04:59+00:00, available in 3 days 4 hours
  - illuminate/bus (v12.70.2) published 2026-10-27T14:08:11+00:00, available in 3 days 4 hours
  - illuminate/collections (v13.39.0) published 2026-10-27T14:05:01+00:00, available in 3 days 4 hours

composer outdated has a new marker for it:

$ composer outdated --direct
Legend:
! patch or minor release available - update recommended
~ major release available - update possible
c newer release still in the cooldown period - not installable yet
laravel/framework 13.38.0 c 13.39.0 (3d 4h left) The Laravel Framework.
phpunit/phpunit   12.5.42 c 13.4.4 (2d 17h left) The PHP Unit Testing framew...

And --no-cooldown skips it for one package, one command:

$ composer update --no-cooldown laravel/framework
  - Upgrading laravel/framework (v13.38.0 => v13.39.0)

So far it does what it says. The surprises started with a full update.

A full update downgraded 23 packages

With laravel/framework now at 13.39.0, still inside the cooldown, I ran a plain composer update. I'll get to why it failed in the next section. With the package behind that failure exempted, here is what the same update planned:

$ composer update --dry-run
78 package version(s) withheld by the cooldown policy (run with -vv to list them).
Updating dependencies
Lock file operations: 0 installs, 23 updates, 0 removals
  - Downgrading doctrine/inflector (2.1.1 => 2.1.0)
  - Downgrading guzzlehttp/guzzle (8.3.1 => 8.3.0)
  - Downgrading laravel/framework (v13.39.0 => v13.38.0)
  - Downgrading league/commonmark (2.10.6 => 2.10.4)
  - Downgrading nesbot/carbon (3.15.1 => 3.15.0)
  - Downgrading symfony/console (v7.4.22 => v7.4.21)
  - Downgrading symfony/http-kernel (v7.4.22 => v7.4.21)
  - Downgrading symfony/mailer (v7.4.22 => v7.4.19)
  ...

The Packagist announcement warns about this. A full composer update re-checks every package, and anything locked at a version still inside the window gets swapped for an older one. A partial update leaves unrelated packages alone. If you add a cooldown to a project that's already up to date, your first full update moves it backwards. Run it with --dry-run first and read the list.

When the update is the security fix

CVE-2026-45070 is an email header injection in symfony/mime, rated medium. The advisory was published on 28 October, alongside the fixed releases, 7.4.22 and 8.1.10. laravel/framework requires symfony/mime, so every Laravel app has it.

Composer also blocks versions with known advisories during update by default (policy.advisories.block defaults to true). Put the two policies together and a project still on the vulnerable 7.4.19 has nowhere to go:

$ composer update symfony/mime
2 package version(s) withheld by the cooldown policy (run with -vv to list them).
Updating dependencies
Your requirements could not be resolved to an installable set of packages.
  Problem 1
    - laravel/framework v13.39.0 requires symfony/mime ^7.4.0 || ^8.0.0 -> found symfony/mime[v7.4.0, ..., v7.4.22, v8.0.0, ..., v8.1.10] but these were not loaded, because:
      - v7.4.12, v7.4.13, v7.4.15, v7.4.16, v7.4.17, v7.4.18, v7.4.19, v8.0.12, v8.0.13, v8.0.15, v8.1.0, v8.1.2, v8.1.4, v8.1.5, v8.1.6, v8.1.7: affected by security advisories ("PKSA-wtxr-p26d-nn42")
      - v7.4.22, v8.1.10: still in the cooldown period configured in "policy.cooldown" (available in 4 days 9 hours)

Composer refuses to move you to a version it knows is vulnerable, and it refuses to move you to the fix because it's too new. So you stay on the version you're on, which is also vulnerable. And nothing at deploy time tells you. composer install installed 7.4.19 from the lock file without a word and exited 0.

composer audit is the one that speaks up. It found the advisory and exited 1:

$ composer audit
Found 1 security vulnerability advisory affecting 1 package:
+-------------------+----------------------------------------------------------------------------------+
| Package           | symfony/mime                                                                     |
| Severity          | medium                                                                           |
| Advisory ID       | PKSA-wtxr-p26d-nn42                                                              |
| CVE               | CVE-2026-45070                                                                   |
| Title             | CVE-2026-45070: Email Header Injection via Non-Token Characters in Mime          |
|                   | Parameter Names                                                                  |
...

The way out is one targeted command:

$ composer update symfony/mime --no-cooldown
  - Upgrading symfony/mime (v7.4.19 => v7.4.22)
No security vulnerability advisories found.

Use --no-cooldown here, not --no-blocking. Composer 2.11 has both, and the help text explains the difference. --no-blocking "disables all policy blocking during this command", which includes the advisory and malware checks you want to keep. --no-cooldown turns off the cooldown only, and the other policies still apply.

New projects fail the same way. With a seven-day period set through the environment, a fresh install broke that morning:

$ COMPOSER_POLICY_COOLDOWN_PERIOD="7 days" composer create-project laravel/laravel fresh-under-cooldown
Installing laravel/laravel (v13.11.0)
81 package version(s) withheld by the cooldown policy (run with -vv to list them).
Your requirements could not be resolved to an installable set of packages.
      - v7.4.22: still in the cooldown period configured in "policy.cooldown" (available in 4 days 8 hours)

laravel new runs composer create-project under the hood, so a cooldown in your global Composer config affects it too.

Your own packages

Two kinds of repository came up in my test, and they behaved differently.

A path repository, the usual setup for a package that lives in your monorepo, installed fine. Composer warned that it couldn't verify the publish date and moved on:

The publication date of 1 package version(s) from path repo (packages/acme-helpers) could not be verified, the cooldown policy relied on the time field set by the package authors (run with -vv to list them).
  - Installing acme/helpers (1.0.0): Symlinking from packages/acme-helpers

A git repository with a tag I'd created a minute earlier did not:

Problem 1
  - Root composer.json requires acme/sdk ^1.0, found acme/sdk[v1.0.0] but these were not loaded, because they are still in the cooldown period configured in "policy.cooldown" (available in 6 days 23 hours, based on the package-supplied time field as the repository provides no published-time).

That's the in-house SDK your team tagged this morning, blocked for a week. The ignore list fixes it, with a reason that ends up in composer.json for the next person:

"cooldown": {
    "period": "7 days",
    "ignore": {
        "acme/*": "Our own packages, tagged by us"
    }
}

With that in place, the same composer require acme/sdk locked v1.0.0 straight away. If you serve private packages from your own Composer repository, check what it reports. The Composer docs say a repository that doesn't provide published-time makes the command error out while a cooldown is set, and a trusted repository can opt back into the older time field with require-published-time set to false.

Which period to pick

The Packagist announcement suggests a few hours to a day. I ran the same full-update dry run with four periods, at 09:21 UTC on 31 October:

Period	Versions withheld	Full `composer update`
1 hour	0	Resolves
1 day	2	Resolves (one bugfix release of `league/commonmark` rolled back)
3 days	41	Fails on `symfony/mime`
7 days	81	Fails on `symfony/mime`

A day matches Packagist's own suggestion, and a security fix stops blocking you by the next working day. With three days, my full update stayed broken until the evening of 31 October. With seven, it stays broken until 4 November, all because one package every Laravel app depends on shipped a security fix.

In CI you don't have to commit the setting. COMPOSER_POLICY_COOLDOWN_PERIOD sets it from the environment. With nothing in composer.json, this was enough for outdated to apply it:

$ COMPOSER_POLICY_COOLDOWN_PERIOD="7 days" composer outdated --direct
Cannot use laravel/framework's latest version v13.39.0 as it is still in the cooldown period configured in "policy.cooldown" (available in 3 days 4 hours).

The setup I'd use

A one-day period, with your own vendor name exempt:

"config": {
    "policy": {
        "cooldown": {
            "period": "1 day",
            "ignore": {
                "acme/*": "Our own packages, tagged by us"
            }
        }
    }
}

Add composer audit to CI as its own step, because composer install won't tell you about a vulnerable lock file and audit exits 1 when it finds one. If you don't have a pipeline yet, my GitHub Actions guide has a starting point. And write the escape hatch down before you need it. When audit fails and the fix is still in cooldown, run composer update vendor/package --no-cooldown for that one package.

The cooldown and the audit cover different risks. The cooldown keeps a brand new malicious version out of your lock file. The audit catches a known vulnerability already in it. I wrote about the first problem after fake Laravel packages started targeting .env files. A cooldown only helps if the fake is caught inside the window, so it doesn't replace reading what you install.

If you're mid-upgrade, the cooldown adds one more kind of line to your conflict output. The usual Laravel 13 upgrade conflicts still come first, and a release you're waiting for may now also be "still in the cooldown period".

FAQ

Does the Composer cooldown affect composer install?

No. composer install installs exactly what's in composer.lock, whatever the cooldown says. The cooldown applies when Composer resolves versions, during update, require and create-project.

Does the cooldown hold back security fixes?

Yes. Composer doesn't exempt them. The Packagist announcement explains why. Any rule that exempted releases based on advisory data would give attackers a way around the cooldown. Run composer update vendor/package --no-cooldown when you need a fix sooner.

What's the difference between --no-cooldown and --no-blocking?

--no-cooldown turns off the cooldown for one command and keeps the advisory and malware policies active. --no-blocking turns off all policy blocking, including those. For a security fix, --no-cooldown is the one you want.

Why does composer update downgrade packages after I enable a cooldown?

A full composer update re-evaluates every package against the cooldown. A version you already have locked that is still inside the window gets replaced with the newest version outside it. A partial update, like composer update vendor/package, leaves other packages alone.

Do my production servers need Composer 2.11?

Not for the cooldown. It only matters where you run update or require, which is usually your machine or CI. Deploys that run composer install from the lock file aren't affected. Upgrade anyway, though, because 2.11 also ships security fixes of its own, listed in the release notes.

Conclusion

Set the cooldown to a day, exempt your own packages, and run composer audit in CI. Then keep composer update vendor/package --no-cooldown somewhere your team will find it. In the week I tried it, the cooldown's first real cost was a security fix, and only the audit told me it mattered.

Laravel's Built-In JSON:API Resources vs timacdonald/json-api vs laravel-json-api: Which One Your API Needs

Hafiz — Thu, 29 Oct 2026 05:15:10 +0000

On Laravel 13.38.0, a request for 20 posts with ?include=author,comments ran 41 queries through the framework's own JSON:API resources. The fix is merged into the 13.x branch. It just isn't in a release yet.

I found that while building the same small API three ways: with Laravel's built-in JsonApiResource, with timacdonald/json-api, and with laravel-json-api/laravel. Same three models (users, posts, comments), same 20 posts and 100 comments, on a clean Laravel 13.38.0 project with SQLite. Each request went through a small middleware that counts queries. All output below is real.

Two of the three look almost the same from the outside. The third is a different kind of tool. One question tells you which you need. (If you're still deciding how the API itself should behave, my production API practices post is the place to start.)

Check your version first

If you already use the built-in resources, three things depend on your Laravel version.

GHSA-5wcm-3v2w-8362. A moderate advisory, published on 19 October. A crafted request to a read-only endpoint could trigger a destructive operation on a related table through relationship inclusion. It affects 12.45.0 up to 12.68.0, and every 13.x release before 13.27.0. Fixed in 12.68.0 and 13.27.0.

Nested includes from 13.27 to 13.36. Release 13.27.0 also changed how resources load relationships (#61322). From then on, nested includes ran one query per related model until #62000 fixed it in 13.37.0. I installed each version and ran the same request, a user with 20 posts and 5 comments per post:

GET /api/builtin/users/1?include=posts.comments.author

13.26.0    4 queries
13.36.0  122 queries
13.38.0    4 queries

Collection includes, on every release so far. #62000 fixed single resources. Collections still load each item's includes one model at a time. This one predates the regression. Issue #61252 reported 101 queries for 100 records on 13.24. The fix is #62152, merged on 22 October, two days after 13.38.0 shipped:

                                  13.26.0   13.36.0   13.38.0   13.x-dev
GET /posts?include=author              21        21        21          2
GET /posts?include=author,comments     41        41        41          3

Until the next tag, eager-load whatever the client asked for. The resource skips relations that are already loaded:

Route::get('/posts', function (Request $request) {
    $includes = array_intersect(
        explode(',', $request->query('include', '')),
        ['author', 'comments', 'comments.author'],
    );

    return PostResource::collection(Post::with($includes)->get());
});

GET /api/builtin/eager/posts?include=author             2 queries
GET /api/builtin/eager/posts?include=author,comments    3 queries

I diffed the response bodies against the version without with(), and they were identical. Keep the allow-list. Eloquent resolves each name passed to with() by calling it as a method on a fresh model instance, so a raw include string lets the client choose which method runs. (If you want the wider picture on spotting N+1 queries, my query optimization post walks through it.)

The built-in JsonApiResource

It arrived in Laravel 12.45.0 (#57571) and is documented in the API resources docs. php artisan make:resource PostResource --json-api generates a class with two properties, and filling them in is most of the work:

namespace App\Http\Resources;

use Illuminate\Http\Resources\JsonApi\JsonApiResource;

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

    public $relationships = [
        'author' => UserResource::class,
        'comments',
    ];
}

Both relationships resolve on their own. The built-in finds CommentResource and UserResource from the related models, so the explicit class on author is optional. I kept it to show the syntax. A route returns it like any resource, and sparse fieldsets and includes work from the query string:

GET /api/builtin/posts/1?include=author&fields[posts]=title&fields[users]=name

{
    "data": {
        "id": "1",
        "type": "posts",
        "attributes": {
            "title": "Post 1"
        },
        "relationships": {
            "author": {
                "data": {
                    "id": "1",
                    "type": "users"
                }
            }
        }
    },
    "included": [
        {
            "id": "1",
            "type": "users",
            "attributes": {
                "name": "Hafiz"
            }
        }
    ]
}

The response goes out as application/vnd.api+json. A paginator gives you first, last, prev and next links, with Laravel's usual pagination meta and a plain ?page=2 parameter. Nesting stops at five levels by default, and JsonApiResource::maxRelationshipDepth() changes that. toLinks() and toMeta() add per-resource links and meta.

That's the whole job. The built-in shapes responses. It doesn't read JSON:API requests or enforce the rest of the spec, and three gaps showed up straight away.

It ignores include paths it doesn't know. ?include=secrets returned 200 with the post and no error. The JSON:API spec says a server that can't identify a relationship path "MUST respond with 400 Bad Request".

Errors come out in Laravel's own format, not as JSON:API error objects. Here's a 422 from a POST route I wrote by hand:

{"message":"The data.attributes.title field is required. (and 1 more error)","errors":{"data.attributes.title":["The data.attributes.title field is required."],"data.attributes.body":["The data.attributes.body field is required."]}}

And writes are yours to build. That route validates data.type and data.attributes.* with ordinary rules, then returns the new resource with a 201:

Route::post('/posts', function (Request $request) {
    $validated = $request->validate([
        'data.type' => ['required', 'in:posts'],
        'data.attributes.title' => ['required', 'string', 'max:120'],
        'data.attributes.body' => ['required', 'string'],
    ]);

    $post = $request->user()->posts()->create($validated['data']['attributes']);

    return (new PostResource($post))->response()->setStatusCode(201);
});

It works. But relationships in the request body, error objects with JSON pointers, and content negotiation are all on you. For filters and sorting, the docs point you at Spatie's Laravel Query Builder, which supports Laravel 12 and 13 in its current 7.x release (it needs PHP 8.4).

timacdonald/json-api

Tim MacDonald's package has been around since its first release in November 2021, and the built-in uses the same property-based API:

use TiMacDonald\JsonApi\JsonApiResource;

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

    public $relationships = ['author' => UserResource::class, 'comments' => CommentResource::class];
}

I compared the package and the built-in on three requests (a single post with includes, the collection, and a user with sparse fieldsets). Once the keys were sorted, the documents were identical. Then I changed only the use line in my three package resources to the built-in Illuminate\Http\Resources\JsonApi\JsonApiResource, and the same three requests still returned identical documents.

The other direction needs care. The package guesses the resource class from the relationship key, not from the related model, so 'author' with no class failed with a 500, because there's no AuthorResource. Moving from the package to the built-in was the use line. Moving from the built-in to the package can mean adding explicit classes.

The difference is loading. The package doesn't eager-load by design, and its README says so plainly. It recommends Spatie's query builder for that job. Without it:

GET /api/tim/users/1?include=posts.comments.author    123 queries
GET /api/tim/posts?include=author                      22 queries
GET /api/tim/posts?include=author,comments             43 queries

With the same with() allow-list from earlier, those collection requests dropped to 2 and 3 queries.

It's still a pre-release. The latest tag is 1.0.0-beta.12, from March 2026. The repository isn't archived, and its constraints cover Laravel 11, 12 and 13. That makes it the right choice on Laravel 11, or on a 12.x app older than 12.45.0. On anything newer I wouldn't start a new API on it, because the built-in gives you the same API from the framework itself, and the N+1 fix lands in the framework too. If you're already on it, my migration for these three resources was the use line.

laravel-json-api/laravel

This is a different kind of tool. It isn't a resource class, it's a full JSON:API server. Version 5.3.0 (July 2026) supports Laravel 12.61.1 and up and 13.x.

Setup is more work. I published the config, generated a server with php artisan jsonapi:server v1, registered it in config/jsonapi.php, generated three schemas and a request class, registered routes, and added its exception renderer in bootstrap/app.php. A schema describes fields instead of output:

class PostSchema extends Schema
{
    public static string $model = Post::class;

    protected int $maxDepth = 3;

    public function fields(): array
    {
        return [
            ID::make(),
            Str::make('title')->sortable(),
            Str::make('body'),
            BelongsTo::make('author')->type('users'),
            HasMany::make('comments'),
            DateTime::make('createdAt')->sortable()->readOnly(),
            DateTime::make('updatedAt')->sortable()->readOnly(),
        ];
    }

    public function filters(): array
    {
        return [
            WhereIdIn::make($this),
            Where::make('author', 'user_id'),
        ];
    }

    public function pagination(): ?Paginator
    {
        return PagePagination::make();
    }
}

JsonApiRoute::server('v1')->prefix('v1')->resources(function ($server) {
    $server->resource('posts', JsonApiController::class)
        ->relationships(function ($relations) {
            $relations->hasOne('author')->readOnly();
            $relations->hasMany('comments')->readOnly();
        });
    $server->resource('users', JsonApiController::class)->only('index', 'show');
});

That route block registered create, update and delete for posts, plus the related-resource and relationship endpoints (/posts/{post}/author, /posts/{post}/relationships/comments), with no controller code of mine.

Then it does the things the built-in leaves to you. Includes are eager-loaded with no help:

GET /api/v1/users/1?include=posts.comments.author    4 queries
GET /api/v1/posts?include=author                     2 queries
GET /api/v1/posts?include=author,comments            3 queries

Include paths are validated. The default $maxDepth is 1, which is why the schema above raises it. Before I did, the nested request came back like this, and so does any path the schema doesn't declare:

{"jsonapi":{"version":"1.0"},"errors":[{"detail":"Include path posts.comments.author is not allowed.","source":{"parameter":"include"},"status":"400","title":"Invalid Query Parameter"}]}

?filter[author]=2, ?sort=-title and ?page[number]=2&page[size]=5 worked straight away. Writes are validated against the request class, and the errors point at the exact member of the request document:

422 Unprocessable Entity | The title field is required. | /data/attributes/title
422 Unprocessable Entity | The body field is required. | /data/attributes/body
422 Unprocessable Entity | The author field is required. | /data/relationships/author

A POST with a plain application/json body was refused with a 415. A proper document, with the author passed as a relationship, created the post and returned it with a 201.

Two costs to know about. Authorization runs through your policies by default. I switched it off for this test with authorizable() returning false on the server, but in a real app you'd write the policies (my policies vs gates guide covers those). And it brings its own conventions, like camelCase createdAt, its own controller, and a schema layer your team has to learn.

Which one your API needs

	Built-in `JsonApiResource`	timacdonald/json-api	laravel-json-api/laravel
What it is	Resource classes	Resource classes	Full server
Minimum Laravel	12.45.0	11	12.61.1
Eager-loads includes	Single resources (13.37+), collections not yet	No, by design	Yes
Unknown include path	Ignored, 200	Ignored, 200	400 error object
Filters, sorting	Spatie Query Builder	Spatie Query Builder	Built in
Writes and validation	Your code	Your code	Request classes, JSON pointers
Error format	Laravel's	Laravel's	JSON:API error objects
Status	First-party	1.0.0-beta.12	5.3.0

The question that decides it is whether clients write through the API.

If they only read, and what you need is the JSON:API shape for a front end or a mobile app, use the built-in. You get includes, sparse fieldsets and links from three small classes, and the remaining N+1 is a framework bug with a fix already merged. Add the with() allow-list until it ships.

If clients create and update resources through it, or a third party will build against your API and expects the spec enforced (error objects, rejected include paths, filters and pagination by the book), use laravel-json-api. Its setup cost is real, but you'd spend more than that rebuilding its validation and errors by hand on top of the built-in.

And timacdonald/json-api is for apps that can't run the built-in yet.

FAQ

Does Laravel's built-in JSON:API resource support filtering and sorting?

No. It shapes responses and handles include and fields. The Laravel docs point to Spatie's Laravel Query Builder for filters and sorts, and its current 7.x release supports Laravel 12 and 13 on PHP 8.4.

Can the built-in JsonApiResource accept JSON:API documents in POST or PATCH?

Only through your own code. You validate data.attributes.* with normal rules and create the model yourself. Validation errors come back in Laravel's default format, not as JSON:API error objects.

Is timacdonald/json-api abandoned?

No. The repository isn't archived and the latest release, 1.0.0-beta.12, supports Laravel 11 to 13. It's still a pre-release, though, and on Laravel 12.45.0 or newer the built-in offers the same property-based API.

Why does laravel-json-api reject my include with a 400?

Either the path isn't a relationship on the schema, or it's deeper than the schema's $maxDepth, which defaults to 1. The JSON:API spec requires a 400 when a server can't support an include path, and the package follows it.

Which Laravel version fixes the JSON:API N+1 queries?

Nested includes on a single resource are fixed in 13.37.0. Includes on collections are fixed on the 13.x branch by #62152, which was merged after 13.38.0 and should ship in the next 13.x release. Check the release notes for #62152 before you remove a with() workaround.

Conclusion

Whichever you pick, run composer show laravel/framework before you ship it. Anything from 13.27.0 to 13.36.0 loads nested includes one model at a time, and every release up to 13.38.0 does the same for collection includes until #62152 is tagged.

Smoke

Hafiz — Wed, 28 Oct 2026 10:48:04 +0000

Hi

Body.

Your Users Save and Still See Old Data: Laravel 13.38 Fixes Read Replica Lag, Except in 3 Places

Hafiz — Mon, 26 Oct 2026 05:15:09 +0000

I changed a post title to "Q4 pricing update", got the green "Saved" banner, and the heading right under it still said "Q3 pricing update". The debug line on the same page said the request had read from the primary. That was Laravel 13.38.0, with the new PreventStaleDatabaseReads middleware installed exactly the way the docs show it.

The middleware is a good idea. Jack Bayliss wrote it after seeing his replicas lag 0 to 1 seconds on average and up to 15 seconds under some workloads. That's long enough for a user to edit a title, refresh, see the old one, and file a bug report. It shipped in v13.38.0 on 20 October.

To see what it covers, I set up a MySQL 8.4 primary and a replica in Docker, held the replica 5 seconds behind with delayed replication (SOURCE_DELAY=5), and pointed a clean Laravel 13.38.0 project at both. Five seconds is slow for a healthy replica. That's the point. It makes every gap reproducible on a laptop. All output below is real.

The documented setup needs one extra call before it protects the most common kind of page. And three things the middleware never touches still read stale data after you fix it. API routes, queued jobs, and the database cache store, which is where your rate limiter keeps its counts.

What sticky already did, and what 13.38 adds

Laravel has split reads and writes for years. You give the connection a read and a write server, and set sticky so a request that writes also reads its own writes:

'mysql' => [
    'driver' => 'mysql',
    'read' => ['port' => env('DB_READ_PORT', '3306')],
    'write' => ['port' => env('DB_WRITE_PORT', '3306')],
    'sticky' => true,
    // host, database, credentials...
],

Both of my servers run on 127.0.0.1, so only the port differs. In production you'd override host instead.

But sticky only lasts for one request. Save a form, redirect, and the GET that follows is a new request on a clean connection. It reads the replica.

PreventStaleDatabaseReads carries the write across requests through the session. This is the core of it, from the framework source:

$connection->useWriteConnectionWhenReading(
    $request->session()->get('_database_modified_at', 0) >= Date::now()->subSeconds((int) $seconds)->getTimestamp()
);

$response = $next($request);

if ($connection->hasModifiedRecords()) {
    $request->session()->put('_database_modified_at', Date::now()->getTimestamp());
}

Three details in those lines come back later. It calls $request->session(), so it needs a session. It only touches the default connection. And it compares whole-second timestamps, so a 2 second window stays open for somewhere between 2 and 3 seconds.

The same release added usingWritePdo(). It runs a callback with every read on that connection sent to the primary, then restores the previous setting, even if the callback throws. Most of the fixes below use it.

The documented setup still served the old title

The docs tell you to append the middleware to the web group:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->web(append: [
        PreventStaleDatabaseReads::class,
    ]);
})

I did that, saved a new title, and reloaded the page every second with the same session cookie. The page prints its title and the @@server_id of whichever server answered a select in the route closure. Server 1 is the primary, server 2 the replica.

+0.0s PUT  title="Q4 pricing update"
+0.1s GET  title="Q3 pricing update"  read from server_id 1 (primary)
+1.2s GET  title="Q3 pricing update"  read from server_id 1 (primary)
+2.3s GET  title="Q3 pricing update"  read from server_id 1 (primary)
+3.4s GET  title="Q3 pricing update"  read from server_id 2 (replica)
+4.5s GET  title="Q3 pricing update"  read from server_id 2 (replica)
+5.6s GET  title="Q3 pricing update"  read from server_id 2 (replica)
+6.7s GET  title="Q4 pricing update"  read from server_id 2 (replica)

The middleware did its job. For the first three reloads the query in the closure went to the primary. The title was stale anyway, because it came from $post, and $post came from route model binding.

Route model binding happens in SubstituteBindings, which is already in the web group. Appending puts the new middleware after it. Laravel does sort some middleware by a priority list, and SubstituteBindings is on that list. PreventStaleDatabaseReads isn't, so it keeps its appended position. By the time it switches the connection to the primary, the model has already been loaded from the replica.

So add it to the priority list:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->web(append: [
        PreventStaleDatabaseReads::class,
    ]);

    $middleware->prependToPriorityList(
        before: AuthenticatesRequests::class,
        prepend: PreventStaleDatabaseReads::class,
    );
})

AuthenticatesRequests is the contract the auth middleware implements, and it sits ahead of SubstituteBindings in Laravel's priority list. Going in before it means the user lookup that auth does reads the primary too. It still runs after StartSession, which it needs. This is the order Laravel resolved for GET /posts/{post} after the change:

EncryptCookies
AddQueuedCookiesToResponse
StartSession
ShareErrorsFromSession
PreventRequestForgery
PreventStaleDatabaseReads
SubstituteBindings

I tested the auth part too. A logged-in user renames themselves, then reloads a route behind auth that prints auth()->user()->name and the server that answered its own query. With the middleware only appended, as in the docs, the rename from "Hafiz R" to "Hafiz Riaz" didn't show:

+0.1s PUT  name="Hafiz Riaz"
+0.1s GET  Hafiz R (server_id 1)
+1.1s GET  Hafiz R (server_id 1)
+2.2s GET  Hafiz R (server_id 1)
+3.3s GET  Hafiz R (server_id 1)

That's the name in your nav bar staying wrong after a profile save, on requests that read the primary for everything else. With the priority call in place, the earlier rename from "Hafiz" to "Hafiz R" showed on the first reload:

+0.1s PUT  name="Hafiz R"
+0.1s GET  Hafiz R (server_id 1)
+1.1s GET  Hafiz R (server_id 1)
+2.2s GET  Hafiz R (server_id 1)
+3.3s GET  Hafiz R (server_id 1)

Back to the post title. Same save, same reloads:

+0.0s PUT  title="Q4 pricing update"
+0.1s GET  title="Q4 pricing update"  read from server_id 1 (primary)
+1.2s GET  title="Q4 pricing update"  read from server_id 1 (primary)
+2.3s GET  title="Q4 pricing update"  read from server_id 1 (primary)
+3.4s GET  title="Q3 pricing update"  read from server_id 2 (replica)
+4.5s GET  title="Q3 pricing update"  read from server_id 2 (replica)
+5.6s GET  title="Q3 pricing update"  read from server_id 2 (replica)
+6.7s GET  title="Q4 pricing update"  read from server_id 2 (replica)

Better, and in one way worse. The user now sees the new title, then the old one again, then the new one. The default window closed after about 3 seconds, and my replica needed about 6.

The window has to outlast your replica lag. for() sets it in seconds:

$middleware->web(append: [
    PreventStaleDatabaseReads::for(6),
]);

The priority entry can stay as the plain class name. I printed the resolved order again to check, and PreventStaleDatabaseReads:6 still landed before SubstituteBindings.

+0.0s PUT  title="Q4 pricing update"
+0.1s GET  title="Q4 pricing update"  read from server_id 1 (primary)
+1.2s GET  title="Q4 pricing update"  read from server_id 1 (primary)
+2.3s GET  title="Q4 pricing update"  read from server_id 1 (primary)
+3.4s GET  title="Q4 pricing update"  read from server_id 1 (primary)
+4.5s GET  title="Q4 pricing update"  read from server_id 1 (primary)
+5.7s GET  title="Q4 pricing update"  read from server_id 1 (primary)
+6.8s GET  title="Q4 pricing update"  read from server_id 2 (replica)

Pick the number from your worst observed lag, not your average. On MySQL, Seconds_Behind_Source in SHOW REPLICA STATUS is the figure to watch. Jack's 15 second peak would need for(15) or more. Also, any write on the default connection during a request reopens the window. If a middleware updates last_seen_at on every request, an active user stays on the primary for as long as they keep clicking.

Place 1: API routes

A stateless API route has no session. Put the middleware in the api group and every request fails (output trimmed):

{
    "message": "Session store not set on request.",
    "exception": "RuntimeException",
    ...
}

Jack flags this in the PR himself ("It's session based, so not ideal for API stuff"). Leave it off, and an API client that saves and reads straight back gets the old value for the whole lag. That part I expected. Sanctum was the surprise.

New Sanctum tokens fail until the replica catches up

Sanctum looks up a personal access token with a plain find(), which reads the replica. So a token issued a moment ago doesn't exist yet as far as the next request can tell:

+0.1s POST /api/tokens -> new token issued
+0.1s GET  /api/me -> {"message":"Unauthenticated."} 401
+1.2s GET  /api/me -> {"message":"Unauthenticated."} 401
+2.3s GET  /api/me -> {"message":"Unauthenticated."} 401
+3.3s GET  /api/me -> {"message":"Unauthenticated."} 401
+4.4s GET  /api/me -> {"message":"Unauthenticated."} 401
+5.5s GET  /api/me -> {"message":"Unauthenticated."} 401
+6.5s GET  /api/me -> {"name":"Hafiz"} 200

A mobile app that logs in and immediately loads the profile screen hits exactly this. I fixed it with a token model that tries the replica first and only falls back to the primary on a miss:

namespace App\Models;

use Laravel\Sanctum\PersonalAccessToken as SanctumToken;

class PersonalAccessToken extends SanctumToken
{
    public static function findToken($token)
    {
        return parent::findToken($token) ?? (new static)->getConnection()->usingWritePdo(
            fn () => parent::findToken($token)?->load('tokenable')
        );
    }
}

// AppServiceProvider::boot()
Sanctum::usePersonalAccessTokenModel(PersonalAccessToken::class);

My first version had no load('tokenable'). Login worked, but a signup that returned a token still got 401 for 6 seconds. On signup the user row is as new as the token, and Sanctum loads the user later, outside the callback, from the replica. Loading it inside the callback fixed both flows. (If you're still choosing an auth package, Passport vs Sanctum covers that decision.)

Sanctum gets one thing right here already. When it updates last_used_at, it puts the connection's "modified" flag back the way it found it, so an authenticated GET doesn't count as a write.

Read-your-writes for API clients

For the save-then-read case I wrote a version of the middleware keyed by the authenticated user instead of the session:

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\DB;

class PreventStaleApiReads
{
    public function handle(Request $request, Closure $next, int $seconds = 2)
    {
        if (! $user = $request->user()) {
            return $next($request);
        }

        $connection = DB::connection();
        $key = 'recent-write:'.$user->getAuthIdentifier();

        $connection->useWriteConnectionWhenReading(Cache::has($key));

        $response = $next($request);

        if ($connection->hasModifiedRecords()) {
            Cache::put($key, true, $seconds);
        }

        return $response;
    }
}

It needs the user, so it has to run after auth and before route binding:

$middleware->appendToPriorityList(
    after: AuthenticatesRequests::class,
    append: PreventStaleApiReads::class,
);

// routes/api.php
Route::middleware(['auth:sanctum', PreventStaleApiReads::class.':6'])->group(function () {
    Route::get('/posts/{post}', /* ... */);
    Route::put('/posts/{post}', /* ... */);
});

A token client with no cookies, saving and then reading every second:

+0.0s PUT  {"title":"Saved by an API client"}
+0.1s GET  {"title":"Saved by an API client","server_id":1}
+1.2s GET  {"title":"Saved by an API client","server_id":1}
+2.3s GET  {"title":"Saved by an API client","server_id":1}
+3.3s GET  {"title":"Saved by an API client","server_id":1}
+4.4s GET  {"title":"Saved by an API client","server_id":1}
+5.5s GET  {"title":"Saved by an API client","server_id":1}
+6.7s GET  {"title":"Saved by an API client","server_id":2}

The flag lives in the cache, so the cache must not read from the replica either. If it does, Cache::has() misses for the whole lag and the middleware does nothing. That's place 3.

Place 2: Queued jobs

A job runs in a worker process with its own connection. No session, no HTTP middleware, and none of the sticky state from the request that dispatched it. (It's the same reason tenant context goes missing in workers, one of the three multi-tenancy queue bugs I wrote about in June.)

Laravel already covers part of this. When a worker rebuilds a model from the job payload, restoreModel() calls useWritePdo(), so $this->post itself comes from the primary. Relations don't. The relations you eager-loaded before dispatching are restored with loadMissing(), which reads the replica. So does every query inside handle().

My test job logs the post title, the comment count through the restored relation, and a direct count query. The route adds a comment, then dispatches the job straight away with $post->load('comments'). The primary had 3 comments when the job ran:

SummarisePost {"title":"Saved through the API","comments_relation":2,"comments_query":2}

Fresh title. Both counts stale.

My first run didn't show this at all, and it took me a minute to see why. I was on the default database queue driver, and reserving a job runs an UPDATE on the jobs table. That marks the connection as modified, and with sticky on, everything the job reads afterwards goes to the primary. When I switched the queue to Redis, the stale reads appeared. Any driver that doesn't write to your replicated connection (Redis, SQS) behaves the same way. The 13.36 option Worker::$flushStickyConnections (#61915) doesn't change the database-driver case either, because the worker flushes before it reserves the next job, and the reserve marks the connection again.

The fix I'd use is a job middleware:

namespace App\Jobs\Middleware;

use Closure;
use Illuminate\Support\Facades\DB;

class ReadFromPrimary
{
    public function handle(object $job, Closure $next): mixed
    {
        return DB::connection()->usingWritePdo(fn () => $next($job));
    }
}

class SummarisePost implements ShouldQueue
{
    use Queueable;

    public function __construct(
        #[WithoutRelations]
        public Post $post,
    ) {
    }

    public function middleware(): array
    {
        return [new ReadFromPrimary];
    }

    // handle() unchanged
}

SummarisePost {"title":"Saved through the API","comments_relation":4,"comments_query":4}

Job middleware runs after the job has been unserialized, so without #[WithoutRelations] a relation stored in the payload is already loaded from the replica by then. Leaving the attribute off, with 5 comments on the primary, I got this:

SummarisePost {"title":"Saved through the API","comments_relation":4,"comments_query":5}

With it, nothing is restored early, and the relation loads lazily inside the middleware's callback.

Put ReadFromPrimary on the jobs you dispatch right after a write, not on every job. A report that runs ten minutes later doesn't need it, and routing every job to the primary defeats the point of having a replica. If a job can wait, ->delay(now()->addSeconds(10)) costs nothing at all. Workers have enough lifecycle rules of their own already (like the SIGTERM they get on every deploy), and if you're tuning them for volume, processing 10,000 queue jobs without breaking covers the worker side.

Place 3: The database cache store, and your rate limiter

A fresh Laravel 13 project ships with CACHE_STORE=database on the default connection. The database cache store reads through that connection with no write-PDO override, so on a replicated connection, cache reads hit the replica. Sessions don't have this problem, because DatabaseSessionHandler adds useWritePdo() to its queries. The cache store doesn't.

Rate limiting is where that hurts. I put throttle:3,1 on a stateless login route and sent a request every half second:

+0.1s attempt 1 -> 200
+0.7s attempt 2 -> 200
+1.3s attempt 3 -> 200
+1.9s attempt 4 -> 200
+2.5s attempt 5 -> 200
+3.1s attempt 6 -> 200
+3.7s attempt 7 -> 200
+4.3s attempt 8 -> 200
+4.9s attempt 9 -> 200
+5.5s attempt 10 -> 200
+6.1s attempt 11 -> 200
+6.7s attempt 12 -> 200
+7.3s attempt 13 -> 429
+7.9s attempt 14 -> 429
+8.4s attempt 15 -> 429
+9.0s attempt 16 -> 429
allowed: 12 of 16 (limit is 3 per minute)

The increments run inside a locked transaction, so they go to the primary and the counter itself is right. But tooManyAttempts() reads the count with a plain cache get, from the replica, which still shows the count from 5 seconds ago. The limiter only starts refusing once the replica has caught up with the third hit. So an attacker gets the limit plus whatever they can send during the lag. At two requests a second that was 12 instead of 3, and a script sends a lot more than two. PreventStaleDatabaseReads doesn't help, because an attacker just drops the session cookie.

Point the cache at a connection without a replica:

// config/database.php
'mysql_primary' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_WRITE_PORT', '3306'),
    'database' => env('DB_DATABASE', 'laravel'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'prefix' => '',
],

DB_CACHE_CONNECTION=mysql_primary
DB_CACHE_LOCK_CONNECTION=mysql_primary

In production that connection gets your primary's host. Same burst afterwards:

allowed: 3 of 16 (limit is 3 per minute)

A Redis cache avoids the problem as well. Either way, the PreventStaleApiReads flag from place 1 depends on this.

What I'd ship

Move the cache off the replicated connection first, even if you skip everything else in this post. A rate limiter that can be outrun is a security bug, not a UX one, and it's a two-line .env change.

Then add PreventStaleDatabaseReads with the priority call and a window longer than your worst lag. Without the priority call it protects the queries in your controllers and misses the model your route is named after.

For APIs, the token fallback is cheap. It costs one extra primary query, and only when the replica misses. The user-keyed middleware is worth it only if your clients read right after they write. If your PUT responses already return the saved resource, your clients may never need it.

For jobs, wrap the few that run straight after a write and leave the rest alone.

Every one of these moves reads onto the primary that the replica was supposed to take. That's the trade. If your lag is routinely more than a few seconds, a longer window hides a replica problem rather than fixing it.

FAQ

Does PreventStaleDatabaseReads stop other users from seeing stale data?

No. It only sends reads to the primary for the session that made the write. Another user viewing the same post during the lag still reads the replica. That's usually fine, because they never saw the new value to begin with.

Do I still need the sticky option?

Yes. They cover different requests. sticky sends reads to the primary later in the same request that wrote. The middleware covers the requests that come after. I had both on for every test in this post.

Does it cover a second database connection?

No. It only tracks and switches the default connection, and the docs say so. If tenant or reporting data lives on another connection, wrap those reads in that connection's usingWritePdo().

Why does a 2 second window last longer than 2 seconds?

The middleware stores and compares whole-second timestamps. A write at 10.0 and one at 10.9 are both stored as 10, and the window closes when the clock reaches 13. So it stays open between 2 and 3 seconds after the write. In my runs, a reload at 2.3 seconds still went to the primary with the default window.

Does the database queue driver protect jobs from stale reads?

By accident, when the jobs table lives on the same replicated connection and sticky is on. Reserving the job is a write, so the job reads the primary. Don't rely on it. Switch to Redis or SQS later and the stale reads show up with no code change.

Conclusion

PreventStaleDatabaseReads fixes the bug Jack described, as long as you add the priority call and size the window to your lag. Both are one-line fixes. Everything else in this post sits outside what a session-based middleware can reach, and none of it needed production traffic to show up. If you run read replicas, start one with SOURCE_DELAY=5 on your laptop and click through your own app before your users do.

I Ran Larastan at Every Level on Agent-Written Laravel Code: 4 Real Bugs, 3 Kinds of Noise

Hafiz — Thu, 22 Oct 2026 04:15:10 +0000

On October 12, Nuno Maduro posted that "it's kind of insane how much AI agents love nullables." His maths was simple. Every nullable doubles the number of states your code can be in, so a constructor with ten of them has over a thousand combinations to reason about.

I wanted to see what that looks like in a real codebase, so I ran Larastan against one of mine at every level from 0 to 10. It's a production Laravel SaaS on Laravel 12 and Filament 4, about 25,000 lines across roughly 250 files in app/, built over the last fifteen months. Most of that code was written by Claude Code, with me reviewing it.

The four real bugs all showed up at level 0. Almost everything above that was typing noise with three causes, and two of them took one line each to fix. The nullables were there too. Some ?-> operators guarded values that could never be null, and some nullable values had no guard at all.

The setup, and the run that died first

Larastan 3.13.0 came out on October 7 and pulls in PHPStan 2.3.1. I cloned the repo into a scratch directory, so nothing here touched the real project:

composer require --dev larastan/larastan

# phpstan.neon
includes:
    - vendor/larastan/larastan/extension.neon

parameters:
    paths:
        - app/
    level: 0

The first run didn't finish:

Internal error: $config must be a string or an array while analysing file
app/Console/Commands/SendActivateDormantCampaign.php

Larastan boots your application, and to type a command's arguments it resolves every Artisan command you have. The file in the error was just the one being analysed. The culprit was another command whose constructor asked the container for a Stripe service, and the service built its Stripe client in its own constructor from config('services.stripe.secret'). With no .env, the secret was null and the Stripe SDK threw. Copying .env.example didn't help either, because an empty STRIPE_SECRET= gives an empty string, and the run died again with "api_key cannot be the empty string".

So static analysis needs a booting app, and in CI that means an .env with non-empty dummy values for anything a constructor reads. The cleaner fix is in the code. A service that talks to an external API shouldn't build its client until something calls it.

Level 0 found four real bugs

Level 0 is meant to be the gentle one. It found the only findings in the whole run that would break in production.

A Filament v3 class in a Filament v4 app. One admin View page called Section::make() eight times, imported from Filament\Infolists\Components\Section. In Filament 4 that class lives in Filament\Schemas\Components, and the old one doesn't exist (I checked vendor/ on 4.5.2). The page throws the moment anyone opens it. Larastan said so in one line:

Call to static method make() on an unknown class Filament\Infolists\Components\Section.

It's the import an agent writes when it remembers Filament v3. The rest of the file was v4 code.

env() outside the config directory. Two places read an admin email like this:

$adminEmail = config('mail.admin_email', env('ADMIN_EMAIL', 'fallback@example.com'));

There's no mail.admin_email key, so it always falls through to env(). And once the config is cached, "the .env file will not be loaded", so env() only sees real system variables. In production the ADMIN_EMAIL value was ignored and the hardcoded fallback won. Larastan's message names the exact problem: "Called 'env' outside of the config directory which returns null when the config is cached, use 'config'."

Enum cases that no longer exist. Two model methods compared a property against enum cases that had been removed from the enum at some point. Nothing calls either method today, which is the only reason nothing broke. The first caller would get an Error, because PHP throws on an undefined enum case.

A duplicate array key. An import command had a lookup map with the same key twice, so the second entry silently replaced the first. Nothing crashes. One mapping just quietly never happens.

None of these four were exotic. All four would have been caught by vendor/bin/phpstan at its lowest setting, on any day in the last year.

Three kinds of noise, and the one-line fixes

From level 2 upwards the counts climbed fast, and almost none of it was a bug. Three causes covered most of it.

Relations without generics

At level 2, almost half the findings mentioned a plain Illuminate\Database\Eloquent\Model. Things like HasMany::valid() being an "undefined method", when valid is a perfectly good scope on the related model. The app has 34 relation methods. Not one of them had a generic return type, so Larastan couldn't tell which model a relation returned.

One docblock per relation fixes it:

/** @return HasMany<ShareToken, $this> */
public function shareTokens(): HasMany
{
    return $this->hasMany(ShareToken::class);
}

That single line removed five level-2 errors in the files that used the relation. It's tedious to add 34 times, which is exactly the kind of work to hand back to the agent that skipped it.

Casts that Larastan didn't read

Larastan kept saying a strict comparison against an enum case would "always evaluate to false", on a model whose casts() method clearly casts that column to the enum. A quick \PHPStan\dumpType() showed Larastan thought the property was a plain string.

The Larastan docs explain why. By default it relies on the return type of the casts() method, and a method declared as returning array says nothing about which cast goes where. Parsing the method body is opt-in, because it's slower:

parameters:
    parseModelCastsMethod: true

Turning it on cut the level 4 findings by 37% and the level 2 findings by about a quarter. If your models use casts() rather than the old $casts property, set this before you read a single result.

`mixed` at levels 9 and 10

Every new finding at level 9 was about mixed, and 93% at level 10. A common source was config(), which returns mixed, so config('app.url').'/about' becomes Binary operation "." between mixed and '/about' results in an error. Laravel already has typed getters for this:

use Illuminate\Support\Facades\Config;

'url' => Config::string('app.url').'/about',

That cleared the finding on that line. It also throws if the value isn't a string, which is better than concatenating null into a URL.

The nullable part

So, did the agent love nullables? Yes, but in two opposite ways.

At level 4, Larastan flagged eight nullsafe operators the code didn't need. Two were on values that can never be null:

Using nullsafe property access on non-nullable type App\Models\User. Use -> instead.

The other six sat on the left of ??, which already handles null. Each ?-> tells the next reader to worry about a null that is either impossible or already handled. That's Nuno's point exactly.

Level 8 is where PHPStan starts reporting method calls on nullable types, and there the agent did the reverse. It called methods on values that really are nullable by type, without narrowing them. Most came from Laravel APIs where the app knows more than the type does:

$request->user() inside routes behind auth middleware, which returns User|null by type. Code using that user accounted for 33 level-8 findings.
->first() straight after an exists: validation rule, so the row is there but the type says it might not be.
Filament's $this->record, typed Model|int|string|null on page classes.

Same root cause both times. The agent handled null from habit instead of reading the types. And the fixes share one idea. Make the type say what the code already knows. For the controllers, Laravel's #[CurrentUser] attribute injects a non-null user:

use App\Models\User;
use Illuminate\Container\Attributes\CurrentUser;

public function me(#[CurrentUser] User $user): JsonResponse
{
    $activeSub = $user->activeSubscription();
    // ...
}

That change cleared all nine level-8 findings in that controller. For the lookups, firstOrFail() instead of first() does the same job and turns a would-be null error into a 404.

PHPStan now talks to your agent

When I ran PHPStan from inside a Claude Code session, the output opened with a block of instructions:

Before fixing the error, fetch the documentation page for its identifier.

The error usually indicates a real bug or incorrect type in the code. Fix the underlying cause, do not just make the error go away.
Do not add `@phpstan-ignore` comments, `@phpstan-ignore-next-line` comments, or baseline entries to suppress the error.
Do not use assert() or inline @var PHPDoc tag to override PHPStan's inferred type.
Do not add type casts just to silence errors.
Do not widen parameter or return types just to make the error go away.

PHPStan added this in 2.1.41 in March, and later versions detect more agents. It checks for environment variables like CLAUDECODE, AMP_CURRENT_THREAD_ID and CURSOR_AGENT, and only prints the block when one is set and there are errors. You won't see it in a normal terminal session.

The quickest way for an agent to make a nullable error disappear is to add a ?->, an @var or a cast. PHPStan now rules out the @var and the cast by name, in the same output that lists the errors.

A baseline and a cache for CI

Fixing everything at level 8 in one go isn't realistic, and you don't need to. Generate a baseline, commit it, and from then on only new code has to be clean:

vendor/bin/phpstan analyse --generate-baseline

# phpstan.neon
includes:
    - vendor/larastan/larastan/extension.neon
    - phpstan-baseline.neon

parameters:
    paths:
        - app/
    level: 8
    parseModelCastsMethod: true
    tmpDir: .phpstan-cache

PHPStan also won't let the baseline go stale. When I fixed one of the baselined findings by switching a first() to firstOrFail(), the next run failed with this:

Ignored error pattern #^Cannot access property \$id on App\\Models\\AffiliateProgram\|null\.$#
(property.nonObject) in path app/Http/Controllers/AffiliateClickController.php
was not matched in reported errors. [identifier=ignore.unmatched]

That error can't be ignored. It's PHPStan asking you to regenerate the baseline, so fixed problems can't quietly come back.

Then the cache. On an M1 Pro, a cold run at level 6 took 3 to 4 seconds. Limited to two processes, like a small CI runner, a cold run at level 10 took 4.2 to 4.7 seconds. With a warm result cache, the same run took 1.1 seconds. After I edited one central service class, it took 2.1 to 2.6 seconds, because PHPStan re-analyses the changed file and everything that references it. It's the same idea as running only the tests your change touched.

Honestly, at 25,000 lines a cold run is cheap. The cache starts to matter on bigger apps. If you want it in GitHub Actions anyway, the PHPStan docs give the recipe. Put tmpDir inside the workspace (the config above does), then restore and save it with a unique key per run:

- name: "Restore result cache"
  uses: actions/cache/restore@v5
  with:
    path: .phpstan-cache
    key: "phpstan-result-cache-${{ github.run_id }}"
    restore-keys: |
      phpstan-result-cache-

- name: "Run PHPStan"
  run: "vendor/bin/phpstan"

- name: "Save result cache"
  uses: actions/cache/save@v5
  if: ${{ !cancelled() }}
  with:
    path: .phpstan-cache
    key: "phpstan-result-cache-${{ github.run_id }}"

That's the docs' version with the path changed to match. I haven't run this workflow, so treat it as the documented starting point. The .env with dummy secrets from the setup section goes in the step before it. For the rest of the workflow, see my GitHub Actions pipeline for Laravel.

Which level to run

Run level 0 today, with no baseline. It's fast, it found every real bug in this app, and this agent-written codebase had stale framework APIs in it.

Then add parseModelCastsMethod, generics on your relations and typed config getters. Those three remove most of what makes the higher levels unreadable.

After that, level 8 with a baseline. That's the level where nullable handling gets checked, which is the habit this codebase most needed correcting. Levels 9 and 10 were all about mixed, mostly from config and decoded JSON. Worth it later. Not first.

FAQ

What Larastan level should I start with on an existing Laravel app?

Start at level 0 without a baseline and fix what it finds, because those are the findings most likely to be real bugs. Then pick the highest level you want new code to meet, often 5 or 8, and generate a baseline for everything that already fails it.

Why does Larastan ignore my Eloquent casts?

If your model uses the casts() method, Larastan only reads its declared return type by default, and array tells it nothing. Set parseModelCastsMethod: true in phpstan.neon so it parses the method body. Models using the $casts property don't need this.

Does Larastan need a database or an .env file?

It doesn't need a database connection for this, but it does boot your application. Any service provider or command constructor that reads a secret and fails on null or an empty string will crash the analysis. Give CI an .env with non-empty dummy values, or build API clients lazily.

Why does PHPStan print instructions for AI agents?

Since PHPStan 2.1.41, when it detects a coding agent through environment variables such as CLAUDECODE or CURSOR_AGENT, it prints guidance telling the agent to fix the cause instead of suppressing errors. It only appears when there are errors and an agent variable is set.

What PHPStan won't catch

PHPStan only checks types. Keep the guardrails that stop an agent doing damage in place too, because a clean level 8 won't stop a migration from dropping a table.

Going Cloud-Only With Laravel: What 7 Weeks on a €5 Dev Box Taught Me

Hafiz — Mon, 19 Oct 2026 04:15:08 +0000

On October 12, Taylor Otwell posted that if he bought a new laptop today, he didn't think he'd install any local dev tools or languages at all. "I think I could do everything I currently do with nothing but Laravel Cloud and @AmpCode Orbs," he wrote, and said he was going to try it. The post pulled 71 replies, and three questions kept coming up. What does it cost? How do you debug when nothing runs on your machine? And can you trust what the agent ships?

I started a version of this experiment seven weeks before he posted. Not with cloud agents, though. With one €5 VPS that holds my projects, a tmux session per project, and Claude Code running inside them. I wrote up the setup and the first round of failures at the end of August.

One correction first. I'm not cloud-only, and that turned out to be the most useful finding.

Two ways to put development in the cloud

From a phone, Taylor's setup and mine look the same. A terminal, an agent, a staging URL. Underneath they're opposite shapes.

Amp's Orbs are ephemeral remote machines. Every new thread gets its own one, with the repository cloned and whatever the agent needs installed. An orb pauses when the agent goes idle, and a paused orb costs nothing. Amp's own description is that "only the diff leaves the orb." Deploys then go through Laravel Cloud, which builds from the repository.

My box keeps everything. One persistent machine, each project checked out once, a tmux session per project that survives any disconnect. The Mac and the iPhone are windows onto it. Staging runs on the box behind a Cloudflare Tunnel with an Access login in front, and production deploys go out through each project's deploy.sh.

The real difference is state. An orb starts from the repository and keeps only the diff. My box holds SQLite copies of production data, queue workers that never stop, a Telegram bot that's always polling, and whatever work is in progress. That persistence is the reason the box is useful, and the cause of most of what broke.

I'm not cloud-only, and the Mac proves it

The Mac still has PHP, Composer and Node. I ran php artisan on it today. A few kinds of work never moved. NativePHP sessions run on the Mac, where the phone and the dev server share a Wi-Fi network. The repo I use for client demos stays local on purpose. So two machines still hold checkouts.

And two checkouts drift, which is why I built the box in the first place. A sync script that reports what's out of step helps. The real fix was a rule instead. A project lives in exactly one place. For anything that has moved to the box, the Mac doesn't keep a copy at all. It attaches to the box's tmux session with one alias, and the laptop becomes the same kind of window the phone is.

Push still matters, for a different reason now. The box is one machine that can die, so every project's CLAUDE.md tells the agent to pull at session start and push after every commit. Each deploy.sh also refuses to run with unpushed commits, because it ships files rather than pulling from git. Without that gate, production can end up running code that exists on no remote. That happened once.

Orbs make this whole section disappear. Nothing lives outside the repository, so there's nothing to drift. That's the first point in Taylor's favour.

What it costs after 52 days

These are the box's numbers on October 16, read straight from it:

Measure	Value
Price	€5 a month, VAT included
Uptime	52 days, no reboot
RAM in use	1.3 GB of 3.9 GB, with two Claude Code instances open
One Claude Code instance	330 to 355 MB resident
Swap in use	178 MB of 2 GB
Disk	15 GB of 78 GB
Load average	0.05

In August I estimated roughly 450 MB per Claude Code instance and called 4 GB the binding constraint. The real figure is lower, and the box spends most of its time waiting on the model, which is why the load average sits near zero.

Taylor's side, from the public price lists. I haven't used Orbs, so read this as a reading of pricing pages, not a review.

Amp's pricing page lists an Individual tier at $20 a month that includes 45,000 minutes of orb time, and tokens can come from your own Claude or ChatGPT subscription. Those minutes are counted at a1.small, the size closest to my box. That's 750 hours, which Amp says covers three at once for eight hours a day.
Pay-as-you-go orb rates run from $0.08 an hour (1 CPU, 2 GB) to $2.13 an hour for the largest size. The closest match to my box, a1.small with 2 CPUs and 4 GB, is $0.17 an hour.
Laravel Cloud's Starter plan is $5 a month plus usage, with $5 of usage credit included and compute that scales to zero.

Careful with the comparison, though. My €5 covers development only. Production runs on servers I was already paying for, which is its own trade-off and the subject of my Cloud vs Forge vs VPS breakdown. So the fair line is Amp's $20 against my €5. The gap is real and small. The other difference is the shape of the bill. Mine is flat whether I work two hours or twelve. Amp's is flat too until the included minutes run out, and orb minutes grow with hours and with parallel threads. And parallel threads are the point of orbs. They run several agents at once, each in its own machine. My box runs them side by side in one.

What broke after the first post

The August post had a table of everything that broke during setup. These came later, from daily use. Several are Laravel-specific, and a few would hit anyone working on a remote machine.

Symptom	Cause	Fix
Livewire buttons did nothing on a tunnelled app. No error, state never saved	Laravel generated `http://` URLs behind the tunnel, and Livewire's update request never landed	Force the scheme and root URL in `AppServiceProvider`
A queued job died on a config key that was right there in the file	The worker booted before the edit and still held the old config	Restart the queue unit after any change, or run `queue:listen`
Telegram couldn't deliver webhooks to the bot	Cloudflare Access guards every path, so Telegram got the login page	Long polling with `getUpdates` from a systemd unit, no inbound route
Search Console data on one site froze for a week, silently	A deploy's `rsync --delete` removed a production-only credential under `storage/app/private`	Exclude `storage/app/private/` wholesale in the rsync exclude file
`deploy.sh` said "Cannot connect to server" while the site stayed up	The production box's Tailscale key had expired six days earlier, and `deploy.sh` connected over Tailscale	Disable key expiry on servers
`deploy.sh` hung, then timed out on port 22	I closed public SSH on a production box, but the dev box's SSH alias still pointed at the public IP	Update every client alias the day a box is hardened
`cloudflared` put a second domain's DNS record inside the wrong zone	The `cert.pem` from `cloudflared tunnel login` is scoped to the zone picked at login	Add the CNAME by hand in the other zone
Every request to Reddit returned 403 "Blocked"	Reddit blocks requests from the hosting provider's IP range	No direct fix. A Reddit front-end mirror loaded in headless Chromium works from the box
Playwright couldn't find its browser inside Claude Code's shell	The agent's shells don't source `/etc/environment`, so `PLAYWRIGHT_BROWSERS_PATH` is unset	Set the variable on the command itself

The Livewire one is a trusted-proxy trap

TLS ends at Cloudflare, and the tunnel hands Caddy plain HTTP. Caddy's reverse proxy, which php_fastcgi builds on, sets X-Forwarded-Proto to the scheme it saw and ignores incoming values unless the sender is a trusted proxy. So PHP receives X-Forwarded-Proto: http.

My vhosts also pass HTTPS=on to PHP-FPM, and that fixed mixed-content errors everywhere else. But this app had trustProxies(at: '*') in bootstrap/app.php, so Laravel believed the forwarded header over the server variable and generated http:// URLs. Livewire's update endpoint was one of them, so from an HTTPS page its update requests went to an http:// URL and never landed. Nothing logged an error.

The fix that's running now, on Laravel 13.30 with Livewire 4:

// app/Providers/AppServiceProvider.php
public function boot(): void
{
    // TLS ends at Cloudflare and the tunnel hands Caddy plain http. Every
    // generated URL (Livewire update endpoint included) must still be https,
    // or Always-Use-HTTPS turns Livewire's POST into a dead GET.
    if (str_starts_with((string) config('app.url'), 'https://')) {
        \Illuminate\Support\Facades\URL::forceScheme('https');
        \Illuminate\Support\Facades\URL::forceRootUrl(config('app.url'));
    }
}

The guard on app.url keeps a plain http://localhost setup working.

The queue worker one gets worse on a dev box

In production, the deploy restarts the workers. On a dev box nothing deploys. You edit config/services.php, the worker running under systemd keeps the config it booted with, and the next job reads the new key as null. Mine died like this:

array_map(): Argument #2 ($array) must be of type array, null given

The queue docs explain why. Workers "store the booted application state in memory" and "will not notice changes in your code base after they have been started." There are two ways out. Restart the unit after every code or config change, which is what I do now. Or run queue:listen on the dev box, which reloads your code for each job and is, in the docs' words, "significantly less efficient."

The trust question, seven weeks in

The August FAQ covered production deploy keys on a box with an agent on it. What's new is isolation between projects.

When the Telegram bot needed its own agent login and its own credentials, sharing root's was wrong and sharing www-data's wasn't much better. It got a dedicated system user, its own PHP-FPM pool on its own socket, its own queue unit and its own cron line. And it's deliberately kept out of the www-data group, because the other projects' .env files are group-readable.

That's isolation an orb gives you for free. Each thread is its own machine, and only the diff comes out. On a shared box, you build isolation per project, by hand, after you notice you need it.

The maintenance nobody demos

While I was collecting the numbers above, the box reported a pending reboot. It's running kernel 6.12.101. Three kernel updates have landed since it booted, and the newest, 6.12.111, is installed and waiting. I found the same trap on a production server in September, where unattended upgrades had installed five kernels that never ran. Uptime looks great on a status page. It also means the running kernel is whatever booted last.

Then there's the Tailscale key row in the table. The default node key expiry is 180 days, and when it passes, "connections to/from the given endpoint will stop working." On a server with SSH locked to the tailnet, that's admin access gone while the site keeps serving. The production boxes I hardened in September have expiry disabled now, and so does the dev box.

None of this is hard. But it's mine to remember. With orbs and Laravel Cloud, patching and access are the provider's job.

Where each setup wins

Taylor's setup wins on these:

Isolation per task, and several agents running in parallel
No drift, because nothing exists outside the repository
No box to patch, reboot or keep reachable
Git-based deploys, which remove the whole rsync --delete class of failure

The box wins on these:

A flat €5 whatever the hours
State that outlives a thread, like production data copies, a bot that polls all day and workers that are always up
Root, any language, any tool, at no extra cost
Staging on real data behind a login, without a per-environment price

If your work is one or two apps already on Laravel Cloud, Taylor's setup removes failure classes I spent seven weeks fixing by hand. If you run several small apps on your own VPSes, with SQLite and long-running processes, one persistent box is cheaper and fits that shape better. I'm keeping the box.

FAQ

Can you run Laravel queue workers on a remote dev box?

Yes, with one habit. Workers keep the application state they booted with, so restart the worker's unit after any code or config change. If you'd rather not think about it, run php artisan queue:listen on the dev box instead. It reloads code for every job at a performance cost that rarely matters in development.

How much RAM does a dev box running Claude Code need?

On mine, two Claude Code instances use 330 to 355 MB each, and the whole box uses 1.3 GB of 4 GB with a tmux session per project. A 2 GB swap file covers spikes from composer install and npm run build. 4 GB is comfortable for a few agents at once.

Why do Livewire actions fail silently behind Cloudflare Tunnel?

Usually because Laravel generates http:// URLs. With trustProxies(at: '*'), Laravel trusts X-Forwarded-Proto, and a local proxy behind the tunnel may report http. Livewire then sends its updates from an https:// page to an http:// URL, and they never reach the component. Forcing the scheme and root URL in AppServiceProvider::boot() fixes it.

Are Amp Orbs cheaper than a VPS for Laravel development?

Not on the price list. Amp's Individual tier is $20 a month with 45,000 orb minutes (750 hours at the 4 GB size), against €5 for a 4 GB VPS. Orbs buy isolation, parallel agents and zero maintenance. A VPS buys persistent state and a flat bill. I haven't used Orbs, so this comes from Amp's published pricing.

The real bill

Money was never the expensive part. Attention was. Orbs take most of that off your plate for $20 a month instead of €5, and Laravel Cloud takes the rest on its own bill. Whether that's worth it depends on one question. Do your projects need state that outlives a thread? Mine do.

Stop Sharing .env Files in Slack: Laravel's Built-In env:encrypt Workflow

Hafiz — Thu, 15 Oct 2026 04:15:08 +0000

A recent r/laravel thread asked how teams share .env secrets with teammates and across environments. One of the most upvoted answers was just the word Slack. It was a joke, but the replies made clear it wasn't entirely one. And the comment that explained Laravel's built-in answer got a reply from someone who'd never heard of it.

It exists, and it's been in the framework since Laravel 9. php artisan env:encrypt turns a .env file into something you can commit, and env:decrypt turns it back on the server. Two recent releases made it much better for teams. Laravel 12.45 added a --readable mode that keeps variable names visible, and Laravel 13.32 (15 September 2026) made updates to that file leave unchanged values alone. Together they turn the encrypted file into something you can actually review in a pull request.

First, most people shouldn't have these values at all

Before encrypting anything, shrink the problem. The best reply in that thread made this point, and it's right. A new developer doesn't need staging or production credentials. They need .env.example and values that work on their own machine.

cp .env.example .env
php artisan key:generate

With Sail, Herd or Docker, the local database, mail catcher and queue have known defaults. Stripe sandboxes give each developer their own test keys. Most third-party APIs let you create a personal sandbox key. If a value only exists in production, it should only exist where production runs.

That leaves a much smaller set of secrets that really need sharing. The staging values a few people deploy with, and the production values the deploy pipeline needs. That's what env:encrypt is for.

How env:encrypt works

The command reads .env (or .env.{name} with --env), encrypts it with AES-256-CBC by default, and writes the same filename with .encrypted on the end. It prints the key once. Laravel doesn't store it anywhere, so it goes straight into your password manager.

The official docs cover the basics. Here's the version worth using in 2026, with --readable:

php artisan env:encrypt --env=production --readable

   INFO  Environment successfully encrypted.

  Key .................... base64:BTdpjAo5VKt267gpICiMwq/F+/jvc4iTM0OjufNjmrc=
  Cipher ......................................................... AES-256-CBC
  Encrypted file ................................... .env.production.encrypted

Without --readable, the output is one opaque blob. With it, every variable keeps its name and only the value is encrypted:

APP_NAME=eyJpdiI6Ikl1T2hnelpQMkFkWSttUGluNUZ1MFE9PSIsInZhbHVlIjoiQ3NldFRnS0Y3YXl...
APP_ENV=eyJpdiI6IkZkN3VXaGYrMnNDZVBkallEVzRweUE9PSIsInZhbHVlIjoiek1mOFhXTGM4c2gx...
APP_KEY=eyJpdiI6Ijkra0dpVlRuaWMvQ0dHdjFPbFVMaUE9PSIsInZhbHVlIjoicUxaQVpnOVVTamww...
DB_PASSWORD=eyJpdiI6IjZVeVRmbHBzMmI4V1BkVVhFMUtRUlE9PSIsInZhbHVlIjoiL2RRTlNLOEYx...
STRIPE_SECRET=eyJpdiI6IkYzN3ZJeitrUVBQNlZOMlVadmVPcVE9PSIsInZhbHVlIjoiTzJWa1I0bj...

Anyone can see which keys exist. Nobody without the key can see a single value. Comments and blank lines from the source file are dropped, so keep your documentation in .env.example.

Why the 13.32 change matters for pull requests

Before Laravel 13.32, re-encrypting rewrote every value, because each encryption uses a fresh random IV. Change one password and the diff showed every line changed. You couldn't tell from the PR what actually happened.

Now, when the encrypted file already exists, --readable asks for the existing key, decrypts what's there, and keeps the ciphertext for any value that didn't change. Here I rotated the database password and added a Postmark token, then re-encrypted with the same key:

php artisan env:encrypt --env=production --readable --key="base64:BTdp..."
git diff --stat

 .env.production.encrypted | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

 STRIPE_SECRET=eyJpdiI6IkYzN3ZJeitrUVBQNlZOMlVadmVPcVE9PSIsInZhbHVlIjo...
-DB_PASSWORD=eyJpdiI6IjZVeVRmbHBzMmI4V1BkVVhFMUtRUlE9PSIsInZhbHVlIjoiL...
+DB_PASSWORD=eyJpdiI6ImpmRHBWR2djcnlqQlhSK3VGekUyZVE9PSIsInZhbHVlIjoiU...
+POSTMARK_TOKEN=eyJpdiI6ImdVcjYxNjBybGM0NHlHVno5bWpkNlE9PSIsInZhbHVlIj...

A reviewer sees exactly what changed. One password rotated, one new key added.

Try it without the key and it refuses rather than silently re-encrypting everything:

   ERROR  The existing encryption key is required to update the encrypted environment file.

That also gives you access control for free. A developer adding a new variable for their feature puts it in .env.example. Only someone who holds the production key can put the real value into .env.production.encrypted. To re-encrypt everything on purpose (a new key, say), pass --force.

The full workflow

1. One key per environment

Generate separate keys for staging and production. Someone who needs to deploy staging shouldn't be able to read production, and with one shared key they could. Each key goes into your password manager, and into the deploy platform for that environment.

2. Editing a file

The encrypted file is the source of truth. The plaintext only exists while you're editing:

php artisan env:decrypt --env=staging --key="base64:..."
# edit .env.staging
php artisan env:encrypt --env=staging --readable --key="base64:..." --prune

--prune deletes the plaintext .env.staging after encrypting. Use it every time, because of the first gotcha below.

3. Decrypting at deploy

On the server (or in the pipeline step that runs there), the key comes from an environment variable called LARAVEL_ENV_ENCRYPTION_KEY. env:decrypt reads it automatically, so the key never appears in a command or a log line.

php artisan env:decrypt --env=production --filename=.env --force
php artisan config:cache

In GitHub Actions, the key is a repository secret:

- name: Decrypt production environment
  run: php artisan env:decrypt --env=production --filename=.env --force
  env:
    LARAVEL_ENV_ENCRYPTION_KEY: ${{ secrets.LARAVEL_ENV_ENCRYPTION_KEY }}

On Forge, Laravel Cloud or a plain VPS with a deploy script, set the variable in whatever environment that script runs in. If you're comparing those platforms anyway, I wrote up Cloud vs Forge vs a VPS earlier this year. And if your deploy runs through a task runner like Envoy or Scotty (I compared both here), the decrypt is just one more line in the task.

Here's the whole flow in one picture:

Three gotchas I hit while testing this

The default .gitignore doesn't cover .env.staging

A fresh Laravel 13 app ignores .env, .env.backup and .env.production. That's it. Create .env.staging to encrypt it and git status shows this:

?? .env.staging

Untracked, not ignored. One git add -A and your staging secrets are in the repo history in plain text, right next to the encrypted copy. Either use --prune every time, or add a line to .gitignore:

.env.*
!.env.example
!.env.*.encrypted

Secrets in git history are the same class of problem as secrets in your logs. Once they're written somewhere durable, deleting the file doesn't undo it.

Without --filename, the app silently ignores what you decrypted

env:decrypt --env=production writes .env.production, not .env. Laravel only loads .env.production if APP_ENV=production is already set outside the file, as a server or process variable. If it isn't, Laravel looks for .env, doesn't find it, and runs on config defaults.

I tested both. Without APP_ENV set, config('app.name') returned 'Laravel'. With APP_ENV=production exported, it returned Acme. No error either way. That's the dangerous part. So always pass --filename=.env in the deploy step, unless you deliberately set APP_ENV at the server level.

config:cache hides anything you read with env() outside config files

After decrypting and running config:cache, I checked a value straight from the environment:

env('STRIPE_SECRET'); // null

The decrypted file had it. But once config is cached, Laravel stops loading .env, and env() only sees real system variables. The docs say this plainly, yet right after switching to encrypted files it's easy to assume the decrypt step broke. It didn't. Read secrets through a config file:

// config/services.php
'stripe' => [
    'secret' => env('STRIPE_SECRET'),
],

// anywhere else
config('services.stripe.secret');

What to rotate when someone leaves

Rotating the encryption key alone does almost nothing. Every old version of .env.production.encrypted is still in git history, and the person who left still has the old key. They can check out last month's commit and decrypt it.

So the order is:

Rotate the actual secrets they could read. Database passwords, payment provider keys, mail tokens, cloud credentials. This is the step that matters.
Generate a new encryption key and re-encrypt with --readable --force --key=<new key>. Update LARAVEL_ENV_ENCRYPTION_KEY on the platform in the same deploy.
Rotate APP_KEY if they had production access. Laravel's APP_PREVIOUS_KEYS lets you do it without logging every user out. Put the old key there, and Laravel encrypts with the new key while still decrypting with the old ones.

This is also the best argument for keeping the circle small. Every person with the production key is a full rotation when they leave. A developer who only ever had local values costs you nothing.

The same logic applies to tools, not just people. If an AI agent in your terminal can run env:decrypt with the key in scope, it can read production. Keep production credentials out of its reach the same way you would with a contractor.

When to outgrow it

env:encrypt is a good fit for a small team with one or two environments. It costs nothing, needs no new service, and the secrets move with the code. Its weak point is the shared key. Everyone who can decrypt production holds the same key, so you can't revoke one person without rotating it for everyone.

Tool	Where the values live	Fits when
`env:encrypt`	Encrypted in your repo, key in the deploy platform	Small team, a few environments, no new service wanted
SOPS	Encrypted in your repo, keys in age, PGP or a cloud KMS	You want per-person keys instead of one shared key, still in git
1Password CLI	Your 1Password vault, referenced as `op://vault/item/field`	The team already lives in 1Password
Doppler	Doppler's hosted service, injected with `doppler run --`	Many services and environments, one place to manage them
Infisical	Hosted, or self-hosted (MIT-licensed core)	You want a Doppler-style service on your own infrastructure

SOPS is the closest step up, because the workflow barely changes. It supports dotenv files and is a CNCF sandbox project. The others move secrets out of the repo entirely, which pays off at scale, and before that is just one more service to run.

If you're already sending .env files over Slack, any of these is an improvement. env:encrypt is the one that's already installed.

FAQ

Is it safe to commit .env.encrypted files to git?

Yes, as long as the key isn't in the repo. The values are encrypted with AES-256-CBC and signed, so they can't be read or tampered with without the key. Decrypting with the wrong key fails with "The MAC is invalid." The real risk is the plaintext file next to it, so use --prune or ignore .env.*.

Where should LARAVEL_ENV_ENCRYPTION_KEY be stored?

In two places. A password manager, so a person can recover it, and the deploy platform's secret store, so the pipeline can use it. Never in the repo, and never in a plain .env that gets committed.

Does env:decrypt run automatically when Laravel boots?

No. Laravel never decrypts at runtime. You run env:decrypt as a deploy step, and the app then reads the plain .env it wrote, like any other deploy.

What does the --readable flag do in env:encrypt?

It encrypts each value separately and keeps variable names in plain text. Since Laravel 13.32, updating an existing readable file with the same key also keeps the ciphertext of unchanged values, so a git diff shows only the variables that changed.

Do developers need the production key?

Almost never. Local development runs on .env.example and local defaults. Only the people who change production configuration and the deploy pipeline need it, and keeping that list short is what makes offboarding cheap.

Filament 5.10 Security Fixes: The Livewire Scope Gap Your Upgrade Doesn't Close

Hafiz — Mon, 12 Oct 2026 04:15:10 +0000

On 8 October, Filament published four security advisories. The fixes shipped two days earlier, in Filament 5.10.0 and 4.15.0. All four are rated medium, and for most apps the answer is simple. Upgrade.

But one of them is different. The advisory about records staying reachable after they leave a user's tenant has its root cause in Livewire, not Filament. Filament 5.10 closes it for resource pages. It says plainly that relation managers, widgets and your own components are not covered. And when I ran composer audit on an affected install, it said everything was fine.

I installed Filament 5.9.0 on a clean Laravel 13.35 project, reproduced the scope problem with a plain Livewire component, and tested two fixes against it. All output below is real.

The four advisories at a glance

Advisory	What it is	Affected	Fixed in
GHSA-6p72-cx74-63f5	Records stay reachable after a scope or tenant change	4.x, 5.x	4.15.0, 5.10.0
GHSA-jpwg-8rw9-v3jj	Email MFA bypass in multi-panel apps with colliding user IDs	4.x, 5.x	4.15.0, 5.10.0
GHSA-q2ph-j76w-c7qx	`FileUpload` kept the client's file extension, so an image could be stored as `.html`	3.x, 4.x, 5.x	3.3.56, 4.15.0, 5.10.0
GHSA-9g92-9qj5-cqjc	Pasted RichEditor custom blocks could run JavaScript	4.x, 5.x	4.15.0, 5.10.0

The current patch releases are 5.10.1 and 4.15.1, both from 7 October. If you're still on v3, only the FileUpload issue applies, and 3.3.56 fixes it.

This is the second round of Filament security fixes in two months. I covered the August round of MFA fixes when 4.12 and 5.7 shipped.

Why composer audit may say you're fine

Here's a Filament 5.9.0 install, which all four advisories affect:

composer show filament/filament | grep versions
composer audit

versions : * v5.9.0
No security vulnerability advisories found.

composer audit reads Packagist's advisory database. When I checked it on 10 October, the newest Filament entry was from 5 October. The four advisories from 8 October weren't there yet. The previous Filament advisory took 12 days to show up after GitHub published it.

So check the version yourself:

composer show filament/filament | grep versions
composer update "filament/*" -W

Why a record outlives its tenant

The advisory describes the symptom. A user opens a record. The record then moves to another tenant, or out of a scope the user is limited to. The page is still open, and the next Livewire request still loads the record. Depending on the page's actions, the user can still view or change it.

It needs an open page and existing access, so this isn't an attacker reaching into arbitrary records. But it is exactly the case multi-tenant apps worry about. Someone moves a client to another team, and the person who just lost access can keep editing from a tab they never closed.

The root cause is in Livewire

A Livewire component can't send an Eloquent model to the browser. When you declare public Project $project, Livewire stores the model's class and key in the page snapshot. On every later request, it loads the model again. This is the line that does it, from Livewire 4.4.7's ModelSynth:

$model = (new $class)->newQueryForRestoration($key)->useWritePdo()->firstOrFail();

And this is newQueryForRestoration() in Laravel 13.35:

public function newQueryForRestoration($ids)
{
    return $this->newQueryWithoutScopes()->whereKey($ids);
}

newQueryWithoutScopes(). Your tenant scope runs on the first request, when the page mounts. It doesn't run when the model is restored on every request after that.

Reproducing it without Filament

To reproduce it, I added a Project model with a team scope:

protected static function booted(): void
{
    static::addGlobalScope('team', function (Builder $query) {
        $query->where('team_id', auth()->user()?->current_team_id);
    });
}

And a plain Livewire component with a public model property:

class ShowProject extends Component
{
    public Project $project;

    public function rename(string $name): void
    {
        $this->project->update(['name' => $name]);
    }
}

The test mounts the component as a user on team 1. It then moves the project to team 2 and calls rename() from the still-open component:

$component = Livewire::test(ShowProject::class, ['project' => $project])
    ->assertSee('Roadmap');

DB::table('projects')->where('id', $project->id)->update(['team_id' => 2]);

dump(Project::find($project->id));

$component->call('rename', 'Renamed after the move');

dump(DB::table('projects')->where('id', $project->id)->first(['team_id', 'name']));

null
{#3176
 +"team_id": 2
 +"name": "Renamed after the move"
}

The scoped query says the project doesn't exist for this user. The component renamed it anyway.

What Filament 5.10 fixes, and what it doesn't

The fix (PR #20616) adds a Livewire component hook. On every request it loads the record again through the resource's own query, scopes included, and returns a 404 if the record is no longer there. This is the hook's skip() method in 5.10.1:

public function skip(): bool
{
    return ! (($this->component instanceof ResourcePage) || ($this->component instanceof EditTenantProfile));
}

Resource pages and the tenant profile page. Nothing else. The advisory says the same: the fix "does not automatically revalidate models passed into separate components, such as relation managers or widgets. Applications must enforce any required scope restrictions when those components access the models."

Here's where that leaves each kind of component after the upgrade:

So after you upgrade, three places still need your attention.

Relation managers need an owner-record check

A relation manager holds its parent in public Model $ownerRecord, so the same restoration happens. Filament 5.10 does add one useful thing here (PR #20587). canViewForRecord() now runs before the relation manager mounts, and again before every later Livewire update. If it returns false, the request gets a 403.

The default implementation only checks viewAny on the related model class. It never asks whether the owner record still belongs to the current tenant. So add that yourself:

use Filament\Facades\Filament;
use Illuminate\Database\Eloquent\Model;

public static function canViewForRecord(Model $ownerRecord, string $pageClass): bool
{
    return $ownerRecord->team_id === Filament::getTenant()?->getKey()
        && parent::canViewForRecord($ownerRecord, $pageClass);
}

Adjust the comparison to however your tenant relationship is named. The point is to check the record you were given, not to trust a query that already ran without your scope.

Widgets have no record in their static check

A widget's canView() is static and receives no record, so it can't do this check. If a widget declares public ?Model $record, verify it in hydrate(). The next section shows that pattern.

Two fixes for your own Livewire components

I ran both against the same scenario. Each one stopped the rename, and the name stayed "Roadmap".

Option 1: keep the key, resolve through the scope on every request. The model never becomes a public property, so Livewire never restores it without scopes:

#[Locked]
public int $projectId;

public function mount(Project $project): void
{
    $this->projectId = $project->id;
}

#[Computed]
public function project(): Project
{
    return Project::findOrFail($this->projectId);
}

After the move, the next request returned 404. findOrFail() runs through the global scope, so the project simply isn't found.

Option 2: keep the model property, check ownership in hydrate(). Livewire calls hydrate() on every request after the first, before any action runs:

public Project $project;

public function hydrate(): void
{
    abort_unless($this->project->team_id === auth()->user()->current_team_id, 403);
}

After the move, the next request returned 403. The restored model carries the fresh team_id from the database, so the check sees the move straight away.

I prefer option 1 for new code. It can't be forgotten in one action, because the scope is the only way to get the model. Option 2 is the smaller change for an existing component.

The same lesson applies to any Livewire public property. What the browser holds between requests is a reference, and the server rebuilds it on its own terms. Authorization belongs in a policy or an explicit check that runs on every request, not in a scope that only ran once.

The multi-panel MFA bypass

This one only affects apps with more than one panel, where the panels use different auth guards and different user models, and email-based MFA is on.

Filament stored the email code and its send rate limit under keys built only from the user's primary key. Two panels share one browser session. So an admin with ID 1 and a customer with ID 1 shared the same MFA state. The advisory explains how an attacker who knows the victim's password and controls a colliding account could use that shared state to pass the victim's email challenge. App-based MFA and single-panel apps aren't affected.

The fix scopes all of this state by guard, user model class and identifier. Filament 5.10 also exposes the helper it uses, which is handy if you've built a custom MFA provider:

use Filament\Facades\Filament;

$principal = Filament::getUserScopedAuthIdentifier($user);

The same mistake is easy to make in your own code. If your app has two guards (say web for customers and admin for staff), any key built from $user->id alone can collide. That covers session keys, cache keys and rate limiter keys. Include the guard and the model class:

use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\RateLimiter;

$guard = Auth::getDefaultDriver();

RateLimiter::attempt(
    'send-code:'.$guard.':'.$user::class.':'.$user->getAuthIdentifier(),
    maxAttempts: 3,
    callback: fn () => $this->sendCode($user),
);

One related detail from the MFA docs. Filament keeps challenge and replay-protection state in your default cache store, and uses an atomic lock when the store supports one. Without lock support, concurrent requests may accept the same code twice. So if you run MFA on more than one server, every server needs the same cache backend, and it should support locks (database and Redis both do).

If you're building a multi-tenant Filament panel with a separate customer panel, this is the combination the advisory describes.

The two XSS fixes

Both are closed by upgrading.

FileUpload kept the client's extension. Filament generated a random file name, but took the extension from the name the browser sent. Validation checks the file's detected MIME type. So a file that passed as an image could be stored as .html. If uploads go to a public disk served from your app's own domain, opening that URL could run JavaScript. The fix switches to Laravel's hashName(), which takes the extension from the detected MIME type instead. This affects v3 as well, which makes it the one fix to backport.

Two things to know. preserveFilenames() still uses the client's file name on purpose, so only use it for trusted uploaders. And files uploaded before you upgrade keep their names. It's worth a quick look for active extensions on your public disk:

find storage/app/public -type f \( -name '*.html' -o -name '*.htm' -o -name '*.svg' -o -name '*.xml' \)

RichEditor trusted pasted block previews. Custom blocks carry a preview in a data-preview attribute. When someone pasted HTML containing a custom block, the editor rendered that preview without sanitizing it. Copying from a malicious page into the editor was enough. The fix regenerates previews on the server instead of trusting the pasted ones.

The upgrade checklist

Check the installed version with composer show filament/filament. Don't rely on composer audit until these advisories reach Packagist.
Upgrade to 5.10.1 or 4.15.1. For v3, upgrade to at least 3.3.56.
Search your relation managers for canViewForRecord(). If records are tenant-scoped, add an ownership check on $ownerRecord.
Search for public ?Model $record and other public model properties in widgets and custom Livewire components. Either resolve them through a scoped query, or check ownership in hydrate().
If you run several panels with email MFA, confirm your cache store supports atomic locks. Then search your own code for session, cache and rate limiter keys built from a user ID alone.
Look for .html, .svg and similar files on the public disk that were uploaded through FileUpload.

If your panel picked up custom widgets and pages over time, step 4 is the one to schedule properly.

FAQ

Which Filament versions are affected by the October 2026 advisories?

All four advisories affect Filament 4.x before 4.15.0 and 5.x before 5.10.0. The FileUpload extension issue also affects 3.x before 3.3.56. The current patch releases are 5.10.1 and 4.15.1.

Why doesn't composer audit report the new Filament advisories?

composer audit uses Packagist's advisory database, which receives GitHub advisories with a delay. On 10 October, the four advisories published on 8 October weren't in it yet. Check your installed version directly until they appear.

Does upgrading to Filament 5.10 fix the tenant scope issue completely?

For resource pages and the tenant profile page, yes. For relation managers, widgets and custom Livewire components, no. The advisory says applications must enforce scope restrictions there themselves.

Do Livewire components apply global scopes when restoring a model property?

No. Livewire restores public model properties with newQueryForRestoration(), which uses newQueryWithoutScopes(). Global scopes run when the page mounts, but not on later requests. Resolve the model through a scoped query, or check ownership in hydrate().

Who is affected by the Filament multi-panel MFA bypass?

Apps with two or more panels that use different auth guards and user models, share a browser session, and have email-based MFA enabled. App-based MFA and single-panel apps aren't affected.

Where the time goes

Steps 1 and 2 take five minutes. Steps 3 and 4 are where the time goes, and they're also the ones no update will do for you.

Laravel AI SDK Skills: Load Agent Instructions Only When They're Needed

Hafiz — Thu, 08 Oct 2026 04:15:08 +0000

Most support agents start with a short instructions() method. Then the refund rules go in. Then the tone guide, then the escalation steps for enterprise customers, then the edge case that bit you last Tuesday. A few months later the agent sends pages of rules with every prompt, and most of them have nothing to do with the email it's answering.

Laravel AI SDK v1.1.0 shipped on October 5 with a fix for exactly that. Agents can now have skills. A skill is a folder of instructions the model loads only when the current task calls for it. Until then, the model sees one line per skill.

I built a small support agent to see how it behaves, with skills from files, from a Blade view, and from the database per team. This post covers what the model actually receives, the three ways to load skills, and a step-limit default that made my first run return an empty reply.

Skills for your app's agents, not your coding agent

If you read my post on the Laravel skills directory, that was about skills for Claude Code and Cursor, the agents that write your code. This is the other side. These skills belong to the agents running inside your application, answering your customers.

The file format is the same. Both follow the open Agent Skills standard, a folder with a SKILL.md file and optional supporting files. The official docs point out that one skill folder can serve both your app's agents and your coding agents. I haven't found a good reason to share them yet, but it works.

If you haven't used the SDK before, start with what the Laravel AI SDK changes. The rest of this post assumes you've built at least one agent.

What the model actually receives

I read the source before writing any code.

When your agent implements HasSkills, the SDK adds one tool to it, LoadSkill. Your skill instructions don't go into the system prompt. Each skill's name and description go into that tool's description instead. Here's the exact text my demo agent sends with every prompt:

Load a skill's instructions before performing a task matching the skill's description. Pass a path to read one of the skill's bundled files instead.

Available skills:
- enterprise-outage: Use when a customer on the Enterprise plan reports that invoices are not sending.
- house-style: Use when writing any reply a customer will read.
- refund-policy: Use when a customer asks for a refund, disputes a charge, or wants to cancel a paid plan.

The tool's name parameter is a JSON schema enum of those three names, so the model can't ask for a skill that doesn't exist. It also has an optional path parameter for reading bundled files.

When the model calls LoadSkill with a name, it gets the body of SKILL.md wrapped in a <skill_content> tag, followed by a list of the files bundled with that skill. If it needs one of those files, it calls the tool again with the path. That's three tiers, and you only pay for the first one on every prompt.

So the description is doing all the routing work. A vague description like "Refund stuff" means the model either loads the skill for everything or never loads it. Write each one as a trigger, starting with "Use when".

Three ways to give an agent skills

The skills() method returns an iterable of sources. Each source is a directory path, a Skill object, or a closure that returns skills. You can mix all three, and my demo does.

1. SKILL.md folders

This is the default and the one you'll use most. Each skill is a folder under resources/skills:

resources/skills/
└── refund-policy/
    ├── SKILL.md
    └── references/
        └── EDGE-CASES.md

The SKILL.md file starts with YAML frontmatter, then the instructions:

---
name: refund-policy
description: Use when a customer asks for a refund, disputes a charge, or wants to cancel a paid plan.
---

# Refund policy

1. Monthly plans: refund the current month in full if the request comes within 7 days of the charge. After 7 days, cancel at period end and refund nothing.
2. Annual plans: refund the unused full months, minus a 10% processing fee.
3. Never promise a refund for a charge older than 60 days. Escalate it to billing@example.com instead.
4. If the customer mentions a chargeback or their bank, read `references/EDGE-CASES.md` before replying.

Rule 4 is the interesting one. The edge cases live in a separate file that the model reads only when a chargeback comes up:

# Refund edge cases

- Open chargeback: do not issue a refund. A refund plus a won chargeback pays the customer twice. Tell them we will match the bank's decision.
- Duplicate charge on the same day: refund the duplicate immediately, no 7-day check.
- Plan downgraded mid-cycle: no partial refund, the credit applies to the next invoice.

If you leave out name, the folder name is used. If you leave out description, the skill is skipped without any warning. I'd add a test that counts your skills, because a typo in the frontmatter makes a skill vanish quietly.

2. Inline skills from a Blade view

Some instructions depend on runtime data. The tone guide in my demo needs the customer-facing brand name, which differs per team. A Skill object takes a name, a description and the instructions, and the instructions can be any Stringable, including a view:

new Skill(
    'house-style',
    'Use when writing any reply a customer will read.',
    view('skills.house-style', ['brand' => $this->team->name]),
),

Write as the {{ $brand }} support team.

- Use the customer's first name once, in the greeting.
- Short paragraphs, no more than three sentences each.
- Never write "unfortunately". State what we can do instead.
- Sign off as "The {{ $brand }} team".

Skill also accepts a files array (filename to contents) if you want bundled files without a folder on disk.

3. Per-team skills from the database

This is the feature I'd build a product around. Let each team write its own skills in your admin panel, store them in a table, and hand them to the agent at run time. No deploy needed when a customer changes their escalation process.

The table is plain:

Schema::create('team_skills', function (Blueprint $table) {
    $table->id();
    $table->foreignId('team_id')->constrained();
    $table->string('name');
    $table->string('description');
    $table->text('instructions');
    $table->timestamps();
});

The model converts itself:

use Laravel\Ai\Skills\Skill;

class TeamSkill extends Model
{
    public function toSkill(): Skill
    {
        return new Skill(
            name: $this->name,
            description: $this->description,
            instructions: $this->instructions,
        );
    }
}

And the agent returns a closure:

fn () => $this->team->skills->map->toSkill(),

Here's the full agent with all three sources:

<?php

namespace App\Ai\Agents;

use App\Models\Team;
use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasSkills;
use Laravel\Ai\Promptable;
use Laravel\Ai\Skills\Skill;

#[MaxSteps(6)]
class SupportAgent implements Agent, HasSkills
{
    use Promptable;

    public function __construct(public Team $team) {}

    public function instructions(): string
    {
        return 'You answer support emails for '.$this->team->name.'. Load a matching skill before you reply.';
    }

    public function skills(): iterable
    {
        return [
            resource_path('skills'),

            new Skill(
                'house-style',
                'Use when writing any reply a customer will read.',
                view('skills.house-style', ['brand' => $this->team->name]),
            ),

            fn () => $this->team->skills->map->toSkill(),
        ];
    }
}

I seeded one team skill, enterprise-outage, for a team called Ledgerly, and created a second team with none. Ledgerly's agent lists three skills. The other team's agent lists two. One agent class serves both teams.

The step limit that ate my first reply

Look at the #[MaxSteps(6)] attribute above. My first run didn't have it, and the agent loaded two skills and then returned an empty string.

The cause is in TextGenerationLoop. Without an explicit MaxSteps, the SDK sets the step budget to 1.5 times the number of tools, rounded and capped at 25. An agent with no tools of its own has exactly one tool, LoadSkill. So round(1 * 1.5) gives it 2 steps.

Loading refund-policy takes one step. Loading house-style takes the second. There's no step left to write the reply. Reading a bundled file costs a step too, so a chargeback email needs at least four.

Set MaxSteps on any agent with skills. Count one step per skill the model might load in a single prompt, one per bundled file it might read, and one for the reply. I use 6 for this agent.

Running it

I wrapped the agent in an Artisan command that listens for the SDK's InvokingTool and ToolInvoked events and prints each call. Here's a real run against OpenAI with the refund email:

The model loads house-style and refund-policy, sees references/EDGE-CASES.md in the file list, and reads it because the email mentions a chargeback. The reply follows the edge case rule. It doesn't promise a refund while the chargeback is open, and it signs off as the Ledgerly team. The order of the first two loads changed between runs, but the third call was there every time.

The enterprise outage email for Ledgerly loaded enterprise-outage and house-style, and the reply included the status page link and the 30-minute promise from the database skill. Nothing about refunds entered that conversation.

Five things I found in the source

The first source wins on a name clash. I gave the second team a database skill called refund-policy to override the file version. The agent kept the file version, with no warning. If you want teams to override defaults, put the closure first in the array.

The closure runs on every prompt. The docs say closures are "only invoked once the agent needs them". In practice the agent needs them on every prompt, because the tool can't list skill names without resolving them. I counted the calls. A prompt that loaded no skill still ran the closure once. Keep that query cheap, and eager load the relation if you build agents in a loop.

Bundled files have limits. Files over 256 KB are refused, and so are files that aren't valid UTF-8. The path is resolved with realpath() and has to stay inside the skill's folder, so ../../.env doesn't work. Good, since the model chooses that path.

You can use LoadSkill without HasSkills. new LoadSkill with no arguments reads resource_path('skills'). If you declare both, the SDK merges your skills into the existing tool and logs a warning. Pick one.

Provider-hosted skills are a separate thing. Anthropic's API can run its own skills in a code container. This feature doesn't touch that. The pull request notes you can still pass Anthropic's container.skills option through provider options.

Should you switch from the community packages?

Before this release, two packages filled the gap, anilcancakir/laravel-ai-sdk-skills and truthanb/laravel-ai-skills. Both use SKILL.md folders under resources/skills, so your skill files should move over without changes.

For new code, use the built-in version. It's maintained with the SDK, so it stays in step with changes to the tool loop.

If you're on truthanb's package, switching is mostly deleting code. Its HasSkills is a trait (Truthanb\LaravelAiSkills\HasSkills) that you wire up by calling skillPrompt() in instructions() and skillTools() in tools(). The SDK's HasSkills is an interface with the same short name, so check your imports when you swap. One behaviour changes too. The package puts skill descriptions in the system prompt, while the SDK puts them in the tool description.

The anilcancakir package is a harder call. It has features the built-in version doesn't, such as a mode that injects full skill content up front, a per-agent allowlist of skills, and helpers that order your prompt for prefix caching. If you rely on any of those, stay on it for now.

Skills, instructions or sub-agents?

Skills don't replace everything else in an agent. This is how I split things now:

Instructions hold what applies to every single prompt. Identity, hard rules, output format. Keep this short.
Skills hold procedures that apply to some prompts. Refund rules, escalation steps, a tone guide for one channel.
Tools do things. Look up an order, issue the refund. A skill can tell the model when to call a tool, and v1.1.0 also lets built-in tools require approval, which pairs well with the setup in my human-in-the-loop tool approval post.
Sub-agents handle work that needs its own model, its own tools or its own context window. If a "skill" needs five tools and a different model, it's a sub-agent.

The trade-off with skills is reliability. The model decides whether to load a skill. In every run I did, about half a dozen, it loaded the right ones for my test emails. But a description that doesn't match the email's wording leaves the model guessing. If a rule must apply every time, it belongs in instructions().

FAQ

Which Laravel AI SDK version added skills?

Version 1.1.0, released October 5, 2026. Run composer require laravel/ai:^1.1. The HasSkills interface, the Skill class and the LoadSkill tool all arrived in that release.

Do skills work with every provider?

Skills work with any provider that supports tool calling, because LoadSkill is an ordinary tool. I tested with OpenAI. The model decides when to call the tool, so test the routing with the exact model you'll run in production.

Do skills reduce token usage?

They reduce what's sent on every prompt to one line per skill, plus the tool definition. A loaded skill costs the same tokens it would in the system prompt, plus one tool round trip. You save the most when you have many skills and each prompt needs one or two.

Can users edit skills without a deploy?

Yes, with the closure source. Store skills in a table, return them from a closure in skills(), and the next prompt picks up the change. Validate the description field in your admin panel. The description is the only thing the model sees before it decides, so a weak one means the skill never loads.

Can I share skills between my app and Claude Code?

The format is the same Agent Skills standard, so a folder like .agents/skills can be read by both. The docs show base_path('.agents/skills') as a source. Keep in mind that a coding skill like "use Pest for tests" is noise for a support agent, so share folders only where the content makes sense for both.

Two settings to get right before production

Set MaxSteps yourself, because the default gives a skills-only agent 2 steps. And write each description as a trigger the model can match, because the description is the only part the model sees until it decides to look.