DEV Community: Hafiz

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.

How I Set Up Encrypted Off-Site Backups for My MacBook With restic and Backblaze B2

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

Earlier this month I finally asked myself a question I'd been avoiding for years. If this MacBook died tonight, what would I lose? The honest answer was everything that wasn't in a git remote. Documents, dotfiles, SSH keys, my notes, a decade of downloads I'd never sorted. My Mac had zero backups. Not a stale one, not an old Time Machine drive in a drawer. Zero.

That's a strange position for a developer who worries about production databases for a living. I'd even written about the risk. When I built my remote dev workstation, a quick check turned up finished work that existed on exactly one machine. I fixed that for code by pushing everything. The laptop itself stayed unprotected, and it's the machine where I let Claude Code run shell commands every day (which is its own risk worth planning for).

So on 24 September I set up restic, Backblaze B2 and Healthchecks.io. The Mac now backs itself up every day, encrypted before anything leaves the machine, and I get an email if it ever stops. This is the third post in the series after the workstation and How I Hardened My VPS in One Afternoon. Same format. The setup, why each piece, the real numbers, and the things that broke.

Why restic and B2, and not the obvious options

I looked at three easier paths first. Each one fails for a specific reason.

Backblaze Personal Backup is the one most people would pick, and it's a good product. It's $9 a month or $99 a year on Backblaze's pricing page, with native Mac and Windows clients. That's the problem. There's no Linux client, and I have three servers that need backing up too. I wanted one system, one bucket and one set of commands for every machine I own, not a consumer app for the laptop and something else for the servers.

iCloud syncs. It doesn't back up. If I delete a folder or a script mangles a file, iCloud copies the mistake to every device as faithfully as it copies my work. It also only covers what lives in iCloud Drive, and my code lives in ~/Sites and ~/side-projects.

An external drive alone sits on the same desk as the laptop. A theft, a fire or a spilled coffee takes both. A local Time Machine copy is still on my list for fast restores and Migration Assistant, but as the second copy, not the only one.

restic splits the job in two. It's the backup program that encrypts, deduplicates and keeps snapshots. B2 is only the storage it writes to. If Backblaze ever raises prices or disappears, I change one environment variable and point restic somewhere else. The passphrase never leaves the Mac, so Backblaze only ever holds ciphertext.

The shape of the setup

Piece	Choice	Why
Backup program	restic 0.19.1 from Homebrew	Client-side encryption, dedup, snapshots, one binary
Storage	Backblaze B2, EU Central (Amsterdam)	Close to Italy, keeps the data in the EU, cheap per GB
Schedule	launchd, daily at 12:30	Runs on wake if the Mac was asleep, unlike cron
Secrets	macOS Keychain	Nothing sensitive in any file
Monitoring	Healthchecks.io, free plan	Emails me when a run fails or never happens
Retention	7 daily, 4 weekly, 12 monthly	About a year of history

The layout is one bucket with one repository per machine, each under its own prefix. Every machine gets its own restic passphrase and its own B2 application key limited to that prefix. A compromised server can't read or delete another machine's backups, because its key can't see them.

The B2 bucket

Setting	Value	Why
Visibility	Private	Obviously
Default encryption	Enabled (SSE-B2)	A second layer on top of restic's, and it's a checkbox
Object Lock	Disabled	With retention set, pruning can't free locked files, and it can't be turned off once enabled
Lifecycle	Keep prior versions 30 days	Deleted objects stay recoverable for a month, then stop costing money
Caps	Storage $0.10/day, download $1/day	About 440 GB stored before uploads block

Object Lock looks like the responsible choice, and for some setups it is. But restic's forget --prune works by deleting old pack files. With a retention period set, locked files can't be deleted until it expires, so pruning can't free them. Since the bucket setting is a one-way switch, I left it off.

restic talks to B2 through its S3-compatible API. The restic docs recommend that over the native B2 backend because of error handling issues in the B2 library. So the repository URL is an S3 one, with the regional endpoint, the bucket, and the machine prefix:

RESTIC_REPOSITORY="s3:https://s3.eu-central-003.backblazeb2.com/your-bucket/macbook"

Secrets live in the Keychain, not in files

The quick way is an env file next to the script with the B2 keys and the repository password in it. I didn't want a plain-text file with credentials that can delete my backups sitting in a folder that gets backed up.

macOS already has an encrypted secret store with a CLI. Four entries, added once:

security add-generic-password -a "$USER" -s restic-b2-key-id -w
security add-generic-password -a "$USER" -s restic-b2-key -w
security add-generic-password -a "$USER" -s restic-password -w
security add-generic-password -a "$USER" -s restic-healthcheck-url -w

With -w at the end and no value, it prompts. The prompt says password data for new item: and it wants the secret itself, not your Mac password. I got that wrong the first time.

The scripts read them back at run time. restic has a RESTIC_PASSWORD_COMMAND variable for exactly this, so the passphrase is never even exported as a plain variable:

secret() { security find-generic-password -s "$1" -w; }

export AWS_ACCESS_KEY_ID="$(secret restic-b2-key-id)"
export AWS_SECRET_ACCESS_KEY="$(secret restic-b2-key)"
export RESTIC_PASSWORD_COMMAND="security find-generic-password -s restic-password -w"

The Keychain holds the working copies. Recovery copies live in a Bitwarden folder, and the restic passphrase is also on paper next to my Bitwarden recovery code. Lose the restic passphrase and the backup can never be decrypted, by anyone. Backblaze can't help you. That's the whole point of client-side encryption.

One more thing to remember. The Keychain isn't in the backup. On a new Mac, those four entries go back in by hand before any restore can happen.

What gets backed up, and what doesn't

Two plain text files drive it. includes.txt lists the folders, one path per line. Trimmed:

# Code
~/Sites
~/side-projects
~/second-brain
~/archives

# Personal files
~/Documents
~/Desktop
~/Downloads
~/Library/Mobile Documents

# Settings, keys and app data
~/.ssh
~/.config
~/.claude
~/.zshrc
~/Library/Preferences
~/Library/Application Support

(The real file uses absolute paths. Library/Mobile Documents is where iCloud Drive keeps its local files.)

excludes.txt is where the savings are. Anything that can be downloaded or rebuilt again stays out:

# Dependencies and build output
node_modules
vendor
dist
.next
.venv

# Laravel runtime files
/Users/you/**/storage/logs
/Users/you/**/storage/framework/cache
/Users/you/**/storage/framework/views

# App caches, at any depth
Cache
Code Cache
GPUCache

Plain names like node_modules match at any depth. The dependency and build folders alone were about 16 GB. Claude's desktop app keeps a vm_bundles folder of 10 GB that it re-downloads anyway. Apps whose data lives in their own cloud (Notion, Slack, Spotify, browsers) are skipped too.

The first run read 26.3 GB across 158,561 files and stored about 16 GB after compression and dedup.

The daily job

launchd runs a script every day at 12:30. I picked launchd over cron for one reason. Apple's scheduling docs say a StartCalendarInterval job that was due while the Mac slept runs when it wakes up. Cron would just skip it. A laptop is asleep a lot.

<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>
    <integer>12</integer>
    <key>Minute</key>
    <integer>30</integer>
</dict>

<!-- Stay out of the way of normal work. -->
<key>Nice</key>
<integer>10</integer>
<key>LowPriorityIO</key>
<true/>

The plist lives in ~/Library/LaunchAgents/ and runs backup.sh. The core of that script is short:

echo -n | ping_hc /start

(
  echo "=== $(date '+%Y-%m-%d %H:%M:%S') backup"
  restic backup \
    --files-from "$DIR/includes.txt" \
    --exclude-file "$DIR/excludes.txt" \
    --exclude-caches
  rc=$?

  # Sundays: drop old snapshots and verify the repository structure.
  if [ "$rc" -eq 0 ] && [ "$(date +%u)" -eq 7 ]; then
    echo "=== prune"
    restic forget --prune --keep-daily 7 --keep-weekly 4 --keep-monthly 12 && restic check
    rc=$?
  fi
  echo "=== exit $rc"
  exit "$rc"
) >"$RUN_LOG" 2>&1
rc=$?

cat "$RUN_LOG" >>"$LOG"

# Exit 0 reports success. Anything else, including 3 (some files unreadable),
# reports failure so the email arrives. The last lines explain why.
tail -n 40 "$RUN_LOG" | ping_hc "/$rc"
exit "$rc"

Where ping_hc is a one-line curl that never fails the script:

ping_hc() { curl -fsS -m 10 --retry 3 --data-binary @- "$PING$1" >/dev/null 2>&1 || true; }

A run takes under a minute, and a day with no changes takes about 15 seconds, because restic only uploads what changed. On Sundays the same run also prunes old snapshots and runs restic check against the repository.

Monitoring with Healthchecks.io

A laptop job fails quietly. The lid stays shut for a week, a plist breaks, a macOS update locks a folder. So the job reports to Healthchecks.io, which is free for up to 20 checks.

The check is called "MacBook backup", with a period of one day and a grace of one day. If no successful ping arrives for about two days, I get an email. That covers the case where the job doesn't run at all, like a broken plist or a Mac that's been off for a week.

The failure path is faster. Healthchecks has an exit status endpoint. Ping /0 and it's a success. Ping any other number and it's a failure. The script sends restic's exit code straight through, with the last 40 lines of the log as the request body. Healthchecks stores up to 100 kB of each ping's body, so the alert email tells me why it failed without opening a terminal.

The /start ping at the top also gives me run durations for free.

The gotchas

All of these cost me time.

B2 blocks uploads at 10 GB until you add a card

B2's first 10 GB are free. What I didn't expect is that a new account without a payment method is hard-capped there. My first backup ran happily until it crossed 10 GB, then every upload failed with storage cap exceeded. That's why the initial upload took two runs.

Adding a card fixes it, but it also flips every cap to "No Cap". So the account that was safely limited a minute ago now has unlimited daily spend. Go straight to Caps & Alerts and set them again by hand. Backblaze emails you at 75% and 100% of each cap, so a runaway script or a leaked key gets noticed within a day.

Exit code 3 is a failure, on purpose

restic's exit codes say code 3 means "backup could not read some source data". The snapshot still gets created. It's just missing whatever couldn't be read.

The first few runs returned 3 constantly, thanks to the next gotcha. The tempting fix is to treat 3 as success so the alerts stop. I did the opposite. Every unreadable path either got fixed or got an explicit line in excludes.txt, and 3 still reports as a failure. So when a macOS update protects some new folder, I get an email instead of a silent hole in my backups that I'd discover during a restore.

macOS privacy folders: exclude them, don't grant Full Disk Access

macOS refuses to let a background job read certain folders. Contacts, Messages, FaceTime, call history, browser profiles. restic logs operation not permitted for each one and exits with 3.

The usual advice is to give Full Disk Access to whatever runs the backup. But launchd runs /bin/bash here, and granting Full Disk Access to bash means granting it to every bash script on the machine. No thanks.

Everything in those folders is already synced somewhere else, mostly iCloud and browser accounts. So I excluded them by path and left the privacy controls alone. iPhone backups also go to iCloud, so MobileSync is out too. And one pleasant surprise. launchd can read Desktop, Documents and Downloads without Full Disk Access. I checked that on macOS 27 before trusting it.

restic ls only shows the top level

My first sanity check was restic ls latest ~/second-brain. It printed a handful of entries and I briefly thought the backup was nearly empty.

It wasn't. The restic docs say it plainly. When filtering by directory, files in subdirectories aren't listed unless you pass --recursive. Add the flag and the whole tree shows up.

restic ls latest ~/second-brain --recursive

A backup you haven't restored from is a guess

Snapshots listed, check passed, Healthchecks green. None of that proves you can get your files back. So on day one I restored a real folder and compared it.

Restoring

Everything manual goes through a small wrapper, restic.sh, which loads the same Keychain secrets and passes its arguments to restic:

R=~/.config/restic/restic.sh
$R snapshots                                   # list backups with dates
$R find "contract.pdf"                         # which snapshots contain a file
$R ls latest ~/Sites/personal --recursive      # browse the latest backup
$R restore latest --include ~/Documents/contract.pdf --target ~/Desktop/restored

Always restore into a separate folder like ~/Desktop/restored, check it, then move files back by hand. A restore never touches current files unless the target is /.

The test restore was second-brain, my notes repo. It came back byte-identical, with its git history intact.

The new-Mac plan is written down too. brew install restic, add the four Keychain entries, copy ~/.config/restic/ back, then restore code and files first. Bring Library settings back one app at a time and only where I actually miss something, because settings from an older macOS can clash with a newer one. Apps aren't in the backup. They get reinstalled.

What it costs

B2 charges $6.95 per TB per month, billed on the average amount stored, and the first 10 GB are always free.

The Mac's repository is about 16 GB. Take off the free 10 GB and that's 6 GB billed, which works out to roughly four cents a month before VAT. The 30-day lifecycle rule keeps pruned data around for a month, so the real number wobbles a little after prune weeks. It's still a rounding error.

Healthchecks.io is free at this scale. restic is free. The only real cost was an afternoon.

Compare that with $9 a month for Backblaze Personal. Personal is simpler and does its job well. But for one laptop plus three servers, one restic setup is both cheaper and the same everywhere.

FAQ

Is restic with Backblaze B2 cheaper than Backblaze Personal Backup?

For a single laptop with a small backup, by a wide margin. B2 bills by storage at $6.95 per TB per month with 10 GB free, while Personal is a flat $9 a month. Personal is unlimited though, so if you have several terabytes on one Mac, run the numbers for your own size.

Does restic need Full Disk Access on macOS?

Not for the usual folders. A launchd job could read Desktop, Documents and Downloads without it on macOS 27. It can't read privacy-protected folders like Messages or Contacts. You can grant Full Disk Access to the binary launchd runs, or exclude those folders if they're synced elsewhere, which is what I did.

Can Backblaze read my restic backups?

No. restic encrypts everything on the Mac before upload, with a passphrase that never leaves it. Backblaze stores ciphertext. That also means nobody can recover the data if you lose the passphrase, so keep an offline copy.

Should I enable Object Lock on a restic bucket?

Only if you've planned for it. Once a retention period is set, Object Lock stops deletions until it expires, which also stops restic's forget --prune from freeing old data. And B2 doesn't let you disable Object Lock on a bucket once it's on. A no-delete application key for machines that shouldn't prune gets you most of the protection with less friction.

How do I know the backup is still running?

Ping a monitoring service at the end of every run with the exit code. Healthchecks.io emails you when it gets a failure or when a success doesn't arrive within the period plus grace. Without that, a backup can stop for months before anyone notices.

What's still open

The servers are next. Production SQLite databases and uploads on three boxes have no backup yet, which is uncomfortable to write down after migrating a live SaaS between them. The plan uses the same bucket with one repository and one key per server. The difference is that server keys won't have delete permission. Pruning needs delete, so it'll run from the Mac, and a compromised server can't wipe its own history. Each server will also run sqlite3 .backup before restic, because copying a live database file can capture it mid-write.

After that, Time Machine on a separate drive for fast local restores. And a restore test every few months, because the day-one test only proves day one.

Squashing Laravel Migrations: 5 Ways schema:dump --prune Bites a Real Team

Hafiz — Wed, 30 Sep 2026 04:15:09 +0000

A recent r/laravel thread was titled "250 migrations in 3 years. What's yours at?" The standard answer is one command:

php artisan schema:dump --prune

It dumps your current schema into database/schema/mysql-schema.sql, deletes your migration files, and from then on a fresh database loads the dump instead of replaying years of history. The docs cover it in five paragraphs. The posts about it mostly date from Laravel 8, when the command shipped, and repeat those paragraphs.

What they don't show is what happens on a team. So I built a small Laravel 13.33 app on MySQL with the kind of history a real app has (a data migration, a foreign key, a column added later), squashed it, and then broke it the ways a team would. Five things went wrong. Most of them fail silently, with a green success message.

What migrate actually does once a dump exists

Every trap below makes sense once you know the rule, so here it is from MigrateCommand. When you run migrate, Laravel checks whether the migrations table has any rows. If it does, the dump is ignored completely and only pending migration files run. If it's empty, Laravel looks for database/schema/{connection}-schema.sql, loads it through your database's command-line client, then runs any migration files the dump doesn't already list as run.

And if that file doesn't exist? It carries on without a word.

The file is picked by connection name, not by driver. And the dump holds your schema plus the rows of the migrations table, nothing else.

Trap 1: --prune deletes migrations you never ran

This is the one that loses work. The --prune flag doesn't compare anything. Here's the implementation in DumpCommand:

(new Filesystem)->deleteDirectory(
    $path = database_path('migrations'), preserve: false
);

It deletes the whole database/migrations directory. The dump, meanwhile, reflects whatever your local database looks like. So if you pulled a teammate's migration this morning and didn't run it yet, the file is gone and it's not in the dump either.

I reproduced it with one pending migration:

$ php artisan migrate:status
  2026_09_26_092550_add_timezone_to_users_table .......... Pending

$ php artisan schema:dump --prune
   INFO  Database schema dumped and pruned successfully.

$ ls database/migrations
ls: database/migrations: No such file or directory

The timezone column isn't in mysql-schema.sql and the file doesn't exist anymore. Git still has it, so you can recover. But only if someone notices, and nothing tells you.

The fix is procedural. Squash on a clean main, run php artisan migrate:status first and make sure nothing is pending, then dump.

Trap 2: teammates who are behind main

Squashing rewrites history that other people are standing on. Two things break.

The first is a teammate whose local database is a migration behind. Say they hadn't run add_archived_at_to_projects_table when you squashed. They pull, run migrate, and get this:

$ php artisan migrate
   INFO  Running migrations.
  2026_09_26_100000_ensure_default_plans_exist ........... DONE

(That migration is the fix from trap 4 below.) No error. Their migrations table has rows, so the dump is skipped, and the file they needed is gone. migrate:status doesn't even list it anymore. The archived_at column simply isn't in their database, and they find out when a query fails.

The second is an open branch that edits a migration you pruned:

$ git merge feature/archive-reason
CONFLICT (modify/delete): database/migrations/2026_01_15_110000_add_archived_at_to_projects_table.php
deleted in HEAD and modified in feature/archive-reason.

That one at least fails loudly. The fix is to move the change into a new migration, never to restore the old file.

The fix for both is coordination, and it's worth being strict about. Announce the squash, get every open branch merged or rebased first, and have everyone run migrate on main before the squash lands. On a solo project none of this matters. On a team of five it's the whole job.

Trap 3: your tests suddenly have no tables

A stock Laravel 13 app runs its tests on SQLite in memory. That's in phpunit.xml out of the box:

<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>

After squashing on MySQL, my test with RefreshDatabase failed on its first query:

SQLSTATE[HY000]: General error: 1 no such table: users
(Connection: sqlite, Database: :memory:, ...)

Follow the rule from earlier. The test connection is named sqlite, so migrate looks for sqlite-schema.sql. It doesn't exist, so Laravel skips it without a word, and there are no migration files left to run. The database stays empty.

You can't point SQLite at the MySQL file either. It's MySQL syntax, backticks and ENGINE=InnoDB included.

The docs do cover this, in one paragraph. If your tests use a different connection, dump a schema for that connection too. Their example uses a connection called testing. With the stock setup it's sqlite, and the dump has to come from a real, migrated SQLite file, which means doing it before you prune. This is what worked for me, run from the last commit before the squash:

touch database/dump.sqlite

DB_CONNECTION=sqlite DB_DATABASE=$PWD/database/dump.sqlite \
    php artisan migrate --force

DB_CONNECTION=sqlite DB_DATABASE=$PWD/database/dump.sqlite \
    php artisan schema:dump --database=sqlite

Override DB_DATABASE inline like that. The default sqlite connection reads DB_DATABASE too, so with your MySQL database name in .env it would otherwise point at a SQLite file called squash_demo.

With sqlite-schema.sql committed next to mysql-schema.sql, the stock test suite passed again. For :memory: databases Laravel loads the file straight through PDO, so you don't need the sqlite3 binary for this.

The cost is that you now have two dumps to regenerate at every future squash. If that bothers you, the other fix is to run your tests on the same engine you run in production. I'd take that trade anyway. SQLite tests passing says little about MySQL behaviour, as my post on Eloquent patterns that silently break MySQL indexes shows. There's more on setting up the test database in the Pest 4 guide.

Trap 4: data migrations disappear

Plenty of apps insert reference data from a migration. Plans, roles, countries. Mine had this:

DB::table('plans')->insert([
    ['slug' => 'starter', 'price_cents' => 900],
    ['slug' => 'pro', 'price_cents' => 2900],
]);

The dump contains CREATE TABLE plans but none of the rows. What it does contain is this line:

INSERT INTO `migrations` (`id`, `migration`, `batch`)
VALUES (5,'2025_03_10_090100_seed_default_plans',1);

So on a fresh database, Laravel loads the empty plans table, reads that the seed migration already ran, and never runs it again. My test on a fresh MySQL test database failed with Attempt to read property "id" on null, because there was no starter plan.

This bites everywhere a database is created fresh. That means CI, a new developer's laptop, a staging rebuild, and every new tenant database if you use database-per-tenant multi-tenancy.

The fix is a new migration, dated after the dump, that restores the rows and is safe to run on databases that already have them:

return new class extends Migration
{
    public function up(): void
    {
        DB::table('plans')->insertOrIgnore([
            ['slug' => 'starter', 'price_cents' => 900],
            ['slug' => 'pro', 'price_cents' => 2900],
        ]);
    }
};

On a fresh database it runs after the dump loads and inserts both rows. On an existing database it runs once and the unique slug index makes it a no-op. I tested both.

My first attempt used upsert() with update: [], meaning "insert, don't touch existing rows". It blew up on the existing database with a duplicate-key error. Look at Builder::upsert() and you'll see why. An empty update array doesn't mean "update nothing". It falls back to a plain insert(). Use insertOrIgnore(), which needs a unique index on the column you match on.

Longer term, reference data belongs in a seeder that tests and new environments call explicitly. But the migration above is what keeps existing deploys and fresh databases in agreement on the day you squash.

Trap 5: CI needs the database client, not just the database

Both halves of this feature shell out. schema:dump runs mysqldump (or pg_dump, or sqlite3), and loading a MySQL dump runs the mysql client with the file piped in. Your CI job can reach the database fine through PDO and still fail the moment migrate hits a dump:

database/schema/mysql-schema.sql ...................... FAIL
The command "mysql --user=... --database=... < ..." failed.
Exit Code: 127(Command not found)

Where this bites depends on the image. GitHub's hosted ubuntu-24.04 runner ships MySQL 8.0, PostgreSQL 16 and sqlite3 clients, according to its image manifest, so the GitHub Actions setup I use is fine as it is. The official php:8.4-cli Docker image ships none of them. I checked. If your CI, or your production container that runs migrate on deploy, is built from a slim PHP image, add the client package before you squash, not after the pipeline goes red.

There's also a version edge. The dump is produced by whatever mysqldump is on the machine that ran it. Mine was a MySQL 9.2 client. Loading it with an older client or server is usually fine for plain DDL, but I didn't test that across versions, so dump with a client that matches production if you can.

The squash, in the order that avoids all five

This is the procedure I'd follow on a team:

Announce it. Get open branches that touch migrations merged first.
On an up-to-date main, run php artisan migrate and check migrate:status shows nothing pending.
If tests run on another connection, generate that dump now, while the files still exist.
Run php artisan schema:dump --prune.
Find every migration that inserted data and add one new insertOrIgnore migration that restores it.
Run the full test suite, then migrate:fresh on a scratch database with the same engine as production.
Make sure CI and your deploy image have the database client.
Commit the dump files and the deletions in one commit. Tell everyone to pull and run migrate.

FAQ

Does schema:dump --prune delete migrations that haven't run?

Yes. It deletes the entire database/migrations directory regardless of what your database has run, and the dump only contains what your database has. Check migrate:status shows nothing pending before you prune.

Why are my tests failing with "no such table" after squashing?

Your tests probably use a different connection, like the stock SQLite :memory: setup. Laravel looks for database/schema/{connection}-schema.sql, silently skips it when it's missing, and there are no migration files left to run. Dump a schema for the test connection before pruning, or run tests on the production engine.

Does the schema dump include seed data?

No. It includes the schema and the rows of the migrations table. Data inserted by migrations is lost on fresh databases, and those migrations are recorded as already run, so they never replay. Restore the rows with a new idempotent migration or move them to a seeder.

Can I roll back past a squashed migration?

No. The pruned migrations and their down() methods are gone, so there's nothing for migrate:rollback to run. Only migrations created after the squash can be rolled back.

Which databases support migration squashing?

MariaDB, MySQL, PostgreSQL and SQLite, according to the Laravel docs. Each uses its command-line client to dump and load. SQL Server isn't supported, and migrate skips schema loading on it entirely.

Should you squash at all?

Squashing buys you a fresh-database path that doesn't replay years of history, and a shorter database/migrations folder. It costs you history in the working tree (git keeps it), rollbacks past the squash point, and the coordination above.

If you're solo or on a small team with no tenant databases and your fresh migrate takes a few seconds, I wouldn't bother. The folder being long isn't a problem that needs solving. If fresh databases get created constantly, in CI, per tenant or per preview environment, and replaying history has become slow or fragile, squash. Do it at a quiet moment, like right after the Laravel 12 to 13 upgrade, and follow the eight steps above in order.

Laravel Mercure Broadcasting: Real-Time Without a WebSocket Server (and 3 Setup Traps)

Hafiz — Mon, 28 Sep 2026 04:15:10 +0000

Laravel 13.32 shipped on September 15 with a Mercure broadcast driver, written by Kévin Dunglas (who also wrote Mercure and FrankenPHP). The pitch is simple. Real-time broadcasting over Server-Sent Events, no WebSocket server to run, and with FrankenPHP you don't even run a separate hub. Your existing ShouldBroadcast events and Echo listeners keep working.

I wanted to see how much of that holds up on a fresh app today. So I built a small ops board with one public channel, one presence channel and one end-to-end encrypted private channel, served by FrankenPHP 1.12.7 with its built-in hub, on Laravel 13.33.

It works. All three channel types, two users, real payloads. But getting there took three fixes that aren't in the docs yet, and one of them breaks every fresh install. This post is the setup that actually worked, the traps in the order you'll hit them, and when Mercure beats Reverb.

What Mercure changes about broadcasting

With Reverb (or Pusher, or Soketi), the browser opens a WebSocket to a long-running server, and that server holds every connection open. For Reverb that's a PHP process you run and supervise alongside your app. I compared those three in Reverb vs Pusher vs Soketi if you want the WebSocket side in depth.

Mercure flips the transport. The browser opens a plain HTTP request using the native EventSource API and the server streams events down it. Laravel publishes an update with one HTTP POST to the hub (or an in-process function call on FrankenPHP), and the hub fans it out. The hub is written in Go and runs inside FrankenPHP's Caddy server, so the open connections live there, not in PHP workers.

Your PHP code never holds a socket.

The traffic is mostly one direction, server to browser. Echo's whispers still work over Mercure, but they're published by the client straight to the hub on their own topics and never touch Laravel. There's no general client-to-server channel like a WebSocket gives you.

Install: one command, one prompt worth reading

The installer gained a --mercure flag in 13.x (PR #61587):

php artisan install:broadcasting --mercure

It asks three questions. Which hub (FrankenPHP's built-in hub or a standalone one), a JWT secret (leave it empty and it generates a 64-character one), and whether to enable end-to-end encrypted channels. Say yes to that last one if you might ever send personal data through a private channel. It just writes a 32-byte key to your .env.

Here's what it changed in my app:

// composer.json
+ "symfony/mercure": "^0.8",
+ "web-token/jwt-library": "^4.1"

// package.json
+ "laravel-echo": "^2.5.0",
+ "pusher-js": "^8.6.0"

BROADCAST_CONNECTION=mercure
MERCURE_JWT_SECRET=652d4c76...
MERCURE_ENCRYPTION_KEY="base64:ZIT5FxQG..."

And resources/js/echo.js:

import Echo from 'laravel-echo';

window.Echo = new Echo({
    broadcaster: 'mercure',
    host: import.meta.env.VITE_MERCURE_HUB_URL,
});

With the built-in hub there's no MERCURE_URL at all. The driver checks for FrankenPHP's mercure_publish() function and publishes in-process. The Echo connector defaults the hub to /.well-known/mercure on the current origin, so the empty VITE_MERCURE_HUB_URL is fine.

The pusher-js dependency isn't needed for Mercure. I removed it and everything below still worked.

The events and channels are ordinary Laravel

Nothing in the app code knows about Mercure. That's the best part of the driver. A public event:

namespace App\Events;

use Illuminate\Broadcasting\Channel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;
use Illuminate\Foundation\Events\Dispatchable;

class DeployStatusUpdated implements ShouldBroadcastNow
{
    use Dispatchable;

    public function __construct(
        public string $app,
        public string $status,
    ) {}

    public function broadcastOn(): Channel
    {
        return new Channel('deploys');
    }
}

An encrypted private one just returns an EncryptedPrivateChannel:

use Illuminate\Broadcasting\EncryptedPrivateChannel;

public function broadcastOn(): EncryptedPrivateChannel
{
    return new EncryptedPrivateChannel('incidents');
}

Channel authorization in routes/channels.php is unchanged. Presence callbacks return the member payload like always:

Broadcast::channel('incidents', function ($user) {
    return $user->email === 'alice@example.com';
});

Broadcast::channel('ops-room', function ($user) {
    return ['id' => $user->id, 'name' => $user->name];
});

On the client, the same Echo calls you'd write for Reverb:

Echo.join('ops-room')
    .here(users => { /* seed the list */ })
    .joining(user => { /* add */ })
    .leaving(user => { /* remove */ });

Echo.channel('deploys')
    .listen('DeployStatusUpdated', e => console.log(e.app, e.status));

Echo.encryptedPrivate('incidents')
    .listen('IncidentOpened', e => console.log(e.summary));

Notice I used ShouldBroadcastNow. Keep that in mind for trap three.

Trap 1: the Echo release doesn't have the connector yet

I built the assets, logged in, and got this in the console:

Broadcaster string mercure is not supported.

The installer pins laravel-echo to ^2.5.0, and 2.5.0 is the latest release on npm. It was published on September 8. The Mercure connector (laravel/echo#549) was merged into the 2.x branch on September 10. As I write this there's no Echo release that contains it.

So a fresh install:broadcasting --mercure today gives you a working backend and a frontend that can't connect. Dunglas's own demo app sidesteps this by building Echo from source, and that's what I did too:

git clone -b 2.x https://github.com/laravel/echo.git
cd echo && pnpm install
cd packages/laravel-echo && pnpm run build

# back in your app
npm install -D ../echo/packages/laravel-echo

Check npm view laravel-echo version before you do this. Once a release after 2.5.0 lands, a plain npm update laravel-echo is the fix and this whole section goes away.

Once it loads, one EventSource carries every channel you join. Joins and leaves are batched into a single re-auth. Authorization goes through the usual /broadcasting/auth route, which answers with an httpOnly cookie the hub reads, and there's no client library to install beyond Echo.

Trap 2: the Caddyfile in most examples no longer starts

FrankenPHP's Mercure docs show the hub configured with publisher_jwt and subscriber_jwt. On FrankenPHP 1.12.7 that config refuses to boot:

the "publisher_jwt", "subscriber_jwt", "publisher_jwks_url" and
"subscriber_jwks_url" directives work only in compatibility mode,
which relaxes access-token validation: move them into an "issuer"
block for modern mode, or set "protocol_version_compatibility 8"

The bundled hub now speaks the Mercure 1.0 protocol, which switched to standard OAuth 2.0 access tokens with a required issuer (the Mercure 1.0 upgrade guide covers the full change). Laravel's driver already signs tokens for 1.0, so don't reach for compatibility mode. Use an issuer block instead.

The issuer has to match the iss claim Laravel puts in its tokens. Unless you set MERCURE_JWT_ISSUER, the driver uses your APP_URL. Here's the Caddyfile, with the mercure block exactly as I tested it:

{
    frankenphp
}

your-app.com {
    root public/
    encode zstd br gzip

    mercure {
        issuer {$APP_URL} {
            publisher {
                jwt {$MERCURE_JWT_SECRET}
            }
            subscriber {
                jwt {$MERCURE_JWT_SECRET}
            }
        }
        anonymous
        subscriptions
    }

    php_server
}

(Locally I served it on localhost:8443, because ports 80 and 443 were already taken on my machine. That needed three extra global options, http_port 8080, auto_https disable_redirects and skip_install_trust. On a server with a real domain you don't need any of them.)

anonymous lets browsers subscribe to public channels without a token. subscriptions turns on the hub's subscription events, and presence channels are built on those.

And one thing cost me a restart. My first attempt used {env.APP_URL}, which is how Caddy writes environment placeholders in a lot of places. Every subscribe then failed with a 401, and the hub log said:

invalid JWT: untrusted issuer "https://localhost:8443"

The issuer and the token were identical. The problem is that {env.APP_URL} is a runtime placeholder, and the issuer name never gets expanded. Running frankenphp adapt showed the issuer stored as the literal string {env.APP_URL}. The parse-time form {$APP_URL} gets substituted when the Caddyfile loads. Export APP_URL and MERCURE_JWT_SECRET into the environment before starting FrankenPHP, since Caddy doesn't read your .env.

With both fixes in, this is two real browser sessions after one deploy event and one incident event:

Presence, public and encrypted private channels all working over one SSE connection per tab.

What actually goes over the wire

A public event on the SSE stream looks like this (captured with curl -N against the hub):

id: urn:uuid:01a0dce5-f4aa-75db-a1dd-24a7f86f65d1
data: {"channels":["deploys"],"event":"App\\Events\\DeployStatusUpdated","payload":{"app":"billing-api","status":"deployed"}}

The encrypted incident, as Alice's browser received it:

data: {"channels":["private-encrypted-incidents"],"data":"eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..avbjUXGvrdWNg-wJ.jKSQWcU_YfBk..."}

That's a compact JWE. The event name and the customer email are both inside the ciphertext. Per the driver PR, each channel gets its own AES-256-GCM key derived with HKDF from your MERCURE_ENCRYPTION_KEY, the auth endpoint hands the key to authorized browsers, and the browser decrypts with WebCrypto. The hub only ever relays ciphertext. If you run a shared or third-party hub, that's a real guarantee.

Topics are namespaced too. Every channel becomes a topic under https://laravel.alt/echo/, a deliberately non-resolvable .alt URL, so two apps on one hub don't collide. Change it with topic_prefix if you share a hub between environments.

Trap 3: queue workers can't use the built-in hub

This one catches you twice.

First, the moment BROADCAST_CONNECTION=mercure points at the built-in hub, plain php artisan commands fail to boot. Even migrate:

Failed to create broadcaster for connection "mercure" with error:
The Mercure broadcasting connection requires a "url" configuration
value, unless the application is served by FrankenPHP with its
built-in Mercure hub enabled.

Loading routes/channels.php resolves the broadcaster, and mercure_publish() only exists inside the running FrankenPHP server. Not in the PHP CLI, and not in frankenphp php-cli either (I checked).

Second, and more important in production. A plain ShouldBroadcast event is queued, and queue workers are CLI processes. So the zero-config built-in hub only covers ShouldBroadcastNow events dispatched during a web request. Everything your workers broadcast would fail.

The fix is to give the driver a URL. When MERCURE_URL is set, it stops calling mercure_publish() and publishes over HTTP with a signed JWT, which works from anywhere:

MERCURE_URL=https://your-app.com/.well-known/mercure
MERCURE_PUBLIC_URL=https://your-app.com/.well-known/mercure

I tested this from the CLI against the same FrankenPHP hub, with a curl -N subscriber open. The event arrived just like the in-process one. The trade-off is that web requests now make an HTTP call too, instead of the in-process publish. For almost every app that cost is noise next to a working queue. If your broadcasts go through queued jobs at any volume, set the URL from day one.

FAQ

Do I need FrankenPHP to use the Laravel Mercure driver?

No. Set MERCURE_URL and MERCURE_PUBLIC_URL to any Mercure hub, including the standalone dunglas/mercure binary or Docker image (it needs to speak the 1.0 protocol), and the driver publishes over HTTP. FrankenPHP just removes the separate hub and adds an in-process publish path for web requests.

Does Laravel Echo support Mercure?

The connector is merged into Echo's 2.x branch but, as of September 26, 2026, not in any npm release. The latest release, 2.5.0, rejects broadcaster: 'mercure'. Build it from the 2.x branch until a newer version ships.

Do presence channels work over Mercure?

Yes. They rely on the hub's subscription events, so the hub needs the subscriptions directive. Echo seeds the member list from the hub's subscription API, then updates it live as users join and leave.

Can I use whispers and client events with Mercure?

Yes, client_events is on by default. Whispers are published by the browser directly to the hub on dedicated per-channel topics, and the grant never covers the channel's own topic, so a member can't forge a server event.

Why do my artisan commands fail after switching to Mercure?

With the built-in FrankenPHP hub and no MERCURE_URL, the driver needs mercure_publish(), which only exists inside the FrankenPHP server. Set MERCURE_URL so the CLI and queue workers publish over HTTP.

Mercure or Reverb?

Both drivers sit behind the same Laravel API, so this is an infrastructure decision, not a code decision. Switching later means changing BROADCAST_CONNECTION and the Echo config. (If you're still building your first real-time feature, my notifications walkthrough covers the event side, and it applies unchanged to either driver.)

Pick Mercure when:

You already serve the app with FrankenPHP (including Octane on FrankenPHP). The hub is already in the binary. There's no extra process to supervise, and no extra port to open.
Your real-time traffic is mostly server to browser. Notifications, dashboards, status updates, "someone else is editing this".
You want end-to-end encryption for private channels that a hub operator can't read.
Your network or proxy is unfriendly to WebSockets. SSE is plain HTTP.

Stay with Reverb when:

You need heavy client-to-server messaging. Multiplayer state, collaborative cursors, chat with high message rates.
You run PHP-FPM behind Nginx and have no plans to move. Then Mercure means running a standalone hub anyway, and Reverb is the better-trodden path in Laravel. It has more tutorials, more production mileage and a released Echo connector.
You need it working today without building a JavaScript package from source.

My take? For a new app on FrankenPHP, Mercure is the better default once Echo cuts a release. One binary serves PHP, TLS and real-time, the connections never touch your PHP workers, and encrypted channels come almost for free. For an existing Reverb setup there's no reason to migrate. It's the same ShouldBroadcast code either way, so move when your infrastructure moves, not before. And if you do pick Mercure, set MERCURE_URL before your first queued broadcast, not after the first failed job.

Migrate Laravel Uploads From Local Disk to S3 With Zero Downtime: Read-Through Disks and moveToDisk

Hafiz — Thu, 24 Sep 2026 04:15:07 +0000

Every storage migration has the same shape. New uploads need to start landing in the new bucket now. The old files need to move over at some point. And for the whole time in between, a request for avatars/42.jpg has to work whether that file has moved yet or not.

Until this summer, Laravel gave you no help with the middle part. You either took a maintenance window, copied everything, flipped the config and hoped, or you wrote a two-disk lookup into every controller that touched a file. Both work. Both are worse than what 13.26 gives you.

Laravel 13.26 shipped a read-through filesystem driver that handles both disks behind one disk name. Laravel 13.32 added copyToDisk() and moveToDisk(), which are the primitives you want for the sweep at the end. Together they make the migration a config change plus one Artisan command.

This is the runbook I would follow to move a Laravel app's uploads from the local disk to S3, tested on 13.32 with 2,000 files, plus the six behaviours I verified against the framework source because the early write-ups disagreed on one of them.

What a read-through disk actually does

You define one disk that sits on top of two ordinary disks:

// config/filesystems.php
'disks' => [
    'local-legacy' => [
        'driver' => 'local',
        'root' => storage_path('app/private'),
        'throw' => true,
    ],

    's3' => [
        'driver' => 's3',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION'),
        'bucket' => env('AWS_BUCKET'),
        'throw' => true,
    ],

    'uploads' => [
        'driver' => 'read-through',
        'primary' => 's3',
        'fallback' => 'local-legacy',
    ],
],

primary is where you are going. fallback is where you are. Both can be disk names or inline config arrays. Then every operation your app performs on uploads gets routed on purpose. I ran each of these against 13.32 with two local disks standing in for old and new, so this is what the code does, not what the docs promise:

Call on the read-through disk	Which disk	Copies the file to primary?
`get()`, `readStream()`	Primary, then fallback on a miss	Yes, once, on the fallback hit
`exists()`, `size()`, `mimeType()`, `lastModified()`	Primary, then fallback	No
`put()`, `putFile()`, `writeStream()`	Primary only	Not applicable
`files()`, `allFiles()`, `directories()`	Primary only	No
`delete()`, `deleteDirectory()`	Fallback first, then primary	No
`url()`, `temporaryUrl()`	Whichever disk holds the file	No

The copy on first read is called promotion. It is a copy, not a move. After my first get() the file existed on both disks. It is also once: the adapter checks primary again after reading fallback, and if another request promoted the file in the meantime it discards what it read and uses the primary copy.

The row that surprised me is delete(). The Laravel News write-up from the 13.26 release says deletes only touch the primary, so a delete() followed by exists() could return true. On 13.32 that is not what happens. ReadThroughFilesystemAdapter::delete() removes the fallback copy first, then the primary one, and my test confirmed the file was gone from both. Aaron Francis's engineering post on laravel.com describes the same both-disks behaviour. Trust the source over the summary, and check your own version.

Two config options matter. 'copy' => false turns promotion off, so the disk becomes a pure two-disk reader. That is useful for a staging environment pointed at production's old bucket, where you want reads to work but must not write anything. And 'throw_on_promotion_failure' => true makes a failed copy fail the read as UnableToReadFile, instead of the default where the read succeeds and the promotion quietly retries next time. Default is right for production, strict is right for tests.

The runbook

Seven steps. The first three take an afternoon, the fourth runs in the background for as long as it needs, and the last three are a deploy each.

1. Create the destination disk and prove it works

Add the s3 disk (or R2, or anything S3-compatible via AWS_ENDPOINT) and write one file to it from Tinker on production. Not staging. Credentials, bucket policy and region mistakes all surface here, where they cost nothing.

Storage::disk('s3')->put('migration-check.txt', now()->toIso8601String());
Storage::disk('s3')->get('migration-check.txt');
Storage::disk('s3')->delete('migration-check.txt');

Keep the same paths on both disks. The read-through driver looks up the identical path on fallback, so if your old disk has avatars/42.jpg the new one must too. If you also want to reorganise paths, do it as a second migration with scoped disks later, not now.

2. Rename, insert, deploy

This is the zero-downtime trick. Your application code refers to a disk by name, usually local through FILESYSTEM_DISK or an explicit Storage::disk('uploads'). Do not change the code. Rename the old disk config to local-legacy, and give the read-through disk the name your code already uses.

'uploads' => [
    'driver' => 'read-through',
    'primary' => 's3',
    'fallback' => 'local-legacy',
],

Deploy. From this request onwards new uploads land in S3, old files are still served from local, and nothing in app/ changed. If you use the public disk with php artisan storage:link, the same rename applies to public, with one caveat about URLs I will get to below.

3. Let traffic promote the hot set

Do nothing for a day or a week. Every file a user actually opens gets copied to S3 on its first read and served from S3 after that. In my test I seeded 2,000 files on the old disk and simulated traffic by reading 300 of them through the read-through disk. Afterwards S3 (well, my stand-in disk) held exactly those 300 and the old disk still held all 2,000.

Watch two things during this phase. Memory, because get() loads the whole file into a string before promoting it. For anything large, your code should already be using readStream(), which promotes through a php://temp buffer that spills to disk above 2 MiB. And latency, because the first read of a cold file now includes a download from old and an upload to new. For a 5 MB PDF that is noticeable. For avatars nobody will see it.

4. Sweep the cold tail

Traffic never touches everything. The files nobody has opened in a year are still on the old disk, and they need moving before you can retire it. This is where 13.32's moveToDisk() earns its place:

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Number;
use League\Flysystem\StorageAttributes;

class SweepStorage extends Command
{
    protected $signature = 'storage:sweep {from} {to} {--prefix=} {--dry-run}';

    protected $description = 'Move every file left on the old disk onto the new one, skipping anything already there';

    public function handle(): int
    {
        $from = Storage::disk($this->argument('from'));
        $to = Storage::disk($this->argument('to'));
        $moved = $skipped = $failed = $bytes = 0;

        // listContents() is lazy: S3 pages through the bucket instead of
        // loading every key into one array the way allFiles() does.
        $listing = $from->getDriver()
            ->listContents($this->option('prefix') ?? '', deep: true)
            ->filter(fn (StorageAttributes $item) => $item->isFile());

        foreach ($listing as $item) {
            $path = $item->path();

            if ($to->exists($path)) {
                $skipped++;  // promoted already, or uploaded after cutover

                continue;
            }

            if ($this->option('dry-run')) {
                $moved++;
                $bytes += $item->fileSize() ?? 0;

                continue;
            }

            if ($from->moveToDisk($to, $path)) {
                $moved++;
                $bytes += $item->fileSize() ?? 0;
            } else {
                $failed++;
                $this->warn("failed: $path");
            }
        }

        $this->info(sprintf(
            '%s %d files (%s), skipped %d already on %s, %d failed',
            $this->option('dry-run') ? 'Would move' : 'Moved',
            $moved,
            Number::fileSize($bytes),
            $skipped,
            $this->argument('to'),
            $failed,
        ));

        return $failed === 0 ? self::SUCCESS : self::FAILURE;
    }
}

Three decisions in there are worth defending.

listContents() on the Flysystem driver instead of allFiles(). allFiles() returns an array, and on a bucket with a million keys that is a million strings in PHP memory before you move anything. listContents(deep: true) returns a DirectoryListing that iterates lazily, so S3 pages through the bucket 1,000 keys at a time.

The exists() check on the destination before every move. It costs one HEAD request per file, and it is the line that makes the sweep safe to run while the app is live. A file already on primary is either one that traffic promoted or one that was uploaded after cutover. Either way the primary copy is the truth, and the sweep must not overwrite it with a stale fallback version.

moveToDisk() rather than copyToDisk(). Under the hood it is copyToDisk() followed by delete() on the source, streamed, so the old disk empties as the sweep progresses and you can watch the numbers converge. The method also accepts a disk instance instead of a name since 13.32, which is why $to can be passed straight in.

Here is the command against my 2,000-file test, after traffic had promoted 300:

$ php artisan storage:sweep local-legacy s3 --prefix=avatars --dry-run
Would move 1700 files (3 MB), skipped 300 already on s3, 0 failed

$ php artisan storage:sweep local-legacy s3 --prefix=avatars
Moved 1700 files (3 MB), skipped 300 already on s3, 0 failed

$ php artisan storage:sweep local-legacy s3 --prefix=avatars
Moved 0 files (0 B), skipped 300 already on s3, 0 failed

The dry run first, always. Then the real run. Then the run that proves nothing is left to move. The second zero is the number you want before step 6.

Against real S3 the sweep is bounded by network, not PHP, so run it under nohup or as a queued job per prefix, with a generous timeout. The queue setup from the 10,000-jobs post applies unchanged: one job per top-level directory, low concurrency, and retries that are safe because the exists() check makes every move idempotent.

5. Verify

Counts are the weak signal. allFiles() on both disks and compare lengths, or better, a lazy listing of the old disk that checks size() on the new one for every path. For anything where corruption would matter, compare checksums on a sample. The laravel.com post is honest that object counts alone are not proof, and I agree.

Then wait. A week of the read-through disk with an empty old disk behind it costs you nothing and tells you whether any code path was still writing to local-legacy directly.

6. Cut over

Point the disk name straight at S3 and drop the read-through config:

'uploads' => [
    'driver' => 's3',
    // ...
],

Deploy. Same trick as step 2: the application code never changed, only what the name resolves to.

7. Retire the old disk

Not before step 6, and not the moment after. The old disk is your rollback for as long as it exists. When you do retire it, delete it wholesale rather than file by file, and here is why.

After my sweep the old disk was not empty. It still held 300 files. Those were the ones traffic had promoted in step 3, because promotion copies and never deletes, and the sweep skipped them because they already existed on the new disk. That is the correct behaviour. It means the old disk is a complete, untouched fallback right up until you decide it is not. It also means "the sweep reported 0 moved" and "the old disk is empty" are different statements. Check the one you mean.

The gotchas I verified

URLs follow the file. Storage::disk('uploads')->url($path) asks whichever disk currently holds the file, so during the migration a page can render one avatar as /storage/avatars/1.jpg and the next as https://bucket.s3.amazonaws.com/avatars/2.jpg. For private files behind a controller that is invisible. For the public disk it is not, and it gets worse: files served straight from /storage/ through the symlink never pass through PHP, so they never promote. If your public uploads are served by nginx, run the sweep for that prefix in step 3, not step 4, so the URLs flip once.

Writes to the old disk after promotion are invisible. I promoted a file, then wrote a new version straight to the old disk. The read-through disk kept returning the old content, because primary had it and primary wins. Nothing should write to the fallback after cutover. If a cron job or a second app still does, find it before step 2.

Overwrites race. If your app overwrites paths in place (a profile.jpg that gets replaced), a put() can land between the promotion's existence check and its write, and the promotion then overwrites the fresh upload with the stale fallback bytes. Immutable, versioned filenames avoid it entirely. If you cannot change the naming, pause overwrites during the migration or sweep those prefixes first.

Deletes need delete permission on the old disk. Because delete() hits fallback first, a read-only credential on the old bucket fails the whole delete, and the primary copy survives. Either give the migration credential delete rights, or defer deletions until the fallback is gone.

Metadata does not travel. Promotion goes through Flysystem's generic write, so cache headers, content disposition and custom S3 metadata come from the new disk's defaults, not from the old object. If you serve files directly from S3 with tuned headers, audit them after the sweep.

Egress costs money once. Moving from local to S3 costs you S3 PUT requests and nothing else. Moving from S3 to R2 costs AWS transfer-out per gigabyte. The laravel.com post has the current rate table and it is the right place to look, because it will be updated and this post will not.

Why this beats the alternatives

The old way, a maintenance page plus aws s3 sync, still works and is simpler to reason about. It costs you downtime proportional to your data, and every minute of that window is a minute you cannot test whether the new disk actually works under real traffic. When I moved a live SaaS to a new server, the storage delta rode inside the same two-minute window as the database snapshot, because there was no way to move files with the site up. This is that way.

Cloudflare's Sippy does the same on-demand promotion at the R2 layer and catches requests that bypass Laravel entirely. If you are moving to R2 and serve files directly from the bucket, it is the better tool for step 3. The read-through disk wins when your files go through PHP anyway, when the source is a local disk that no external service can read, and when you want the migration visible in your own logs and tests rather than in a Cloudflare dashboard.

FAQ

Which Laravel version do I need for read-through disks?

The read-through driver landed in Laravel 13.26.0 (18 August 2026, framework PR #61140), with the copy => false option in the same release. Fallback-aware move() and copy() came in 13.27.0, visibility handling for fallback-only files in 13.30.0, and copyToDisk() / moveToDisk() in 13.32.0 (15 September 2026). Run 13.32 or later for everything in this post.

Does a read-through disk slow down every request?

Reads that hit primary cost one extra exists() check compared to a plain disk. Reads that miss cost an existence check on both disks, a read from fallback, a second primary check and a write. That happens once per file. Writes, listings and deletes on primary are unchanged. Metadata calls like exists() and size() never trigger a copy.

Can I use it to move between two S3-compatible buckets, or between prefixes?

Yes. Both primary and fallback can be any configured disk, including two S3 disks with different endpoints, or two scoped disks with different prefixes on the same bucket. The one requirement is that both adapters support existence checks and reads, and primary supports writes.

Does moveToDisk stream, or load the file into memory?

It streams. copyToDisk() opens a readStream() on the source and passes it to writeStream() on the destination, and moveToDisk() is that followed by delete() on the source. Memory use stays flat regardless of file size, which is what you want for a sweep over gigabytes.

What if the copy to S3 fails during a promotion?

By default the read still returns the file from the fallback, the file stays where it was, and the next read tries again. Nothing is logged, so a persistently failing promotion is silent. Set throw_on_promotion_failure => true (together with the disk's throw => true) if you would rather see the failure as an UnableToReadFile exception.

What to take away

Two disks, one name, and a sweep that is safe to rerun. The read-through driver moves the files people actually use, moveToDisk() moves the rest, and the exists() check in between is the whole reason you can do it with the site up. Keep the old disk until the second sweep reports zero and a week has passed. Then delete it in one go, promoted copies and all.

Jev Gives Your Laravel App a Probability. Here Is What to Do When It Says 0.69

Hafiz — Mon, 21 Sep 2026 04:15:08 +0000

TypeSafe released Jev on 15 September 2026. Two days later the Laravel AI SDK grew a Classification API on its 1.x branch, with TypeSafe as the first provider. Freek already used it to kill a hand-maintained spam list, and the PR's own example routes support tickets. Both stop at the same line: $response['department']->choice.

That is the boring number. The interesting one sits next to it. A customer asks "can we pay by bank transfer instead of card before we sign up for the annual plan". Jev says billing with a confidence of 0.69, and sales is the runner-up at 0.23. What does your code do now?

The obvious code does nothing. It reads ->choice, routes the ticket, and the 0.69 evaporates. Which means you paid for a model that can say "I'm not sure" and then built a system that cannot hear it.

This post builds the missing half. A threshold policy that treats confidence as a per-action decision. A review queue in Filament for the calls the model should not make alone. A write-back so the truth lands next to the guess. And an Artisan command that turns "calibrated" from a marketing word into a table you can read. All of it against 60 real-looking support tickets I wrote and labelled by hand, so the numbers at the end are measured, not imagined.

What the Classification API actually returns

First the ground rules, because they shape everything after. Classification is on the 1.x branch only, so you install a dev version:

composer require laravel/ai:1.x-dev
php artisan vendor:publish --tag=ai-config

Stable is v0.11.2 at the time of writing, and 1.x has an upgrade guide branch open, so a 1.0 tag is close. The docs on laravel.com do not mention Classification yet. The PR author also said the API may be flagged experimental after release. Every code block here ran against commit ca8d9bf of 1.x on Laravel 13.32. If a method is renamed before you read this, the source under vendor/laravel/ai/src/Classification is short enough to diff in a minute.

Config is one key. config/ai.php already carries 'default_for_classification' => 'typesafe' and a typesafe provider reading TYPESAFE_API_KEY. The default model is jev-latest.

There are three question types, and they return three different answer objects:

use Laravel\Ai\Classification;
use Laravel\Ai\Classification\Boolean;
use Laravel\Ai\Classification\Choice;
use Laravel\Ai\Classification\Score;

$response = Classification::of([
    'subject' => $ticket->subject,
    'body' => $ticket->body,
])->questions([
    'department' => new Choice('Which team should handle this ticket?', [
        'billing' => 'Invoices, failed payments, plan changes, VAT',
        'technical' => 'Bugs, errors, integrations, API problems',
        'sales' => 'Pricing questions, quotes, trials, upgrades before buying',
        'refund' => 'The customer is asking for money back',
    ]),
    'urgent' => new Boolean('Does the customer need a response today?'),
    'frustration' => new Score('How frustrated is the customer?', [
        'Calm, stating facts',
        'Annoyed but polite',
        'Angry or threatening to leave',
    ]),
])->classify();

// Real answers for the bank transfer ticket from the intro
$response['department']->choice;         // 'billing'
$response['department']->confidence;     // 0.69
$response['department']->probabilities;  // ['billing' => 0.77, 'sales' => 0.23, 'technical' => 0, 'refund' => 0]
$response['urgent']->probability;        // 0.34
$response['urgent']->isTrue(0.7);        // false
$response['frustration']->level();       // 0
$response['frustration']->label();       // 'Calm, stating facts'
$response->meta->model;                  // 'jev-1.13.0'
$response->usage->inputTokens;           // 478

Two details matter for the rest of the post.

Boolean answers carry a probability and nothing else. There is no confidence property on BooleanAnswer, because for a yes/no question the probability already is the certainty. 0.5 means the model has no idea, 0.99 or 0.01 means it does.

Choice and Score answers carry both. The probabilities array is the real output, and confidence is a single number TypeSafe derives from its shape. Their confidence docs put it plainly: a distribution concentrated on one option is a confident answer, a flat one is not. It is not the same as the top probability. One ticket in my run came back billing at 0.84 with a confidence of 0.78, because the remaining 0.16 sat on a single rival option rather than being spread thin. And the SDK types confidence as ?float, so a future provider that cannot measure it returns null. Your policy has to handle that case from day one.

The other line worth pinning on the wall comes from the System One page. Calibration is measured across groups of predictions, and in their words "it does not guarantee that an individual answer is correct." So a 0.69 does not mean this ticket is 69% billing. It means that across many answers where Jev said 0.69, roughly 69% should turn out right. That is a statement about your whole queue, and you can only check it if you keep records. Hold that thought.

A threshold is a policy, not a number

The naive version is if ($answer->confidence >= 0.8). It fails the first time a refund request auto-routes to billing and sits there for two days. Misrouting a pricing question costs a forwarded email. Misrouting a refund costs a chargeback. The same confidence should not be allowed to do both.

TypeSafe's own docs suggest three ranges (act, proceed with caution, do not act) and note that the boundaries move with the stakes. Here is what that looks like as a Laravel class:

namespace App\Support;

use Laravel\Ai\Responses\Data\ChoiceAnswer;

final class ConfidencePolicy
{
    /**
     * @param  float  $floor  Below this the model is guessing. Never act.
     * @param  array<string, float>  $actAt  Per-option threshold to act without a human.
     */
    public function __construct(
        private float $floor = 0.5,
        private array $actAt = [
            'billing' => 0.75,
            'technical' => 0.75,
            'sales' => 0.75,
            'refund' => 0.9,   // money leaves the building, so the bar is higher
        ],
    ) {}

    public function decide(ChoiceAnswer $answer): Decision
    {
        if ($answer->confidence === null || $answer->confidence < $this->floor) {
            return Decision::Review;
        }

        $threshold = $this->actAt[$answer->choice] ?? 1.0;

        return $answer->confidence >= $threshold ? Decision::Act : Decision::Review;
    }
}

Decision is a two-case enum, Act and Review. Three things are deliberate here. A null confidence goes to review, not to a default threshold. An option missing from $actAt gets a threshold of 1.0, so adding a fifth department to the Choice without adding a threshold fails safe. And the numbers are constructor arguments, so a test can pass a strict policy and a lenient one without touching config.

The 0.69 from the intro hits the floor check, passes it, then fails billing's 0.75. Review. Which is the right answer for a sales question wearing billing vocabulary. The customer has not bought anything yet. (Running the same ticket again a minute later gave 0.70. Jev is not perfectly deterministic, so a policy that flips on the second decimal is a policy with a bad threshold.)

The action that ties it together is short. It classifies, decides, records, and only touches the ticket when the policy says so:

namespace App\Actions;

class RouteTicket
{
    public function __construct(private ConfidencePolicy $policy) {}

    public function handle(Ticket $ticket): ClassificationDecision
    {
        $started = hrtime(true);

        $response = Classification::of([...])->questions([...])->classify();

        $department = $response['department'];
        $decision = $this->policy->decide($department);

        $record = $ticket->decisions()->create([
            'question' => 'department',
            'suggested' => $department->choice,
            'confidence' => $department->confidence,
            'probabilities' => $department->probabilities,
            'decision' => $decision->value,
            'model' => $response->meta->model,
            'input_tokens' => $response->usage->inputTokens,
            'latency_ms' => (int) ((hrtime(true) - $started) / 1_000_000),
        ]);

        if ($decision === Decision::Act) {
            $ticket->update(['department' => $department->choice, 'routed_by' => 'model']);
        }

        return $record;
    }
}

Every call writes a classification_decisions row, whether the model acted or not. That table is the audit log, and it is the input to everything below. If you already run Spatie's activity log, you could log there instead, but a dedicated table with typed columns for confidence and suggested makes the calibration query at the end a plain where, not a JSON path.

The review queue is the other half of automation

A decision of Review has to land somewhere a human will actually look. In my apps that is Filament, so the queue is a resource over the same classification_decisions table, filtered to what the model was unsure about and nobody has resolved:

public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()
        ->where('decision', 'review')
        ->whereNull('actual')
        ->with('ticket')
        ->orderBy('confidence');
}

public static function getNavigationBadge(): ?string
{
    return (string) static::getEloquentQuery()->count();
}

Lowest confidence first, because those are the ones where the runner-up is most likely right. The badge on the sidebar is the whole "someone must work this queue" problem made visible. Two row actions do the work:

->recordActions([
    Action::make('accept')
        ->icon(Heroicon::Check)
        ->color('success')
        ->action(fn (ClassificationDecision $record) => static::resolve($record, $record->suggested)),
    Action::make('override')
        ->icon(Heroicon::ArrowUturnLeft)
        ->color('gray')
        ->schema([
            Radio::make('department')
                ->options(fn (ClassificationDecision $record) => collect($record->probabilities)
                    ->map(fn (float $p, string $option) => sprintf('%s (%.2f)', $option, $p))
                    ->all())
                ->required(),
        ])
        ->action(fn (ClassificationDecision $record, array $data) => static::resolve($record, $data['department'])),
])

The override form shows the model's own probabilities next to each option. The reviewer sees that sales was at 0.23, which is often enough context to decide in two seconds. And resolve() writes the same two columns in both cases:

protected static function resolve(ClassificationDecision $record, string $department): void
{
    $record->update([
        'actual' => $department,
        'actual_source' => 'review',
        'reviewed_at' => now(),
    ]);

    $record->ticket->update(['department' => $department, 'routed_by' => 'human']);
}

This is the same shape as the tool approval flow the SDK ships for agents, applied to a classifier. The agent version pauses a tool call until a human approves it. This version pauses a routing decision. Same principle, and the same rule about who gets to press the button.

Write the truth back, including for the calls you got right

The review queue gives you ground truth for the decisions the model doubted. That is a biased sample. If you only ever learn the outcome of low-confidence calls, you can never find out whether your 0.9s are actually 90% right, and that is the question that decides whether your threshold is too high or too low.

So the auto-routed decisions need an outcome too. In a real helpdesk the natural moment is ticket closure, when an agent has handled it and the department it was closed in is known. That is one listener:

class RecordRoutingOutcome
{
    public function handle(TicketClosed $event): void
    {
        $event->ticket->decisions()
            ->where('question', 'department')
            ->whereNull('actual')
            ->update([
                'actual' => $event->ticket->department,
                'actual_source' => 'closed',
            ]);
    }
}

The whereNull('actual') matters. A reviewed decision already has its truth from a human and must not be overwritten by whatever department the ticket eventually drifted to.

For the demo I do not have a helpdesk, so a small command writes each ticket's labelled department onto its auto-routed decision, standing in for the closure event. Same two columns, same whereNull guard.

If you also want a global record of every classification for cost tracking, the SDK fires Laravel\Ai\Events\Classified with the invocation id, provider, model, prompt and response after every call. It is the right hook for a usage ledger. It is the wrong hook for outcome tracking, because the invocation id never reaches your calling code, so you cannot join it back to the ticket later. Log decisions from the action, log usage from the event.

Now calibration is a number you own

With suggested, confidence and actual on the same row, the report is a single query and two tables:

$decisions = ClassificationDecision::query()
    ->where('question', 'department')
    ->whereNotNull('actual')
    ->get();

The first table buckets by confidence and asks how often the model was right in each bucket. The second replays every threshold from 0.5 to 0.9 and asks what would have happened: how many tickets would have auto-routed, how many would have gone to a human, and how many of the automatic ones would have been wrong.

collect([0.5, 0.6, 0.7, 0.8, 0.9])->map(function (float $threshold) use ($decisions) {
    $auto = $decisions->filter(fn ($d) => $d->confidence >= $threshold);
    $wrong = $auto->reject->wasCorrect()->count();

    return [
        number_format($threshold, 2),
        sprintf('%d (%d%%)', $auto->count(), round($auto->count() / $decisions->count() * 100)),
        $decisions->count() - $auto->count(),
        $auto->isEmpty() ? '-' : sprintf('%d%%', round(($auto->count() - $wrong) / $auto->count() * 100)),
        $wrong,
    ];
});

I ran the 60 tickets through jev-latest, which resolved to jev-1.13.0. 18 billing, 18 technical, 14 sales, 10 refund, with 10 written to sit between two departments (a "charge I don't recognise" that is billing, and its twin with "reverse it please" that is a refund). The policy above auto-routed 58 and sent 2 to review. I resolved those two in Filament, overriding both, then wrote the labels back onto the rest to stand in for ticket closure. Here is the report:

60 decisions with a known outcome, model jev-1.13.0

Accuracy by confidence bucket:

Confidence	Decisions	Correct	Accuracy
0.0 to 0.5	1	0	0%
0.5 to 0.6	0	0	(none)
0.6 to 0.7	1	0	0%
0.7 to 0.8	3	1	33%
0.8 to 0.9	1	1	100%
0.9 to 1.0	54	54	100%

If the act threshold had been:

Threshold	Auto-routed	Sent to review	Auto accuracy	Wrong auto-routes
0.50	59 (98%)	1	95%	3
0.60	59 (98%)	1	95%	3
0.70	58 (97%)	2	97%	2
0.80	55 (92%)	5	100%	0
0.90	54 (90%)	6	100%	0

Read the first table top to bottom. Below 0.7 Jev was wrong both times, which is what "I'm not sure" should look like. From 0.8 up it was right 55 times out of 55. The bucket that matters is 0.7 to 0.8, where one answer in three was right, and my 0.75 bar sits in the middle of it. Both wrong auto-routes landed there, at 0.76 and 0.78, and both were tickets a human could argue either way ("Invoice PDF will not download" went to technical, my label said billing, and honestly the model has a case).

Now read the second table as a menu. At 0.75 I got 2 wrong routes and 2 reviews. Moving the bar to 0.80 costs three more tickets in the queue and removes every wrong route. That is not a judgement call any more. It is a row in a table, and the next run of the command tells you whether it held.

Sixty tickets is a small sample and I wrote them, so treat the percentages as a demonstration of the method, not a benchmark of Jev. The point is that the table exists. You can run it every Monday on last week's decisions, and when it says your 0.75 bucket is only 70% right, you raise the threshold and the review queue grows by a known amount. Threshold tuning stops being a feeling.

Cost, for the record. The 60 tickets used 28,479 input tokens, an average of 475 per ticket with three questions each. TypeSafe lists Jev at $42 per billion input tokens on typesafe.ai, which is $0.042 per million, so the whole run cost about a tenth of a cent. Latency from a VPS in Vienna was 589ms on average and 583ms median, with the slowest call at 704ms. Freek measured 639ms for a similar three-question call, so that is roughly what to budget for.

Testing without spending a cent

The SDK ships a fake for classification, which is where the policy gets its real test. You hand it the exact answer you want and assert what your code did with it:

use Laravel\Ai\Classification;
use Laravel\Ai\Responses\Data\ChoiceAnswer;

it('sends a 0.69 department call to the review queue instead of acting', function () {
    Classification::fake([
        ['department' => new ChoiceAnswer('billing', [
            'billing' => 0.77, 'sales' => 0.23, 'technical' => 0, 'refund' => 0,
        ], confidence: 0.69)],
    ]);

    $ticket = Ticket::create([...]);

    $decision = app(RouteTicket::class)->handle($ticket);

    expect($decision->decision)->toBe('review')
        ->and($ticket->fresh()->department)->toBeNull();

    Classification::assertClassified(fn ($prompt) => $prompt->asks('department'));
});

Any question you do not override gets a random but shape-valid answer, so the urgent and frustration questions in the action do not need stubbing. Classification::fake() also accepts a closure that receives the ClassificationPrompt, so you can return 1.0 when $prompt->contains('ASAP') and 0.0 otherwise, and preventStrayClassifications() makes an unfaked call throw. The second test in my suite feeds a refund at 0.85 and then at 0.93 and asserts that only the second one acts, which is the per-option threshold doing its job.

If you queue the routing (and you should, since a classification is an HTTP call to a third party), the Horizon setup for AI SDK jobs applies unchanged. Short timeout, its own queue, a retry that does not double-write the decision row.

Trade-offs

You are building on a dev branch. The class names are stable enough that I would ship this behind a composer.lock pin, but not on 1.x-dev without one. When 1.0 tags, check the upgrade guide the same way you did at 0.x.

One provider. Today Classification has TypeSafe and nothing else. The abstraction is there (ClassificationProvider, ClassificationGateway), so a second provider is a PR away, but right now a TypeSafe outage is a classification outage. The SDK's failover loop in PendingClassification::classify() already iterates providers, it just has one to iterate.

Boolean has no confidence, by design. If you gate on a Boolean, gate on distance from 0.5. A probability of 0.55 for "urgent" is a shrug, not a yes.

A review queue only works if someone works it. The badge count is not decoration. If it climbs past what your team clears in a day, the fix is not to lower the thresholds, it is to look at what the model keeps doubting. In my 60 tickets, three of the five lowest-confidence answers were tickets from the batch of ten I had deliberately written to sit between two departments. That is what you want a classifier to do.

And the calibration report is only as honest as your write-back. Skip the closure listener and you will tune thresholds on the biased half of the data. That shortcut is where the wrong lessons come from.

FAQ

Does the Laravel AI SDK Classification API work on the stable release?

Not yet. Classification landed on the 1.x branch on 17 September 2026 (laravel/ai PR #1010). The latest stable tag is v0.11.2. Install laravel/ai:1.x-dev to use it now, and expect a 1.0 release to follow, since the branch already has an upgrade guide in progress.

What is the difference between probability and confidence in a Jev answer?

For a Choice or Score, probabilities is the full distribution across your options or levels, and confidence is one number TypeSafe derives from how concentrated that distribution is. For a Boolean, there is only probability, because a yes/no answer's certainty is the probability itself. Confidence can be null if a provider cannot measure it, so always handle that case.

Can I use a different threshold for each option?

Yes, and you should. The policy class in this post keeps a floor below which nothing acts, then a per-option threshold above it. A refund route needs a higher bar than a sales route because the cost of being wrong is higher. Options without an explicit threshold default to 1.0, which sends them to review.

How do I test classification code without calling TypeSafe?

Classification::fake() accepts an array of per-question answers or a closure. Pass a ChoiceAnswer with the exact probabilities and confidence you want to exercise, run your code, and assert on the outcome. Classification::assertClassified() and assertNothingClassified() check that the call happened, and preventStrayClassifications() makes any unfaked call throw.

Is Jev cheaper than using an LLM for the same classification?

TypeSafe publishes $42 per billion input tokens with no charge for output. Whether that beats your current LLM setup depends on your prompt length and volume, and I have not benchmarked the two side by side here. What I can say from this run is the token count and latency per ticket above. A fair comparison against a small LLM with structured output is a separate post.

What to take away

The Classification API is ten lines of code and everyone will write those ten lines. The decisions table, the per-option policy, the review queue and the write-back are maybe 200 more, and they are what let you raise a threshold on a Monday morning because a report told you to, instead of because a customer complained.

Jev's whole pitch is that it tells you when it is unsure. Build the part that listens.

Your Queue Worker Gets a SIGTERM on Every Deploy. Here Is What Laravel 13.31 Lets You Do About It

Hafiz — Thu, 17 Sep 2026 04:15:11 +0000

Every time you deploy, something sends your queue workers a SIGTERM. Supervisor does it on restart. Docker does it on docker stop. Kubernetes does it before it evicts a pod. And somewhere in the middle of that, a job is halfway through importing 40,000 rows.

What happens to that job?

The comfortable answer is that Laravel handles it. The worker finishes the current job before exiting, so nothing is lost. That is true right up until the job takes longer than your process manager is willing to wait, at which point SIGKILL arrives and the job dies wherever it happens to be.

Laravel 13.31 shipped a JobInterrupted event, and 13.7 shipped the Interruptible contract it depends on. Together they let a job notice the signal and stop cleanly at a safe point. I spent a morning testing both against a real 13.31 app, and two things turned out differently from how the release notes describe them. One of them silently disables the whole feature.

The problem is the gap between SIGTERM and SIGKILL

When your process manager wants a worker gone, it does not kill it outright. It sends SIGTERM, waits, and then escalates to SIGKILL if the process is still alive.

Laravel's worker catches that SIGTERM and sets an internal shouldQuit flag. It does not abandon the job it is running. It lets the current job finish, then exits before reserving another one. So for a job that takes two seconds, this is a non-issue.

For a job that takes nine minutes, it is the whole issue. Supervisor's stopwaitsecs defaults to 10 seconds, and the Laravel docs recommend raising it past the length of your longest job, with an explicit warning: "You should ensure that the value of stopwaitsecs is greater than the number of seconds consumed by your longest running job. Otherwise, Supervisor may kill the job before it is finished processing."

The sample Supervisor config in the docs sets it to 3600. An hour. That is the honest cost of the "worker finishes its current job" guarantee, and it means a deploy can hang for an hour waiting on one import.

Interruptible jobs are the other way out. Instead of making the deploy wait for the job, you let the job hear the signal and wind itself down.

What actually happens, in order

Here is the part where testing beat reading. I wrote a job that logs each step, implemented Interruptible, registered listeners on both events, and sent a real SIGTERM to a running worker mid-job.

The observed log, in the order it was written:

SlowReport: step 1
SlowReport: step 2
SlowReport: step 3
SlowReport: step 4
EVENT WorkerInterrupted signal=15 queue=default
SlowReport::interrupted() called with signal 15
EVENT JobInterrupted signal=15 conn=database
SlowReport: stopping cleanly at step 5
Worker STOPPED Interrupted

Signal 15 is SIGTERM. The ordering is not what you would guess from the changelog.

The interrupted() method on the job runs before the JobInterrupted event fires, not after. If you are writing a listener that assumes the job has already reacted to the signal by the time your listener runs, that assumption holds. If you assumed the reverse, that your listener runs first and can influence what the job does, it does not.

In Illuminate\Queue\Worker, the signal handler sets shouldQuit, dispatches WorkerInterrupted, then calls notifyJobOfSignal(), which calls $job->interrupted($signal) and only then dispatches JobInterrupted. Four steps, one after the other, inside the signal handler itself.

And notice the last line. Worker STOPPED Interrupted comes from the stop-reason output added in 13.30, which tells you why a worker exited instead of leaving you guessing.

The flag that turns all of this off

This is the one that will actually bite people.

php artisan queue:work --once never installs the signal handlers at all.

Not "handles them differently". Does not install them. In Worker, the call to listenForSignals() lives inside the daemon() method. The --once flag routes through runNextJob() instead, which never touches signal handling. You can see the branch in WorkCommand:

->{$this->option('once') ? 'runNextJob' : 'daemon'}(

I ran the same SIGTERM test with --once and the log stopped dead at step 4. No WorkerInterrupted. No interrupted() call. No JobInterrupted. The process died mid-loop with the job still reserved in the table, waiting for its timeout to expire before anything retries it.

This matters more than it sounds, because --once is everywhere. It is the standard pattern for running workers under cron. It shows up in Docker setups that prefer one job per container. It is what a lot of people reach for in Kubernetes when they want a job runner rather than a long-lived process. Every one of those setups gets SIGTERM on shutdown, and none of them will run your cleanup code.

If you rely on interruptible jobs, run the daemon. That is the requirement, and nothing in the release notes says so.

Writing a job that stops cleanly

The contract is one method:

namespace Illuminate\Contracts\Queue;

interface Interruptible
{
    public function interrupted(int $signal): void;
}

The important thing to understand is that interrupted() is cooperative, not preemptive. Laravel calls it, and that is the entire extent of Laravel's involvement. It does not unwind your stack, throw an exception, or stop your loop. If your handle() method never checks anything, the job keeps running exactly as before and your interrupted() method accomplished nothing.

So the pattern is always two halves. A flag set by the signal, and a check inside the work loop:

namespace App\Jobs;

use Illuminate\Contracts\Queue\Interruptible;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

class SlowReport implements ShouldQueue, Interruptible
{
    use Queueable;

    protected bool $stopping = false;

    public function handle(): void
    {
        foreach (range(1, 10) as $step) {
            if ($this->stopping) {
                logger()->info("SlowReport: stopping cleanly at step {$step}");

                return;
            }

            logger()->info("SlowReport: step {$step}");
            sleep(1);
        }

        logger()->info('SlowReport: finished all steps');
    }

    public function interrupted(int $signal): void
    {
        $this->stopping = true;
        logger()->info("SlowReport::interrupted() called with signal {$signal}");
    }
}

Where you put the check decides how quickly the job gives up the process. A check at the top of a loop that iterates once per second means you stop within a second. A check outside a loop that runs for four minutes means you stop in four minutes, which defeats the point.

Three practical notes on the real version of this:

Save progress before returning. Stopping cleanly is only useful if the next run can pick up where this one left off. A checkpoint column, a cursor, a last-processed ID. Returning without recording anything just means you redo the work.
Return, do not throw. Throwing marks the job failed and sends it down the retry path, which is not what happened. A clean return lets you re-dispatch on your own terms.
Put the check where the work is. Inside the chunk loop, not around it.

If your jobs process large batches, the checkpointing side of this pairs with the batching approach I wrote about in processing 10,000 tasks without breaking, where the same idea keeps a failed run from restarting at zero.

The two events do different jobs

Both events exist and they are not interchangeable.

JobInterrupted carries connectionName, job and signal. It fires only for jobs that implement Interruptible. The check in notifyJobOfSignal() returns early unless there is a current job, its resolved handler is a CallQueuedHandler, and the underlying command implements the contract. Miss any of those and the event never fires.

WorkerInterrupted carries signal, connectionName, queue and the WorkerOptions. It fires whenever a worker catches a termination signal, whatever job happens to be running and whether or not that job implements anything.

That difference makes WorkerInterrupted the better observability hook. It tells you a worker on a given queue got a signal, and it tells you for every worker, not just the ones running jobs you have retrofitted. If you want a count of how often deploys are interrupting in-flight work, listen to that one:

use Illuminate\Queue\Events\WorkerInterrupted;
use Illuminate\Support\Facades\Event;

Event::listen(function (WorkerInterrupted $event) {
    logger()->warning('Worker interrupted', [
        'signal' => $event->signal,
        'queue' => $event->queue,
        'connection' => $event->connectionName,
    ]);
});

Use JobInterrupted when you need the job instance, for per-job cleanup or for recording which specific job was cut short.

Neither event appears in the queue documentation as of this writing. The Interruptible contract is documented under Reacting to Worker Signals, but the events are release-note material only, which is part of why the ordering surprise above is easy to miss.

totalSize() and the number you were probably alerting on

The other half of 13.31 is queue measurement, and it fixes a real footgun.

size($queue) counts one queue. If you call size() with no argument, you get the default queue and nothing else. Plenty of monitoring code calls that, names the metric something like "queue depth", and quietly ignores every other queue in the system.

totalSize() counts all of them. I dispatched three jobs onto three different queues and checked:

size("default"): 1
size("emails"):  1
totalSize():     3

There are three companion methods that break the number down, and they are the ones worth graphing:

$queue = app('queue')->connection('database');

$queue->totalPendingSize();   // waiting, available now
$queue->totalDelayedSize();   // waiting, scheduled for later
$queue->totalReservedSize();  // picked up by a worker, still running
$queue->totalSize();          // all of the above

A clean run with two immediate jobs and one delayed job returned 2, 1, 0 and 3 respectively.

The split matters because the three numbers mean different things when something is wrong. Pending climbing means you are not consuming fast enough. Delayed climbing is usually just scheduled work and is often fine. Reserved climbing while pending stays flat means jobs are being picked up and not finishing, which is the shape of a hung worker or a job stuck on an external call.

Two caveats worth knowing before you wire this into a dashboard.

These methods are implemented per driver rather than on the base Queue class, and that matters more than it sounds. DatabaseQueue and RedisQueue return real numbers. SqsQueue, SyncQueue and BeanstalkdQueue implement the same methods and return a hardcoded 0:

// SqsQueue.php
public function totalSize()
{
    return 0;
}

So on SQS the call succeeds, returns zero, and never errors. Wire that to a dashboard and you get a flat line that looks like a healthy queue. Check what your driver actually returns rather than whether the method exists.

And the implementations are not equivalent in cost. DatabaseQueue::totalSize() is a single unfiltered count() against the jobs table. RedisQueue::totalSize() enumerates every known queue name and sums size() across them, so the work scales with how many queues you have. On Redis with a lot of queues, that is not a call to make every second from a hot path.

For a fuller picture of what to watch beyond raw depth, the trade-offs in managed queues versus Horizon cover where each approach puts the monitoring burden.

What I would actually change

If you run long jobs, do these three things in order.

Check whether you are running --once. Everything else is moot if signal handlers were never installed. Look at your Supervisor config, your Dockerfile CMD, your Kubernetes manifests and your crontab. If --once is there and you have jobs that run for minutes, you are losing work on every deploy and it is not being logged anywhere.

Add Interruptible to your longest job, not all of them. Find the job with the worst p99 duration and start there. Most jobs finish in under a second and gain nothing from this. The import that runs for six minutes is the one holding up your deploys.

Listen to WorkerInterrupted before you do anything else. It costs one listener and it tells you whether this is a real problem in your app. If it fires twice a month, drop it and move on. If it fires forty times during a deploy window, you have found something.

Then, once you know a job can be interrupted safely, you can lower stopwaitsecs from the hour the docs suggest to something that matches how fast your jobs actually wind down. That is the payoff. Not just cleaner shutdowns, but deploys that do not have to choose between waiting an hour and killing work in progress.

The multi-tenant version of this gets messier, because a job stopping cleanly still has to stop cleanly in the right tenant context. I wrote about three bugs that only show up in multi-tenant queues if you are running that setup, and the two-minute server migration covers the deploy side when workers are part of the cutover.

FAQ

Does implementing Interruptible mean my job gets killed when a deploy happens?

No. Laravel calls your interrupted() method and nothing else. The job keeps running until your own code decides to stop it, which is why the flag-and-check pattern matters. A job that implements the contract but never checks the flag behaves exactly as it did before.

Why did nothing happen when I sent SIGTERM to my worker?

The most likely cause is --once. That flag routes through runNextJob() instead of daemon(), and signal handlers are only installed in daemon(). The other possibility is that the pcntl extension is not loaded, since Laravel checks for it before installing handlers and silently skips them if it is missing.

What is the difference between JobInterrupted and WorkerInterrupted?

WorkerInterrupted fires whenever a worker receives a termination signal, regardless of what it is running. JobInterrupted fires only when the job currently being processed implements Interruptible. Use the worker event for observability across everything, and the job event when you need the job instance itself.

Does totalSize() work on every queue driver?

Every driver implements it, but only the database and Redis drivers return real numbers. SqsQueue, SyncQueue and BeanstalkdQueue return a hardcoded 0, so the call works and tells you nothing. On SQS, queue depth has to come from CloudWatch instead.

Should I still set stopwaitsecs high in Supervisor?

Until your long jobs handle interruption, yes, because the alternative is SIGKILL partway through. Once a job stops cleanly within a known window, you can bring the value down to match that window instead of padding it to cover the full job duration.

The thing worth remembering

The feature here is small. One interface, two events, four counting methods. What makes it worth an afternoon is that the failure it prevents is invisible: jobs dying partway through on deploy, leaving half-written state, and nothing in your logs saying that is what happened.

Before you write a single listener, go and grep your infrastructure config for --once. If it is there alongside jobs that take minutes, that one flag is quietly discarding every cleanup path Laravel offers, and it will keep doing it however many contracts you implement.

Laravel Starter Kits Now Ship Vite+. Here Is What vp migrate Does to an App You Already Have

Hafiz — Mon, 14 Sep 2026 04:15:10 +0000

Every Laravel starter kit now ships with Vite+. That landed in laravel/maestro#60 on 28 August, covering all 21 kit variants, and it deletes eslint.config.js, .prettierrc and .prettierignore in favour of one binary called vp.

If you are starting a new app, you get this for free and it works. The interesting question is the other one. What happens when you point vp migrate at an app you already have?

I tried it on a stock Laravel React starter kit. The first attempt refused to run at all, the second reported success while quietly failing halfway through, and the config file came out at 1,293 lines. None of that is a reason to avoid Vite+, but all of it is worth knowing before you run the command on something you care about.

What Vite+ actually is

One binary that swallows your whole frontend toolchain. Vite for the dev server and build, Rolldown for bundling, Vitest for tests, Oxlint in place of ESLint, Oxfmt in place of Prettier, tsdown for library packaging, plus its own Node and package-manager management.

So instead of npm run lint and npm run format:check and npm run types:check, you run vp check and it does all three in one pass. The test half is Vitest, which is the JavaScript side of your suite rather than a replacement for Pest on the PHP side.

It is beta, currently 0.3.1. It is also MIT licensed, which is worth saying clearly because VoidZero originally announced it as a paid product for startups and enterprises. They reversed that and open sourced the whole thing. If you were holding off because you expected a licence bill later, that concern is gone.

Installation does not go through npm:

curl -fsSL https://vite.plus | bash

There is no npx vp. If you try it, the CLI stops you and points at the installer. On macOS it drops into ~/.local/share/vite-plus, asks for no sudo, and adds a line to your shell config. vp implode --yes removes it again.

Attempt one: it refuses

A freshly created Laravel React starter kit today ships Vite 6. Run vp migrate against it and you get this.

Worth noting that the message and the docs disagree. The CLI asks for Vite 7 or newer. The migration guide says to upgrade to Vite 8 and Vitest 4.1 first. Follow the docs, since Vite+ 0.3 is built on Vite 8.

The good news is that the refusal is clean. It checked package.json, decided it could not proceed, and changed nothing. No half-migrated state to unpick.

So the first real step of any migration is not vp migrate at all. It is upgrading Vite, which for most existing Laravel apps is its own piece of work with its own breaking changes.

Attempt two: the report says success, the middle says otherwise

I upgraded Vite to 8.3.0 and ran it again.

Read the summary and the warning together, because they contradict each other. ✓ Dependencies installed in 21s sits four lines above Dependency installation failed (exit code 1).

What happened underneath is a peer dependency conflict, the JavaScript cousin of the Composer conflicts that block a Laravel upgrade. The kit ships @tailwindcss/vite@4.0.8, which declares a peer range of Vite 5 or 6. Once Vite is on 8, npm refuses to resolve the tree and bails out. The migration kept going regardless, rewrote every config file, and only mentioned the failure in a warning at the bottom.

The fix is the one the warning names:

vp install

And it works, for a reason that is easy to miss. The migration rewrote package.json so that vite is no longer the real Vite:

"devDependencies": {
    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.1",
    "vite-plus": "0.3.1"
},
"overrides": {
    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.1"
}

vite is now an alias to VoidZero's own package, pinned with an overrides entry so nothing in the tree can ask for anything else. Tailwind's peer range is satisfied by fiat. That is how the conflict disappears on the second attempt, and it is the part of Vite+ that deserves a moment of thought before you adopt it, because every package that peers on Vite is now resolving against a VoidZero build rather than upstream Vite.

If you deploy from CI with npm ci and a lockfile, test that path specifically. The alias plus override combination is exactly the sort of thing that behaves differently under a clean install.

The diff

Six files, and it deletes two of them:

 .prettierrc       |   18 -
 eslint.config.js  |   44 -
 package-lock.json | 7574 +-
 package.json      |   35 +-
 tsconfig.json     |    1 -
 vite.config.js    | 1286 ++++
 6 files changed, 4463 insertions(+), 4495 deletions(-)

Nine devDependencies collapse into two. Out go eslint, @eslint/js, eslint-config-prettier, eslint-plugin-react, eslint-plugin-react-hooks, typescript-eslint, prettier, prettier-plugin-organize-imports and prettier-plugin-tailwindcss. In come vite-plus and the aliased vite.

The scripts get rewritten to match, so vite build becomes vp build, prettier --write becomes vp fmt, eslint . --fix becomes vp lint . --fix, and a prepare script is added to wire up git hooks.

One detail the summary glosses over. It claims Prettier was migrated to Oxfmt, and it deleted .prettierrc, but it left .prettierignore on disk with a warning suggesting you move those patterns into the config. So you finish the migration with a stray dotfile for a tool that is no longer installed.

Why vite.config.js is now 1,293 lines

This is the number that surprised me. The starter kit's config was 21 lines. After migration it is 1,293.

It is not gratuitous. The ESLint config, the Prettier config and the lint environment all got folded into one file, and most of the bulk is a single block: 1,127 browser globals written out one per line.

export default defineConfig({
    staged: {
        '*': 'vp check --fix',
    },
    lint: {
        plugins: ['oxc', 'typescript', 'unicorn', 'react'],
        categories: {
            correctness: 'warn',
        },
        env: {
            builtin: true,
        },
        globals: {
            AbortController: 'readonly',
            AbortSignal: 'readonly',
            // ...1,125 more
        },
    },

Underneath that sits the rules block, then the formatter settings, then your actual plugins.

Credit where it is due on the translation. It carried the kit's real Prettier settings across rather than resetting to defaults, so printWidth: 150, tabWidth: 4, single quotes, the Tailwind class sorting with its clsx and cn functions, and the ignore pattern for the generated UI components all survived intact.

Your Vite plugins also get wrapped:

plugins: lazyPlugins(() => [
    laravel({
        input: ['resources/css/app.css', 'resources/js/app.tsx'],
        ssr: 'resources/js/ssr.jsx',
        refresh: true,
    }),
    react(),
    tailwindcss(),
]),

lazyPlugins keeps the plugin array from being constructed when you are only running lint or format, which is how vp check stays fast without booting your whole build pipeline.

The practical cost is that vite.config.js is no longer a file you read. It is generated output that happens to live in your repo, and every future diff on it will be noise. If that bothers you, the globals block is the part to consider trimming by hand once you know which environments you actually target.

It builds, and then vp check fails

The build works, and quickly:

✓ built in 467ms

vp dev starts a normal dev server on port 5173 and picks up the Laravel plugin correctly. Two deprecation warnings come from vite:react-babel about esbuild and optimizeDeps.esbuildOptions now being Rolldown's job, which is upstream plugin lag rather than anything your app did.

Then vp check fails on a starter kit nobody has touched.

Two separate things are going on, and it is worth keeping them apart.

The formatting failures are a scope change. The old scripts were prettier --write resources/, so formatting only ever looked at the resources/ directory. vp check looks at the repository. That means it reformats files Prettier was never pointed at, and on this kit it rewrote both GitHub Actions workflow files, 76 lines each. Nothing broke, but a migration that quietly restyles your CI config is a surprise, and it explains the reviewer note on the Laravel PR about Inertia kits needing workflow updates. If your GitHub Actions pipeline asserts on formatting, that reformat is the kind of thing that turns a green build red for reasons unrelated to your code.

The four lint errors are a different story:

welcome.tsx:221:46        TS2322  '"plus-darker"' is not assignable to MixBlendMode
login.tsx:25:72           TS2344  LoginForm does not satisfy FormDataType
register.tsx:20:72        TS2344  RegisterForm does not satisfy FormDataType
reset-password.tsx:24:72  TS2344  ResetPasswordForm does not satisfy FormDataType

Vite+ did not cause these. I checked out the pre-migration commit and ran npx tsc --noEmit against it, and the same four errors are already there. The starter kit had no types:check script, so nothing in the normal workflow ever ran the type checker. Vite+ turns on typeAware and typeCheck by default, so the moment you migrate, four pre-existing type errors become visible.

That is an argument for Vite+, not against it. But it does mean your first vp check on a real codebase will probably fail, and the failures will look like the migration's fault when they are not.

Should you migrate an existing app?

For a new project, take it. The kits ship with it, it works, and one command in place of four npm scripts is a real improvement to the daily loop. That holds whichever kit you picked, though the Livewire kits changed least of all of them, since they have no TypeScript to lint, which is one more small point in the Livewire versus Inertia ledger.

For an app you already run, the honest sequence is:

Upgrade to Vite 8 first. This is the actual project. vp migrate will not even start until you do, and the Vite 8 upgrade has its own breaking changes that have nothing to do with Vite+.
Run the migration on a clean branch and read the whole diff, particularly vite.config.js and anything under .github/.
Run vp install immediately, whatever the summary claims about dependencies.
Expect the first vp check to fail, and triage it before assuming the migration broke something.
Test your CI install path, since the aliased vite and the overrides entry are the parts most likely to behave differently under npm ci.

The thing I would weigh hardest is the alias. Vite+ is MIT and the reversal on pricing was the right call, but adopting it means your vite dependency resolves to a VoidZero package and every peer range in your tree is satisfied against that instead of upstream Vite. For most apps that is a fine trade for the tooling consolidation. It is still a decision, not a formality, and it is not one the migration output asks you to make out loud.

Worth knowing too that none of this is in the Laravel documentation yet. The asset bundling docs do not mention Vite+, vp, Oxlint or Rolldown anywhere, even though the starter kits now ship all four.

FAQ

Do I have to migrate if I am on an older Laravel app?

No. Vite+ ships in new starter kits, and nothing in Laravel requires it. The existing vite plus laravel-vite-plugin setup keeps working, and the Laravel documentation still describes that as the standard path.

Why did vp migrate refuse to run on my project?

Most likely your Vite version. The CLI stops if package.json has anything below Vite 7, and the migration guide asks for Vite 8 and Vitest 4.1. The refusal is clean, so nothing is modified when it happens.

Is Vite+ free, or does it become paid later?

MIT licensed and free. VoidZero originally announced tiered pricing with a flat fee for startups and custom enterprise pricing, then reversed course and open sourced it. The projects it builds on, Vite, Vitest, Rolldown and Oxc, are all MIT as well.

Why is my vite.config.js suddenly over a thousand lines?

The lint environment gets inlined, including roughly 1,100 browser globals, along with the rules block and the formatter settings that used to live in eslint.config.js and .prettierrc. It is generated configuration rather than something you are expected to read.

Will vp check pass on my codebase after migrating?

Probably not on the first run, and often for reasons that predate the migration. Vite+ enables type-aware checking by default, so any type errors your old lint script never surfaced will appear immediately. Check them against tsc on your pre-migration commit before treating them as regressions.

What this comes down to

Vite+ in the starter kits is a straightforward win for new apps. For existing ones, vp migrate is not really the step that matters. Upgrading to Vite 8 is, and the migration is the short part at the end.

If you do run it, read the summary sceptically. A migration that prints "Dependencies installed" and "Dependency installation failed" in the same output has earned a careful look at the diff before you commit it.