DEV Community: Hafiz

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

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

Originally published at hafiz.dev

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.

View the interactive component on hafiz.dev

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

Originally published at hafiz.dev

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.

View the interactive component on hafiz.dev

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

Originally published at hafiz.dev

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.

View the interactive component on hafiz.dev

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

Originally published at hafiz.dev

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.)

View the interactive component on hafiz.dev

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

Originally published at hafiz.dev

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.

View the interactive component on hafiz.dev

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

Originally published at hafiz.dev

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.

Spatie Permission vs Bouncer: One Question Decides Which One You Need

Hafiz — Thu, 10 Sep 2026 04:15:10 +0000

Originally published at hafiz.dev

Every roles system starts the same way. You add a permission called edit articles, give it to the editor role, and ship it. It works for a year.

Then a client asks for something small. Sarah should be able to edit this one article, the one she wrote with the legal team, and nothing else. Your permission is a string. Strings don't know about article 4,182.

That request is the moment the decision gets made for you, and it decides which package you should have picked. So here's the question that separates the two, before any code.

The question that decides it

Are your permissions about kinds of things, or about particular things?

"Editors can edit articles" is a kind of thing. The permission is a name, the same name for every article in the table, and a role carries it. That's spatie/laravel-permission.

"Sarah can edit article 4,182" is a particular thing. The permission points at one row. That's silber/bouncer.

Both register themselves on Laravel's Gate, so $user->can(...) works either way and your controllers look identical. The difference sits underneath, in what the database can express.

Spatie Permission: permissions are names

Spatie's model is roles and permissions as strings, stored in tables, editable at runtime. You add a trait and you're running:

use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}

Then you create the data:

use Spatie\Permission\Models\Permission;
use Spatie\Permission\Models\Role;

$editor = Role::create(['name' => 'editor']);
$editor->givePermissionTo(Permission::create(['name' => 'edit articles']));

$user->assignRole('editor');
$user->can('edit articles'); // true

That is most of the package. There's a query scope for finding users by permission, syncPermissions and syncRoles for bulk changes, and getAllPermissions for showing someone what they hold.

The adoption gap matters more than people admit. Spatie's package has over 110 million installs on Packagist. Every Laravel developer you hire has used it, every AI assistant knows its API, and every question you'll ever have is already answered on Stack Overflow. That is worth real money on a team.

The ceiling. Permissions are global names. The package does not model a permission attached to one specific row, and this is a documented limitation rather than an oversight, asked and answered on the issue tracker years ago. Spatie's own docs point you at Laravel policies for row-level rules, which is the right answer and also the moment you notice the package stopped helping.

So Sarah and article 4,182 become your problem, solved with a policy and a pivot table you build yourself.

Bouncer: abilities can point at a row

Bouncer calls them abilities, and an ability can be granted against a class or against one model:

Bouncer::allow($user)->to('edit', Post::class); // any post
Bouncer::allow($user)->to('edit', $post);       // this post

That second line is the whole reason Bouncer exists. Sarah and article 4,182 take one call and no schema of your own.

Ownership is built in, which removes a policy method most apps write by hand:

Bouncer::allow($user)->toOwn(Post::class);
Bouncer::allow($user)->toOwn(Post::class)->to(['view', 'update']);

Bouncer::ownedVia(Post::class, 'created_by');

And there's a capability Spatie has no answer for. Bouncer can forbid, which beats any allow that would otherwise apply:

Bouncer::allow('admin')->everything();
Bouncer::forbid('admin')->toManage(User::class);

Bouncer::forbid('banned')->everything();
Bouncer::assign('banned')->to($user);

Suspending an account without stripping and later rebuilding someone's roles is a real operational need, and forbidding is the clean way to do it. Note that unforbid only removes the block. It does not grant the ability back, so the underlying allow has to still be there.

The cost is adoption. Bouncer sits around 5 million installs against Spatie's 110 million plus, so you'll find fewer examples, fewer colleagues who know it, and thinner coverage when you ask an AI assistant about it. It is maintained, with v1.0.4 released in March 2026 supporting Laravel 11 through 13, but it moves at a slower pace.

View the interactive component on hafiz.dev

Policies still sit on top of both

Neither package replaces policies, and the mistake I see most often is treating them as if it did. Permission checks scattered through controllers and Blade files are the same problem as business logic scattered through controllers, and they cause the same trouble later.

Put the package check inside the policy:

public function update(User $user, Post $post): bool
{
    return $user->can('edit articles') && $post->status !== 'locked';
}

Your controller then calls Gate::authorize('update', $post) and knows nothing about which package you chose. Swap Spatie for Bouncer later and the controllers don't change. Spatie's own documentation recommends exactly this, describing policies as the place where your application logic combines with your permission rules.

I've covered how policies and gates work in detail in the authorization guide, including the before() super-admin shortcut and rich response objects, so I won't repeat that ground here.

Multi-tenancy is where they diverge again

Both handle tenants, differently enough that it should influence your choice.

Spatie has a teams mode you turn on in config before running migrations, then set the active team per request:

// config/permission.php
'teams' => true,

setPermissionsTeamId(session('team_id'));

Two details cause problems. That middleware has to run before SubstituteBindings or you'll get 404 responses instead of 403s, which is a confusing afternoon. Spatie's documentation still shows this being set in app/Http/Kernel.php, and that file hasn't existed since Laravel 11. On Laravel 13 the priority goes in bootstrap/app.php:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->prependToPriorityList(
        before: \Illuminate\Routing\Middleware\SubstituteBindings::class,
        prepend: \App\Http\Middleware\TeamsPermission::class,
    );
})

And when you switch teams inside a single request you must clear the loaded relations, or you'll read the previous team's answers:

setPermissionsTeamId($newTeamId);
$user->unsetRelation('roles')->unsetRelation('permissions');

Bouncer scopes everything through one call instead:

Bouncer::scope()->to($tenantId);

Cleaner to read, and it scopes abilities and roles together. If you're deciding tenancy strategy at the same time, the tenancy comparison covers the layer below this one, and Filament's tenancy implementation shows how it plays out in an admin panel.

The cache bug that catches both

Permission checks run on nearly every request, so both packages cache. Both then hand you the same class of production bug, where you change a permission and nothing happens.

Spatie caches the role and permission registry for 24 hours by default. The helper methods reset it for you, but editing rows directly in the database does not, and neither does a deploy. When permissions look stale:

php artisan permission:cache-reset

Bouncer caches per request by default, which is safe. Turn on cross-request caching for speed and you take on invalidation yourself:

Bouncer::cache();          // faster
Bouncer::refreshFor($user); // now your job, after every change

With a scoped Bouncer, refreshFor only clears the current tenant's cache, so a user in three tenants needs three calls. That one has cost me an evening.

Whichever you pick, log permission changes. An audit trail turns "the permission isn't working" into a question you can answer, and activity logging is a twenty-minute install.

What I'd actually choose

Spatie, for most applications. Coarse permissions cover far more real systems than people expect, the ecosystem advantage is large and compounding, and you can express the occasional row-level rule in a policy with a pivot table when it comes up.

Bouncer when per-row permissions are the product rather than an exception. Shared documents, per-project collaborators, anything where users grant each other access to specific records. If your app has a share button, that's Bouncer.

Neither, if you have three roles that never change. A role column and a policy will outlive both packages, and you can add one later when the requirements actually arrive. Reaching for a permissions package on day one is a common way to carry two tables and a cache layer you never needed.

FAQ

Can I migrate from Spatie to Bouncer later?

Yes, and it's less painful than it sounds if your checks live in policies. Both register on the Gate, so can() calls and @can directives keep working. You rewrite the seeding and admin screens, migrate the data, and swap the calls inside your policy methods. If permission checks are scattered across controllers and Blade files instead, the migration touches every one of them, which is the strongest practical argument for the policy layer.

Do I still need policies if I use one of these packages?

Yes. Packages answer what a user holds. Policies answer whether an action is allowed right now, which usually combines the permission with state, like a locked post, a closed invoice or an expired subscription. Skipping policies means encoding that state logic into permission names, and you'll end up with strings like edit unlocked articles.

Which one for a multi-tenant SaaS?

Either works. Spatie's teams mode needs the config flag set before you migrate, so decide early, and be careful with the middleware ordering. Bouncer's scopes read more cleanly and cover abilities and roles in one call. If your tenants need to grant each other access to individual records, that pushes toward Bouncer regardless of tenancy.

Is Bouncer still maintained?

Yes. Version 1.0.4 shipped in March 2026 with support for Laravel 11, 12 and 13. It moves slower than Spatie's package and has a fraction of the installs, so judge it on release cadence and open issues rather than assuming abandonment. The smaller community is a real cost, just not a correctness one.

The thing worth remembering

The choice comes down to whether your permissions name kinds of things or particular things. That answer comes from the product, not from the code.

Get that answer from whoever writes the requirements, before you install anything. If nobody can tell you whether users will ever share single records with each other, you don't have enough information to choose, and the safe move is a role column until you do.

Every AI Word You Keep Hearing, Explained With Laravel Code

Hafiz — Mon, 07 Sep 2026 04:15:09 +0000

Originally published at hafiz.dev

Someone drops this into your team chat: "we'll put a guardrail on the sub-agent before its tool call hits the vector store." You know every single one of those words. The sentence still means nothing.

That was me for most of this year. The code was never the hard part. The vocabulary was, because almost every explainer is written in Python for people building models, not for people wiring a model into an app that already has a Stripe integration and a queue that has to stay up.

So this is the map I wanted. Thirty-one terms, grouped into five layers, each one anchored to code that runs in a Laravel app. No maths beyond what you already remember.

One thing holds the whole map together, and it's worth saying before the first term. All of it sits on next-token prediction plus plumbing you write yourself. Once you accept that, the fancy words stop being fancy.

Layer 1: what the model actually is

An LLM, or large language model, guesses what comes next. That's the entire job. You give it some text, it produces a probability distribution over what the next chunk of text might be, picks one, appends it, and does the whole thing again.

That chunk is a token. A token isn't a word. It's closer to a syllable-sized piece of a word, and the model has its own vocabulary of them. OpenAI's rule of thumb for English is that one token runs to roughly four characters, or about three quarters of a word, so 100 tokens is about 75 words. Short common words are one token. Long or unusual ones split into several.

You don't have to trust a rule of thumb, though. The Laravel AI SDK hands you the real count on every response:

$response = (new SalesCoach)->prompt('Summarise this transcript.');

$response->usage->inputTokens;
$response->usage->outputTokens;
$response->usage->totalTokens;

Log those three numbers on your first real agent and the cost model stops being abstract. If your provider supports prompt caching, cacheReadInputTokens and cacheWriteInputTokens are there too, and they matter more than people expect once a system prompt gets long.

Next-token prediction is the part that's hardest to accept. Watching a model write a working migration, a test, and a passing implementation, it feels impossible that it's picking one token at a time. It is, though. And knowing that explains most of its failures better than any theory about reasoning does.

Hallucination is the name for the most common of those failures. The model produces something fluent and wrong, and gives you no signal that it's wrong, because nothing in next-token prediction separates true from likely. It isn't lying and it isn't broken. It's doing the only thing it does, with nothing to check the output against. That's the argument for tools and retrieval later in this post. Both exist to give the model something real to work from.

The thing that made this work at scale was the transformer, from a 2017 paper by Vaswani and seven colleagues called Attention Is All You Need, submitted on 12 June that year. Earlier architectures read text in order, one position at a time. The transformer looks at all positions at once and learns which ones should pay attention to which. That's the breakthrough, compressed into a sentence.

Temperature controls how adventurous the pick is. When the model has ten plausible next tokens, low temperature makes it take the most likely one nearly every time, and high temperature lets it wander. In the SDK it's an attribute on the agent class:

use Laravel\Ai\Attributes\Temperature;

#[Temperature(0.2)]
class InvoiceClassifier implements Agent
{
    use Promptable;
}

Classification, extraction, anything you're going to parse: keep it low. Naming things and writing copy: raise it.

The context window is how much text the model can consider in one go. Everything counts against it. Your system prompt, the conversation so far, retrieved documents, tool definitions, tool results, all of it.

Here's where I'd push back on the usual advice, which is that bigger is better. Chroma's Context Rot report from July 2025 tested 18 models and found that performance degrades as input grows, well before the window is anywhere near full. NVIDIA's RULER benchmark found something similar and blunter, that plenty of models advertising 32k or more can't actually hold quality across 32k. Advertised window and usable window are different numbers. Give the model what it needs and stop there.

Last one for this layer. Open weights and open source are not synonyms, though they get used that way constantly. Open weights means you can download the parameters and run the model yourself. Open source, used strictly, would also mean the training data and code are available, which for most so-called open models they aren't. Llama and Mistral are open weights. Very little meets that second definition.

Layer 2: what turns a model into an agent

A chatbot answers. An agent acts. That's the whole distinction, and everything else in this layer is machinery for making acting safe and useful.

A tool is a function you write, described in a way the model can understand, that the model may choose to call. The model never runs your code. It emits a request to run it, your framework runs it, and the result goes back into the conversation. In the SDK a tool is a class with three methods:

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class LookupOrder implements Tool
{
    public function description(): Stringable|string
    {
        return 'Look up an order and its current status by order ID.';
    }

    public function handle(Request $request): Stringable|string
    {
        return Order::findOrFail($request['order_id'])->toJson();
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'order_id' => $schema->integer()->required(),
        ];
    }
}

The description is not a comment. It's the only thing the model reads when deciding whether to call this tool, so it does more work than the implementation does.

There's a second reason tools exist, beyond reaching the outside world. Models are bad at anything that has to be exact. Dates, arithmetic, counting, sorting. They're producing likely-looking tokens, not calculating, so "what date is 45 working days from today" is a guess. Give it a tool. Deterministic work belongs in PHP, where it's just code.

An agent bundles instructions and tools together:

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class SupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You help customers with order and billing questions.';
    }

    public function tools(): iterable
    {
        return [new LookupOrder, new IssueRefund];
    }
}

The agent loop is what happens when you prompt that class. The model reads the conversation, decides whether to answer or call a tool, and if it calls one, your code runs and the result is appended. Then it starts again. It keeps going until it produces a final answer or hits the limit you set with #[MaxSteps(10)].

Each pass is a step, and the SDK exposes them on the response as $response->steps. Steps are where cost lives, because every step resends the whole thing: system prompt, tool definitions, and every previous call and result. Step five is much more expensive than step one. Not because the model got slower, but because the conversation got longer.

The diagram below is the part I wish someone had drawn for me on day one. The model only ever does one thing, which is decide. Everything else in the loop is code you wrote.

View the interactive component on hafiz.dev

ReAct is the name for making the model write its reasoning before it acts. Reasoning and Acting, shortened into one word. When you see a "thinking" panel in a chat interface, that's this. It works because tokens spent explaining the plan condition the tokens that come after, which makes the tool choice better.

Multi-agent systems put agents inside other agents. In the SDK, an agent becomes callable as a tool by implementing CanActAsTool and giving itself a name and description:

class RefundsAgent implements Agent, CanActAsTool, HasTools
{
    use Promptable;

    public function name(): string
    {
        return 'refunds_specialist';
    }

    public function description(): string
    {
        return 'Decide whether an order qualifies for a refund.';
    }
}

Then a parent agent lists new RefundsAgent among its tools, and delegation is just a tool call. It's elegant. It's also the fastest way to spend money I know of, because every sub-agent carries its own context and its own steps. My honest advice is to reach for it only when one agent's tool list has grown incoherent, not because the architecture diagram looks better. I wrote up the sub-agent patterns in detail if you want the longer version.

Layer 3: what gives it knowledge it wasn't trained on

Models have no memory. None. Every API call starts from nothing, and the illusion of continuity in ChatGPT exists because the interface resends the conversation each time. The first time you call a model from your own code, this is the surprise.

Memory, then, means deciding what to resend. The SDK gives you conversation persistence out of the box:

use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Conversational;

class SupportAgent implements Agent, Conversational
{
    use Promptable, RemembersConversations;
}

$response = (new SupportAgent)->forUser($user)->prompt('Where is my order?');

$next = (new SupportAgent)
    ->continue($response->conversationId, as: $user)
    ->prompt('And the one before that?');

That covers short conversations. Long ones need a strategy, because resending everything eventually collides with both the context window and your budget. Summarising older turns while keeping recent ones verbatim is the common answer, and choosing where to cut is still unsolved.

RAG stands for retrieval augmented generation, and it's a plain idea hidden behind an acronym. Before answering, go and fetch the relevant bits of your own data, put them in the prompt, and let the model answer from those. No retraining. Your support tickets and internal docs were never in the training data, and this is how they get in front of the model anyway.

Making it work is a pipeline. Split documents into chunks, because whole documents are too big and single sentences lose their meaning. Convert each chunk into an embedding, which is an array of numbers representing what the text means rather than what it says. Store them. At query time, embed the question, find the closest stored chunks, and put those in the prompt.

View the interactive component on hafiz.dev

Laravel does all of this natively now, which surprised me when I first went looking. Generating embeddings is one call:

use Illuminate\Support\Str;

$embedding = Str::of('Napa Valley has great wine.')->toEmbeddings();

Storing them is a column type, and an HNSW index keeps similarity search fast as the table grows:

Schema::ensureVectorExtensionExists();

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->text('content');
    $table->vector('embedding', dimensions: 1536)->index();
    $table->timestamps();
});

A vector database is a database built to store those numeric arrays and find the nearest ones quickly. Pinecone and Qdrant are the well-known standalone ones. But you very likely don't need either, because PostgreSQL with pgvector, MariaDB 11.7 or later, and MongoDB all do this from inside your existing database, and Laravel ships the query method:

$documents = Document::query()
    ->where('team_id', $user->team_id)
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley', minSimilarity: 0.4)
    ->limit(10)
    ->get();

Pass a string and Laravel embeds it for you. Note the ordinary where clause sitting next to it, which is the thing a separate vector service makes painful and your own database makes trivial.

Reranking is a cheap trick, and it has done more for my results than anything else in this layer. Retrieve a wide set fast, then have a model reorder the top candidates by actual relevance:

$articles = Article::query()
    ->whereFullText('body', $query)
    ->limit(50)
    ->get()
    ->rerank('body', $query, limit: 10);

I've covered the retrieval side more thoroughly in Laravel search in 2026, including when plain full-text beats all of this.

Layer 4: how it reaches the rest of your system

Tools solve access for your own app. MCP, the Model Context Protocol, solves it for everyone else's.

Anthropic open-sourced it on 25 November 2024, and the official docs describe it as "a USB-C port for AI applications", which is a fair description. Before it, connecting M AI clients to N systems meant writing M times N bespoke integrations. A protocol turns that into M plus N.

An MCP server exposes tools, resources and prompts. An MCP client consumes them. Your Laravel app can be either, and there's a first-party package:

use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/support', SupportServer::class)
    ->middleware(['auth:sanctum', 'throttle:mcp']);

That middleware line deserves more attention than it usually gets. An MCP server is a public API whose consumers are language models, so it needs the same authorisation you'd put on any other endpoint, applied per tool as well as per route. I wrote a whole post on locking one down after realising how many public ones ship wide open.

You'll also see A2A and various agent-to-agent protocols. Several appeared once MCP became popular. Adoption has gone almost entirely one way so far, and agents can already talk through MCP, so I'd wait.

Layer 5: how you stop it hurting you

Guardrails means checking input on the way in and output on the way out. Prompt injection is the reason for the first, where text from a user or a fetched document tries to overwrite your instructions. Reputation is the reason for the second, since a model trained on the internet will occasionally produce something you don't want appearing under your company's name.

In Laravel this is middleware, and it works on both directions in one class:

use Closure;
use Laravel\Ai\Prompts\AgentPrompt;
use Laravel\Ai\Responses\AgentResponse;

class ScreenContent
{
    public function handle(AgentPrompt $prompt, Closure $next)
    {
        abort_if($this->looksLikeInjection($prompt->prompt), 422);

        return $next($prompt)->then(function (AgentResponse $response) {
            Log::info('agent.responded', ['text' => $response->text]);
        });
    }
}

The agent picks that up by implementing HasMiddleware and returning the class from a middleware() method, the same shape as HTTP middleware.

Human in the loop means the agent stops and asks before doing something it can't undo. The SDK makes approval a property of the tool, so the dangerous ones pause and the harmless ones don't:

protected function needsApproval(Request $request): Approval|bool
{
    return $request['amount'] > 5000
        ? Approval::required('Refunds above 5,000 need a human.')
        : false;
}

The agent then returns with hasPendingApprovals() true, you show a human the pending call and its arguments, and you resume with Decision::approve() or Decision::reject(). The full workflow is here, including what happens when generation fails mid-approval.

A sandbox is where you run code the model wrote. If your agent generates and executes anything, it runs in a container that can be thrown away, never on the machine holding your database credentials.

Evals are tests for non-deterministic output. You can't assert on an exact string, so you assert on properties instead: did it call the right tool, is the JSON shaped correctly, does a cheaper model grade the answer as acceptable. Skipping these is the most common mistake I see, because everything feels fine until a model version changes underneath you.

Then cost. Two attributes cover most of it, since not every task needs your best model:

#[UseCheapestModel]
class TagExtractor implements Agent {}

#[UseSmartestModel]
class MigrationPlanner implements Agent {}

You'll see people quote splits like 60/30/10 for cheap, mid and premium models. Treat those as somebody's anecdote rather than a rule. Measure your own totalTokens per task type and route from that. Local models through Ollama are worth testing for the boring high-volume work, where the marginal cost is zero and the quality is often fine.

For watching it in production, the same tools you already use apply. Telescope locally, Pulse or Nightwatch in production, plus SDK middleware logging prompts and token counts per run.

What to build first

Reading about this does very little. The path that worked for me was small and boring, in this order.

A tool that adds two numbers. Pointless in itself, and the fastest way to see that the model decides when to call it and your PHP does the work.
A tool that hits your own database. Read-only. Now the model can answer questions about real data, and you'll immediately want to constrain what it can see.
Turn on conversations. Add RemembersConversations and watch your token count per message climb as history accumulates. This teaches context cost better than any article.
Add an approval gate. Give a tool a needsApproval that fires, and build the screen that shows a pending call.
Then RAG. Embed a folder of markdown, store it with vector, query it with whereVectorSimilarTo. Doing it manually once is worth more than any framework tour.

Only after that should you look at sub-agents or MCP. Both are much easier to reason about once you've felt where the tokens go.

What I'd skip

Multi-agent architectures, for most applications. The demos look impressive and the bills are real. One agent with a well-described set of tools beats a hierarchy of specialists for the majority of what people actually build, and you can always split later.

Standalone vector databases, unless you've measured a reason. Your Postgres already does this, and keeping vectors next to the rows they belong to means you can filter by team, tenant or status in the same query.

Chasing new protocols. MCP took hold because it solved an actual integration problem and shipped SDKs. Most of what followed is positioning.

What I wouldn't skip is evals and token logging. They're boring, and they're the difference between an agent you can change with confidence and one nobody wants to touch.

FAQ

Do I need Python for any of this?

No. Everything in this post runs in PHP through the Laravel AI SDK, including embeddings, vector search, reranking and MCP servers. Python dominates model training and research. Application work, which is what most of us are doing, has first-party PHP support now.

Do I need a vector database like Pinecone or Qdrant?

Probably not. PostgreSQL with pgvector, MariaDB 11.7 or later, and MongoDB all store vectors and run similarity search, and Laravel's whereVectorSimilarTo works against them directly. Keeping vectors in your main database also means normal where clauses compose with similarity search, which is awkward when your vectors live in a separate service. Reach for a dedicated one when you've outgrown that, not before.

Is RAG still worth it now that context windows are so large?

Yes, for two reasons. Cost, because retrieving five relevant chunks is far cheaper than sending an entire knowledge base on every request. And quality, because Chroma's context rot research shows accuracy falling as input grows, even well inside the advertised window. Less relevant context beats more context.

What's the difference between open source and open weights?

Open weights means the parameters are downloadable, so you can run the model on your own hardware. Open source, taken literally, would also require the training data and pipeline, which almost no widely used model provides. Most models described as open are open weights. For running something locally the distinction rarely matters, but the words aren't interchangeable.

The thing worth remembering

Go back through the terms and you'll notice they fall into two buckets. Some describe next-token prediction and its consequences, which covers tokens, temperature, context windows and hallucination. The rest describe plumbing you write yourself: tools, memory, retrieval, approval gates, guardrails.

There's no third bucket. Nothing in the list is a machine that thinks. That's why an agent with no tools can't do anything, why it's bad at arithmetic until you hand it a calculator, and why the interesting engineering is almost entirely in the second bucket.

Which is good news for us, honestly. The second bucket is just software, and you already know how to write that.

Your Query Bindings Are in Your Logs: Laravel 13.27 Can Mask Them, and How to Clean Up What Leaked

Hafiz — Wed, 02 Sep 2026 04:15:11 +0000

Originally published at hafiz.dev

Here is something most Laravel developers have never noticed. When a database query fails, Laravel takes the SQL, fills in the real values, and puts the whole thing into the error message. Every value. The email someone just typed into your signup form, the name, the password hash, the API token you were saving. That message then goes wherever your errors go, and it stays there.

I'd been writing Laravel for years before I looked at this properly. Laravel 13.27, released on 26 August 2026, adds a one-line switch that turns it off. This post explains what the leak looks like, why the switch doesn't work the way the announcement suggests, and how to find and delete what's already in your logs.

What a failed query actually writes

Let me show you rather than describe it. A fresh Laravel 13.29 app, SQLite, the default users table with its unique index on email. Create a user, then try to create the same one again:

User::create(['name' => 'Mario Rossi', 'email' => 'mario.rossi@example.com', 'password' => 'secret-password']);
User::create(['name' => 'Mario Rossi', 'email' => 'mario.rossi@example.com', 'password' => 'secret-password']);

The second call throws a QueryException (a UniqueConstraintViolationException, to be exact). This is its getMessage(), straight from the terminal:

SQLSTATE[23000]: Integrity constraint violation: 19 UNIQUE constraint failed: users.email
(Connection: sqlite, Database: /var/www/app/database/database.sqlite,
SQL: insert into "users" ("name", "email", "password", "updated_at", "created_at")
values (Mario Rossi, mario.rossi@example.com, $2y$12$hR9..., 2026-08-29 08:57:42, 2026-08-29 08:57:42))

The query you wrote had five ? placeholders. The message has the five real values in their place. Laravel does this on purpose, because a message with the values in it is much easier to debug. That's true. It's also a copy of your user's personal data, in plain text, inside an error string.

Where that string ends up

An exception message doesn't stay in memory. It gets written down, usually in more places than you think.

storage/logs/laravel.log. If the exception isn't caught, the handler logs it. In my test the log line was local.ERROR: SQLSTATE[23000] ... followed by the full message, email included. Log files get rotated, backed up, rsynced to other servers, and sometimes shipped to a logging service. Each copy carries the data.

The failed_jobs table. This one surprised me. The exception column is a longText that stores the whole exception chain as a string. I dispatched a job that hit the same unique index, ran queue:work --once, and queried the table:

DB::table('failed_jobs')
    ->where('exception', 'like', '%mario.rossi@example.com%')
    ->count(); // 1

The row contains the PDOException, then "Next Illuminate\Database\UniqueConstraintViolationException" with the full SQL and every value. Failed jobs are kept for 24 hours by default if you prune them, and forever if you don't. Most apps don't.

Error trackers. Sentry, Bugsnag, Flare, Nightwatch. They all receive the exception message as the headline of the event. Sentry's default server-side scrubbing removes values in fields named password, secret, token and so on, and anything that looks like a credit card number. An email address sitting in the middle of a SQL string in a free-text message is not on that list. So it goes through, and it sits in a third party's database under their retention policy.

Telescope, Slack alerts, email notifications. Anywhere you've wired exceptions to go.

None of this is a bug. It's the default behaviour doing exactly what it says. But if someone asks you "where is customer data stored?" and your answer doesn't include "the error log and the failed_jobs table", the answer is incomplete. If you deal with GDPR, personal data with no retention limit in a log file is exactly the kind of thing an audit finds.

The switch in Laravel 13.27

Laravel 13.27 adds a per-connection config key, contributed by Lau Josefsen in PR #61326:

'mask_bindings_in_exception_messages' => env('DB_MASK_BINDINGS', false),

With it on, the same failure produces this message:

SQLSTATE[23000]: Integrity constraint violation: 19 UNIQUE constraint failed: users.email
(Connection: sqlite, Database: /var/www/app/database/database.sqlite,
SQL: insert into "users" ("name", "email", "password", "updated_at", "created_at")
values (?, ?, ?, ?, ?))

The placeholders stay as placeholders. Nothing else changes. The query still fails the same way, the exception is the same class, and the values are still available on the exception object if you need them (more on that below). Only the message is different.

It's off by default, so you won't get it unless you turn it on.

The part the announcement gets slightly wrong

The release notes say the key ships in the framework's own config/database.php, so apps can enable it with DB_MASK_BINDINGS=true in .env and nothing else. I tried exactly that on a fresh app and it did nothing. The message still had the values in it.

The reason is that every Laravel app has its own published config/database.php, and that file doesn't contain the new key. Laravel does merge your config with the framework's defaults, and for database it even merges the connections list. But each connection you define replaces the framework's version of that connection wholesale. Your mysql array wins over the framework's mysql array, and yours doesn't have the key. So config('database.connections.sqlite.mask_bindings_in_exception_messages') came back null, and null means off.

The fix is to add the line to each connection you use:

'mysql' => [
    'driver' => 'mysql',
    'mask_bindings_in_exception_messages' => env('DB_MASK_BINDINGS', false),
    // ...
],

Then set DB_MASK_BINDINGS=true in .env, clear the config cache, and it works. I verified this by checking config() before and after. If you skip the config edit, the env var is silently ignored, which is the worst kind of security setting: one that looks on and isn't.

Cleaning up what's already there

Turning on masking only changes exceptions from now on. Everything that failed before today is still written down. Three places to look.

Failed jobs. Count how many rows contain something that looks like an email:

DB::table('failed_jobs')
    ->where('exception', 'like', '%@%.%')
    ->count();

Then decide. If those jobs are old and you're never going to retry them, delete them all with php artisan queue:flush. If some are worth keeping, prune by age instead: php artisan queue:prune-failed --hours=48. And put that prune command on the scheduler so the table stops being a permanent archive.

Log files. A quick search over whatever is still on disk:

grep -cE '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' storage/logs/*.log

That counts lines with an email-shaped string per file. Delete the old files or let rotation do it. If you're still on the single log channel, switch to daily and set LOG_DAILY_DAYS to something short. The default is 14. And check where else those files went: server backups, a log shipper, a colleague's laptop after a debugging session.

Error tracker. Search your Sentry or Bugsnag project for insert into and @. You can delete individual events and set a shorter retention window. For anything sensitive that went through, the honest step is to treat it as a small incident and note it, because the data left your servers.

What you lose, and how to get it back

Masked messages are harder to debug from a log line alone. When a job fails at 2am and the log says values (?, ?, ?), you can't see which row caused it. That's a real cost, and it's why the setting is off by default.

You don't lose the data, though. The QueryException object still carries everything:

try {
    $user->save();
} catch (QueryException $e) {
    $e->getSql();       // the query with ? placeholders
    $e->getBindings();  // the real values, as an array
    $e->getRawSql();    // the query with values filled in, properly quoted
}

So the pattern is to keep the values out of the places that persist for a long time and are hard to control (log files, failed_jobs, third-party trackers), and reach for getBindings() in the places where a person is actively debugging, behind authentication. Telescope, Pulse or Nightwatch are the right home for that kind of detail, because they sit behind your login and you control their retention. A log file on disk doesn't have either.

For queue jobs specifically, log the identifier rather than the payload. A failed() method on the job that writes "ImportUser failed for row 4812" tells you what to look at without copying the row into the exception column. If you've read my post on processing 10,000 queued tasks without breaking, this is the same idea from a different angle: the job should carry an ID, not the data.

FAQ

Does this affect Laravel 12 or older?

No. The config key exists from Laravel 13.27 onwards. On older versions the values are always interpolated. If you're on 12 and can't upgrade yet, the practical options are to catch QueryException where personal data flows through, rethrow with a cleaner message, and prune failed_jobs aggressively.

Will masking change how my error tracker groups events?

No. Sentry, for example, groups an exception by its stack trace when one is present, and only falls back to the message text when it has nothing better. Two QueryExceptions from the same line group together whether the message contains real values or placeholders. What changes is the title you see on the issue, and a title with (?, ?, ?) in it is the one you want on a screen other people can see.

Does it hide the values from `dd()` or the debug page in local development?

No. Only the exception message changes. The debug page shows the exception object, and getBindings() still returns the array. Local debugging is unaffected. You can also leave DB_MASK_BINDINGS=false in your local .env and set it to true only in production.

Is this a GDPR requirement?

GDPR doesn't name log files, but it does require that personal data isn't kept longer than needed and is protected appropriately. A log file with no retention limit, copied to backups, containing emails and names, is hard to defend on either point. Masking plus a short log retention is a cheap way to close the gap.

The one line, and the second one

Add 'mask_bindings_in_exception_messages' => env('DB_MASK_BINDINGS', false) to every connection in config/database.php, set DB_MASK_BINDINGS=true in production, and clear the config cache. Then spend ten minutes on queue:flush and your old log files. The switch stops the leak going forward. The cleanup is the part that actually removes the data, and it's the part people skip.

How I Turned a €5 VPS Into a Dev Workstation I Can Use From Anywhere

Hafiz — Mon, 31 Aug 2026 04:15:12 +0000

Originally published at hafiz.dev

I wanted to work on my projects from wherever I happen to be. At the desk on the Mac, on the train from my phone, on a borrowed laptop if it came to that. Not just check on things, but write code, review what an AI agent did, and deploy it. A laptop-only setup can't do that, and it has a second problem that's easy to ignore until it bites. The laptop is a single point of failure. Earlier this month a quick check showed finished work on a few projects that existed on exactly one machine, with no copy anywhere else.

So I built the alternative. One cheap VPS is the workstation, and every device I own is just a window onto it. I'd written about coding PHP from a phone back in May, but that was one project on one box. This is the version that holds up for a dozen projects, with an AI agent doing most of the typing.

Everything below was built between 25 and 28 August 2026, in three days of evenings. It's a blueprint, not a tour. Follow it and you end up with the same setup. The part nobody publishes, the table of everything that broke along the way, is near the end, and it's the section I'd bookmark.

The idea: one box, many windows

One cheap VPS is the workstation. The MacBook and the iPhone are just windows onto it.

tmux keeps every session alive on the server, one session per project. Claude Code runs inside those sessions and does the actual work. Every project gets a private staging URL so I can look at what it did from any browser. Close the laptop, lock the phone, lose the train's Wi-Fi. Nothing happens to the work, because nothing was running on the device.

View the interactive component on hafiz.dev

The setups you see on Twitter (levelsio's is the famous one) mostly stop at "tmux on a server, Termius on the phone". That part takes an hour. What took three days was making it hold up for many projects, with private HTTPS staging, an agent with shell access, and a way to rebuild the whole thing from a repo. That's what this post is about.

The stack, and why each piece

Piece	Choice	Why this one
Box	netcup VPS Lite 1 G12s, €5/mo incl. VAT	2 vCore, 4 GB RAM, 80 GB SSD. 4 GB is the binding constraint, not disk. 2 GB does not fit Claude Code plus a build plus staging sites
OS	Debian 13	The provider's default. Ships PHP 8.4, so PHP 8.3 comes from Sury's repo
Network in	Tailscale only	Port 22 is firewalled to the tailnet's `100.64.0.0/10` range. There is no public SSH port at all
Sessions	tmux, one session per project	Each keeps its own windows, scrollback and running Claude Code. Switching projects disturbs nothing
Web	Caddy on loopback + php-fpm	Caddy listens on `127.0.0.1:80` only. One config file per project, generated by a script
Staging	Cloudflare Tunnel + Cloudflare Access	Outbound tunnel, so no inbound port. Access puts an email one-time PIN in front of every staging URL
Agent	Claude Code on the box	The sessions show up in the Claude desktop and iOS apps too, which solves screenshots (more below)
Phone	Termius	One host entry per project, each with a startup snippet that lands in the right tmux session

Two of those deserve a sentence more.

Why Tailscale instead of a hardened public port. I did the public-port version on another box and wrote it up in How I Hardened My VPS in One Afternoon. This time I skipped straight to closing the port. In the few hours between provisioning and the firewall rule going in, sshd logged 1,904 failed login attempts on a box that didn't exist the day before. In the 18 hours after the rule: zero. No fail2ban, because there's nothing for it to react to. The way back in if Tailscale ever breaks is the provider's web console, which doesn't depend on the network path.

Why a tunnel and not just Tailscale for staging. Security is roughly a third of the reason. The rest is that some of my projects have OAuth callbacks, Stripe webhooks and payment flows, and none of those will talk to http://. The tunnel gives real certificates on real hostnames with no open port and no Let's Encrypt dance. It also works from a phone browser without the Tailscale app, and a staging link can be sent to a client.

The blueprint

The rule that governs the whole build is simple. Anything typed on the box goes into a git repo first, then onto the box. Four provisioning scripts, a handful of commands in bin/, the systemd units, the panel source. The box must always be rebuildable from that repo, because a VPS at this price is not something to get attached to.

Provisioning: four scripts and four manual steps

Run in order, each idempotent, so re-running is safe.

./scripts/00-ssh-bootstrap.sh <ip> devbox   # local: dedicated key, pin host key, harden sshd
ssh devbox 'bash -s' < scripts/01-base.sh   # packages, 2G swap, ufw, unattended upgrades
# MANUAL.md steps 1 and 2: Tailscale join, Cloudflare tunnel login
ssh devbox 'bash -s' < scripts/02-stack.sh  # PHP 8.3, Node 22, Composer, Playwright path
ssh devbox 'bash -s' < scripts/03-caddy.sh  # Caddy bound to loopback
ssh devbox 'bash -s' < scripts/04-tunnel.sh # cloudflared as a service

The SSH bootstrap generates a key just for this box, pins the host key before the first real connection, verifies key auth works, and only then disables password login:

PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin prohibit-password
MaxAuthTries 3

The base script is where the firewall rule lives. Tailscale and cloudflared are both outbound, so this is the entire inbound policy:

ufw default deny incoming
ufw default allow outgoing
ufw allow from 100.64.0.0/10 to any port 22 proto tcp comment "SSH via Tailscale"
ufw --force enable

It also adds git config --global --add safe.directory "*", and you'll see why in the gotchas table.

The stack script sets php-fpm to pm = ondemand with a 30 second idle timeout. That single line is what makes "eight staging sites up at once" cheap. An idle pool spawns no workers, so a registered-but-unused project costs nothing until someone requests a page.

Four things genuinely cannot be scripted, and the repo says so instead of pretending. Tailscale needs a browser login on the same tailnet as your other devices. The Cloudflare tunnel needs cloudflared tunnel login. Claude Code needs its account authentication. And .env files are copied per project, by hand, never from git.

The three commands you'll actually use

Everything day to day goes through three small bash scripts installed to /usr/local/bin.

p                      # list projects, staging URLs, which sessions are running
p prompt-optimizer         # jump into that project's tmux session, already cd'd

dev up prompt-optimizer    # serve at prompt-optimizer-staging.hafiz.dev, create DNS if new
dev down prompt-optimizer  # stop serving, free its php-fpm workers
dev list               # what is up, plus memory and worker count
dev logs prompt-optimizer  # follow that project's requests

project-setup <name> <git-url>   # clone and bootstrap a new project

p is the one that changes how the box feels. It creates the session if it doesn't exist, detached, then either attaches to it or, if you're already inside tmux, switches your client over. No detaching, no cd, no remembering session names. The one wrinkle worth knowing: tmux switch-client needs the real client, so the script reads #{client_tty} and passes it with -c. Without that, running it from a Termius snippet silently does nothing.

dev up writes one Caddy vhost per project. This is the whole file:

http://prompt-optimizer-staging.hafiz.dev {
    root * /var/www/prompt-optimizer/public
    encode gzip
    php_fastcgi unix//run/php/php8.3-fpm.sock {
        env HTTPS on
    }
    file_server
}

Note env HTTPS on. TLS terminates at Cloudflare and the tunnel hands Caddy plain HTTP, so without that line Laravel thinks the request is insecure and generates http:// asset URLs. Every XHR on the page then fails with mixed-content errors. That one cost me an evening.

dev up also creates the DNS record on first run, through cloudflared tunnel route dns, and then leaves it alone. dev down removes the vhost but keeps the DNS, because Cloudflare rate-limits record churn and there's no reason to delete it.

Staging behind Cloudflare Access

Here's the full path of a request to a staging site. The point of the diagram is what's missing: there is no arrow into the VPS from the internet.

View the interactive component on hafiz.dev

cloudflared makes an outbound connection to Cloudflare and keeps it open. Requests for *-staging.hafiz.dev arrive through that connection and get handed to Caddy on the loopback interface. Caddy talks to php-fpm over a Unix socket. Nothing on the box has a port open to the world.

In front of all of it sits one Access application in Zero Trust: subdomain *-staging, domain hafiz.dev, policy "Allow", selector "Emails", one address. Every staging URL then asks for a one-time code by email before serving a byte. I verified it from outside rather than assuming: an unauthenticated request returns a 302 to the sign-in page with zero application content in the body, while the same site serves normally when curled on the box. The free Zero Trust plan is more than enough for one person.

The hostname shape is not a style choice. I wanted prompt-optimizer.dev.hafiz.dev. It fails the TLS handshake with sslv3 alert handshake failure, even with DNS and the tunnel healthy, because Cloudflare's free Universal SSL covers one subdomain level only. Two levels deep needs Advanced Certificate Manager, a paid add-on. And *-dev.hafiz.dev looks like a wildcard but isn't one. DNS wildcards only work as a leading *., so Cloudflare treats that asterisk literally and it never matches anything. So it's <project>-staging.hafiz.dev, one CNAME per project, created by dev up. With fifteen projects that's fine.

Migrating a project onto the box

project-setup <name> <git-url> does the boring part and refuses to do the dangerous part:

Clone into /var/www/<name>, or fast-forward pull if it's already there
Create the storage/framework/* skeleton, because not every repo tracks it
composer install, with --no-scripts if there's no .env yet (more on this below)
npm install and npm run build
If .env exists: key:generate if needed, migrate --force, storage:link
chown -R www-data:www-data, group-writable, setgid on directories

Then the manual steps, deliberately manual:

Copy the .env, and decide per token. A token that can write to production only goes on the box with a reason. Most of them stay blank, so if the box is ever compromised the blast radius stays small.
Copy the SQLite database.
rsync storage/app/public from the production box, not from the laptop. The laptop copy is missing every image production generated since you last pulled. On one project the local copy was 32 MB and production was 71 MB.
chmod g+rwX storage/app after that rsync, because -a preserves production's restrictive directory permissions and the Caddy user can't traverse into a 700 directory.
dev up <name>.

A project is verified when three things are true: curl on the box returns 200, the public staging URL returns 302 to Access, and a page loads content from the real database.

Eight projects went through this in three days. The ones I parked (four of them, no active work) are a fifteen-minute job each when one wakes up, which is the point of writing the procedure down.

Working from the phone

This is the part I built all of it for. The pattern comes from levelsio: instead of one SSH host and a tmux menu, Termius gets one host entry per project. Same address, same key, but the label is the project name and the startup snippet is p <name>. A fresh SSH connection isn't inside tmux yet, so p attaches directly and every project becomes a tap-to-open tab.

The plain devbox host stays for box-wide work and attaches a shared work session. Only projects that have earned it get their own entry.

Four snippets cover everything else:

Snippet	Script
`attach work`	`[ -n "$TMUX" ] \
{% raw %}`claude`	`claude --continue`
`detach`	`tmux detach`
`dev list`	`dev list`

And the tmux config on the box is short. mouse on so finger-scrolling works, focus-events on, a 20,000 line history, and the session picker bound to s.

Switching projects while Claude Code is running. p <name> only works at a shell prompt. With Claude Code in the foreground it owns the input line, so typing p hafiz-dev just sends "p hafiz-dev" to Claude as a message. Only two things reach tmux past a running application: the prefix key, which tmux intercepts at the terminal layer, and mouse events. So the switch is Ctrl+B then S, which opens the session picker. On the phone, ctrl is a key in the Termius toolbar. Tap it, press b, press s. Verified working through Claude Code, over 4G.

I tried binding a status-bar tap to the picker so switching would be one touch. Termius on iOS treats the touch as a text-selection gesture and shows its own Copy/Paste menu instead of forwarding a mouse event. Binding removed. The prefix works.

Screenshots into Claude. Raw paste into Claude Code over SSH does nothing, because the image is on the phone's clipboard and the CLI is on the server. The fix is to not use the terminal for that. Sessions running on the box show up in the Claude iOS and desktop apps, grouped by project. Open the session there, attach the image natively, and it travels through Claude's own infrastructure. For the rare case where the file needs to physically exist on the box (a fixture, an asset), the iPhone share sheet to Tailscale drops it into an inbox directory via Taildrop.

Three equivalent ways to leave. Close Termius. Lock the phone. Or Ctrl+B D if you want to be tidy. tmux notices the connection drop, detaches, and everything keeps running. Termius shows a persistent "One connection" notification while it holds the SSH session open for fast reconnects. Harmless. The only thing that loses work is typing exit inside a session, because that's the one action that destroys it.

The proof this works came on day two: a footer change written on the phone over 4G, reviewed, corrected, committed and deployed to a live site. Since then the two-machine problem has mostly dissolved, because there is one checkout. From the Mac, dp prompt-optimizer attaches the same session the phone uses. Nothing to reconcile.

The control panel

By day three there were eight staging sites and a growing number of Claude Code instances, and "what's running right now" needed an answer that didn't involve SSH. So the box serves one more Access-protected page, on the same staging pattern as everything else. It shows memory, disk, load, each project with its staging state, every tmux session with a claude/idle badge, every Claude process with its working directory and RSS, and which repos are out of step with their remotes. Then buttons: start and stop per staging site, and "start CC" on any idle session.

Putting buttons on a web page that runs shell commands on a box with production deploy keys is exactly the kind of thing that goes wrong. The design has three paths, and each one needs less privilege than the one before it.

View the interactive component on hafiz.dev

Status is read-only. A root systemd timer runs a Python script every 30 seconds that collects everything and writes status.json with a 0644 mode. The page fetches that file every 15 seconds and renders it. The web layer executes nothing for status. If the file goes stale, the page says so.

Actions go through the narrowest sudo I could write. The start/stop buttons POST to a small PHP file. It refuses anything without a custom X-Panel header (browsers won't send custom headers cross-origin without a CORS preflight, which is never allowed), validates the project name against ^[a-z0-9][a-z0-9-]{0,31}$, checks the directory exists under /var/www, refuses the name panel so it can't saw off its own branch, and only then runs sudo dev up|down <name>. The sudoers rule grants www-data exactly that: one binary, two verbs, a name matching a character class, plus the status refresh. Nothing else. php-fpm runs under systemd's ProtectSystem=full, with a drop-in that makes exactly one directory writable, the one Caddy vhosts live in.

Starting Claude Code needs no sudo at all. This is the path I'm happiest with. The button writes a project name into /var/spool/panel/cc-start and returns. A systemd path unit, running as root, watches for that file. When it appears, a consumer script re-validates the name from scratch, checks the tmux session exists, checks that the foreground process in that session is a bare shell (never a running Claude, never an editor), and types claude --continue || claude into it. The web layer left a note. Root decided what to do with it.

Two things the consumer had to learn. Inside a systemd unit, tmux's -t "=name" target form fails with "can't find pane" while plain -t name and list-panes -a work, so it uses those. And claude --continue on a large old conversation shows a resume picker that self-cancels when no client is attached, exiting 0, so the || claude never fires. The script waits six seconds, checks whether Claude is actually running, and starts a fresh conversation if not. The old one stays resumable from a real terminal.

Stopping Claude Code is deliberately not a button. That stays a human act, from a terminal or the Claude app.

If you run an agent with shell access anywhere near production keys, this earlier post on keeping it from destroying your app covers the project-level guardrails. The panel is the box-level version of the same instinct: every new action gets a header check, strict validation, and the least privilege that can possibly do the job, and the spool-file pattern beats a new sudoers line every time.

Everything that broke

This is the table I wish someone had published before I started. Every row cost real time.

Symptom	Cause	Fix
500 on every page of a fresh project	Checkout was root-owned and php-fpm runs as `www-data`. Laravel writes to `vendor/` during package discovery, not just `storage/`	`project-setup` chowns the whole tree to `www-data`, group-writable, setgid dirs
`dubious ownership` on every git command	Checkouts owned by `www-data`, git runs as root	`git config --global --add safe.directory "*"` in the base script
`deploy.sh` can't reach production	The box's SSH key wasn't on the production servers. This is per box, and I have three	Add the devbox public key to each production box's `authorized_keys`
Staging URL fails TLS with `sslv3 alert handshake failure`	Free Universal SSL covers one subdomain level. `foo.dev.hafiz.dev` is two deep	Hostnames are `<project>-staging.hafiz.dev`
`*-dev.hafiz.dev` wildcard matches nothing	DNS wildcards only work as a leading `*.`. The asterisk mid-label is literal	One CNAME per project, created by `dev up`
`Ctrl+B D` seems dead on the phone	Mistimed keystrokes, not interception. The prefix does reach tmux	Slow down
`project-setup` dies in composer on a fresh clone	`package:discover` boots the app, and a service provider that needs a secret throws with no `.env` (a Stripe service in one project)	`composer install --no-scripts` until `.env` exists, then re-run
"Please provide a valid cache path" on a fresh clone	The repo didn't track `storage/framework/*`, so the view compiler had nowhere to write	`project-setup` creates the storage skeleton before composer runs
New staging URL dead in the browser for about 30 minutes	The resolver in the path (the carrier DNS behind an iPhone hotspot) cached NXDOMAIN from a lookup made before `dev up` created the record. Negative TTL was 1800 seconds, and flushing the Mac can't clear an upstream cache	Set the interface DNS to `1.1.1.1`, or wait it out
Mixed-content errors on every staging XHR	TLS ends at Cloudflare, the tunnel delivers plain HTTP, so Laravel generated `http://` URLs	`env HTTPS on` in every Caddy vhost
`site.webmanifest` CORS errors on staging	Browsers fetch manifests without cookies, so the request can't carry the Access session and gets redirected to the login page	Cosmetic. Inherent to Access-protected staging, ignore it
Uploaded images 403 on staging	Two causes stacked: `storage:link` never ran, and `storage/app/public` is data git doesn't carry	`project-setup` runs `storage:link`. Rsync the directory from production, not the laptop
Images still 403 with correct file permissions	`storage/app` itself was `700`, so the `caddy` user (group `www-data`) couldn't traverse into it. `rsync -a` preserves production's restrictive directory modes	`chmod g+rwX storage/app` after any rsync from production
Playwright can't launch Chromium in one project	Browser builds are version-pinned. The project's `playwright-core` wanted build 1208, the box had 1234	`node node_modules/playwright-core/cli.js install chromium` from that project
`tmux send-keys -t "=name"` fails inside a systemd unit	"can't find pane" for the `=` exact-match form when no client is attached	Use plain `-t name`, and `list-panes -a` with a filter
`claude --continue` from the panel does nothing	On a large conversation it shows a resume picker that self-cancels with exit 0 when no client is attached	Re-check after six seconds and start fresh if Claude isn't running

The Termius status-bar tap that never worked belongs in the same spirit but didn't cost enough to earn a row.

What it costs and what it feels like

€5 a month, billed six months at a time, so €30 up front. That's the whole bill. For comparison, my main production server is a small box running several sites, and I'd never run a build or an agent there, which is the same reasoning behind separating environments that applies to any small setup.

Memory is the number that matters on a 4 GB box, so here's what it actually uses. Baseline with eight staging sites up and nothing else running: about 840 MB. That includes the OS, Caddy, cloudflared, Tailscale, php-fpm pools that spawn no workers while idle, and the panel's timers. Each Claude Code instance adds roughly 450 MB, and that is the only thing that scales with how much you're doing. Three projects with Claude open is comfortable. Six would not be. The 2 GB swap file exists for composer install and npm run build, each of which can spike past 500 MB, and OOM mid-task from a phone is the failure I most wanted to avoid.

Disk was never the constraint. The active projects total under 6 GB, and most of that is vendor/ and node_modules/ that rebuild from lockfiles.

Latency from Turin to Vienna, where the box landed, is around 20 ms. Typing over SSH feels local. My Helsinki box, at about 40 ms, feels like typing through syrup by comparison, and that difference is a good part of why this got a new box rather than sharing an existing one.

The rebuild story is the one I care about most. Everything that defines the box is in one repo, and the box's own checkout of that repo is where the panel gets deployed from. If netcup vanished tomorrow, the recovery is order a box anywhere, run four scripts, do the four manual steps, run project-setup per project, copy secrets. About an hour, plus rsync time for databases. I moved a live SaaS between servers with two minutes of downtime earlier this month using the same "write it down as you go" habit, and it's the habit, not the scripts, that makes a box disposable.

What it feels like is harder to put in a table. The honest version is that reviewing works on a phone and debugging doesn't. Reading a diff, approving a plan, running a deploy, fixing a typo: all fine from a train. Stepping through a failing test on a phone keyboard is miserable, and that's exactly the moment you'll want a real screen. So the Mac still does the heavy work. It just does it as another window onto the same session, which means closing the lid mid-task is free, and the audit script hasn't found stranded commits since.

FAQ

Why not just use Tailscale for the staging sites too?

Because some of my projects have OAuth callbacks and Stripe webhooks, and those refuse to talk to http:// or to a private address. The tunnel gives valid certificates on real hostnames with no open port, works from any browser without a Tailscale client, and lets me send a staging link to someone else. Tailscale carries SSH, the tunnel carries HTTPS. They're complements, and for a project with no third-party callbacks Tailscale alone would do.

Does Claude Code keep running when the phone disconnects?

Yes, and that's the whole point of tmux. Claude Code runs inside a tmux session on the server. When the SSH connection drops, tmux detaches the client and the session keeps running. Reconnect from any device and it's still there, mid-task. The only way to lose work is to type exit inside the session.

How do you switch projects while Claude Code is in the foreground?

Ctrl+B then S opens tmux's session picker. The prefix key reaches tmux before any application sees it, so it works even while Claude Code owns the input line. Typing a command into the terminal at that point doesn't work, because the characters go to Claude as a message. On the phone, ctrl is a key in the Termius toolbar.

Isn't putting production deploy keys on a box with a web-controlled agent dangerous?

It's a trade, and it's made deliberately. The box can deploy to production because that's what makes it a workstation. What limits the damage is that .env tokens are copied per project with a reason for each, most of the ones that can write to live sites stay blank, and the panel's actions are validated three times over with the narrowest sudo rule that works. The start-Claude path needs no sudo at all. The remaining risk is an agent with shell access, which is the same risk on the laptop.

What happens if Tailscale breaks and there's no public SSH port?

The provider's web console. It's a VNC session into the box that doesn't depend on the network path at all, which is why I didn't keep a public port open as a fallback. Closing the port is strictly stronger than banning attackers who reach it.

The mental model in one line

Conversations live on the server. You carry glass.

Every design decision above follows from that. Sessions persist because they never ran on the device. Staging is private because the only way in is a tunnel that dials out. The panel can be trusted because the web layer only ever reads a file or leaves a note. And the box is disposable because everything that made it is in a repo, next to a table of what went wrong the first time.

NativePHP v4: Build a Truly Native iOS Screen in Blade, No Xcode Required

Hafiz — Wed, 26 Aug 2026 04:15:09 +0000

Originally published at hafiz.dev

When I wrote my first NativePHP mobile tutorial, the honest caveat sat in the middle of the post: your Laravel app was running in a webview. A good webview, with real native APIs a bridge call away, but still a browser pretending to be an app.

NativePHP v4 removes the pretence. Blade components now render as real SwiftUI views on iOS and Jetpack Compose views on Android. No webview, no HTML, no JavaScript bridge. The engine is called SuperNative. It debuted at The Vibes, the unofficial extra day of Laracon US, hit Laravel News in mid August, and I have now built and run a screen with it on a real iPhone.

This post is that build, start to finish, including the parts where I hit a wall. And the best bit for anyone who bounced off mobile development before: I never opened Xcode.

What SuperNative actually does

NativePHP ships its own Blade engine. Instead of compiling your components to HTML, it converts them into a compact binary representation of a UI tree and hands that directly to the native shell. PHP and the native layer share memory, so there is no network hop and no bridge round-trip between your component and the screen.

On iOS that tree becomes SwiftUI views. On Android it becomes Jetpack Compose. Your Blade file is the single source of truth for both.

The mental model is Livewire. A screen is a PHP class with public properties and methods. The view is Blade. When a property changes, the screen re-renders. If you have written a Livewire component, you already know how to write a NativePHP screen.

The setup, and the first wall

Two requirements before anything works:

PHP 8.4. v4 requires it, and this is the first wall I hit: my machine defaulted to PHP 8.3 and composer require failed with a clear enough constraint error. On a Mac with Homebrew, brew install php gets you 8.4 without touching your default PHP. Point Composer at it explicitly if you keep 8.3 as your daily driver.
The starter kit currently scaffolds v3. laravel new my-app --using=nativephp/mobile-starter gave me nativephp/mobile 3.3.7. One extra require fixes it.

laravel new watch-later --using=nativephp/mobile-starter
cd watch-later
composer require "nativephp/mobile:^4.2"

That second command is the actual v4 upgrade. It ran clean for me, which matches the upgrade guide's claim that v4 is additive and needs no application code changes.

Build the screen

The demo is a Watch Later list, the native cousin of the Telegram watch-later bot I built earlier this year. A list of saved videos, tap a row to mark it watched, a running total of queued minutes.

v4 ships a generator that creates both halves of a screen:

php artisan native:make WatchList

That gives you app/NativeComponents/WatchList.php and resources/views/native/watch-list.blade.php, plus the route line to paste:

use App\NativeComponents\WatchList;

Route::native('/', WatchList::class);

Route::native() is the mobile sibling of a Livewire route. Parameters work like web routes, so Route::native('/video/{id}', VideoDetail::class) matches a path segment and the screen reads it with $this->param('id').

The data layer is just Laravel

A full PHP runtime with SQLite runs on the device, so the model and migration are exactly what you would write in any Laravel app:

Schema::create('videos', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->string('channel');
    $table->unsignedSmallInteger('minutes')->nullable();
    $table->boolean('watched')->default(false);
    $table->timestamps();
});

One on-device quirk worth knowing: there is no db:seed on the phone. Migrations run once on app start, so starter data goes into the migration's up() method as plain inserts. It feels wrong for about a minute and then makes complete sense.

The component

namespace App\NativeComponents;

use App\Models\Video;
use Illuminate\View\View;
use Native\Mobile\Edge\NativeComponent;

class WatchList extends NativeComponent
{
    public function toggleWatched(int $id): void
    {
        $video = Video::findOrFail($id);
        $video->watched = ! $video->watched;
        $video->save();
    }

    public function render(): View
    {
        $videos = Video::orderBy('watched')->latest()->get();

        return view('native.watch-list', [
            'videos' => $videos,
            'queuedMinutes' => $videos->where('watched', false)->sum('minutes'),
        ]);
    }
}

Eloquent, on a phone, feeding SwiftUI. That sentence still feels strange to type.

The view

The view uses EDGE elements, Blade tags under the native: namespace that map one-to-one onto native UI. Styling is Tailwind utility classes, parsed by the engine into native modifiers:

<native:top-bar title="Watch Later" />

<native:scroll-view class="w-full h-full bg-zinc-100">
    <native:column class="w-full p-4 gap-3">
        <native:text class="text-sm text-zinc-500">
            {{ $videos->count() }} videos saved, {{ $queuedMinutes }} minutes queued
        </native:text>

        @foreach ($videos as $video)
            <native:pressable key="video-{{ $video->id }}" @tap="toggleWatched({{ $video->id }})">
                <native:row class="w-full items-center gap-3 p-4 bg-white rounded-2xl">
                    <native:icon
                        ios="{{ $video->watched ? 'checkmark.circle.fill' : 'circle' }}"
                        android="{{ $video->watched ? 'check_circle' : 'radio_button_unchecked' }}"
                        size="24"
                        color="{{ $video->watched ? '#16A34A' : '#A1A1AA' }}"
                    />
                    <native:column class="flex-1 gap-1">
                        <native:text class="text-base font-semibold {{ $video->watched ? 'text-zinc-400' : 'text-zinc-900' }}">
                            {{ $video->title }}
                        </native:text>
                        <native:text class="text-sm text-zinc-500">
                            {{ $video->channel }}@if ($video->minutes), {{ $video->minutes }} min @endif
                        </native:text>
                    </native:column>
                </native:row>
            </native:pressable>
        @endforeach
    </native:column>
</native:scroll-view>

Three details that earn a comment:

@tap takes arguments. @tap="toggleWatched({{ $video->id }})" calls the method with the id, Livewire style. @foreach is normal Blade, because it is normal Blade.

<native:top-bar> is real chrome. It hoists onto the actual NavigationStack, so you get native back gestures and large-title behaviour for free. The docs are explicit about never hand-rolling a nav bar out of rows, and they are right.

Icons are per-platform names. There is no shared icon dictionary in core. The ios attribute takes an SF Symbols name, android takes a Material name, and whatever you pass through goes straight to the platform. Get one wrong and the icon silently does not render.

Run it on your phone without Xcode

This is the part of v4 that changes who can use it. Compiling an iOS app still requires a Mac with Xcode. Running one during development no longer does:

php artisan native:jump

Jump starts a dev server and prints a QR code. Scan it with your phone's camera and the free Jump app opens your Laravel app as a native iOS app, rendering your actual Blade over the network. No compilation, no provisioning profiles, no Apple Developer account.

Every element in that screenshot is a SwiftUI view. Tap a row and the checkmark fills, the row title dims, and the queued-minutes counter recalculates, all driven by the PHP component:

Edit the Blade file and the screen hot-reloads on the device. The feedback loop is genuinely faster than my Livewire browser workflow, which I did not expect to write.

You can test screens without a device

The sleeper feature of v4 is the testing harness. php artisan native:make-test WatchList scaffolds a Pest test, and the API reads like Livewire's:

use App\NativeComponents\WatchList;
use Native\Mobile\Testing\Native;

it('toggles a video watched when its row is tapped', function () {
    $video = Video::where('title', 'Laracon US 2026 Keynote')->firstOrFail();

    Native::test(WatchList::class)
        ->tap("video-{$video->id}")
        ->assertSee('66 minutes queued');

    expect($video->refresh()->watched)->toBeTrue();
});

That runs on your machine in milliseconds, no simulator involved. It can fire taps, long-presses, text input, toggles, swipes and navigation, and assert against the rendered tree. Mobile UI you can put in CI is not something the PHP ecosystem had last year.

The sharp edges

I promised the walls, so here they are.

Form elements live in a plugin, and the plugin is not on Packagist. Core v4 registers layout, text, icons, pressables and navigation chrome. button, text-input, toggle and bottom-sheet come from a separate nativephp/native-ui package distributed through NativePHP's own channels rather than Packagist. My original demo had an add-video form in a bottom sheet, and it died with Unknown native element type: bottom_sheet until I read the service provider source and found the comment explaining the split. For a list-and-tap screen core is plenty. For forms, budget time to sort out plugin access first.

v4 is moving fast. The version number tells the story: 4.0.0, 4.0.1, 4.1.0 and 4.2.0 all shipped within weeks of each other, and 4.2.0 was current when I built this. Nothing broke for me across that churn, but I would not bet a client deadline on the surface staying identical yet.

The PHP 8.4 floor will surprise people. Plenty of Laravel developers are on 8.3 today. The error is clear, the fix is quick, but it is the first thing you will hit.

None of these change the verdict. They are the normal texture of a framework feature that is one month old.

Should you build with it?

If you shipped something on v3, the upgrade is safe and additive. Your webview screens keep working, and you can convert them one at a time. That migration-friendly posture is the same pattern I liked when I compared the desktop side of NativePHP to Electron: NativePHP consistently chooses paths that let you adopt incrementally.

If you are starting fresh: for an internal tool, a companion app for an existing Laravel product, or anything list-and-detail shaped, this is now the fastest route from Laravel skills to a real native app. For a consumer app with heavy custom UI or deep platform integration, native Swift or Kotlin still wins, and NativePHP's own plugin system is the escape hatch when you need one native capability rather than a native rewrite.

FAQ

Do I need a Mac to try this?

Not for development. Jump runs your app on a real device without compiling anything, so any machine that runs Laravel works. You need a Mac with Xcode only when you compile a distributable iOS build for the App Store.

Is NativePHP v4 free?

The core nativephp/mobile package installed from Packagist with no license key, and the Jump app is free. Some UI and capability plugins are distributed separately through NativePHP's own channels, with paid tiers for premium plugins.

Does my existing Livewire knowledge transfer?

Almost embarrassingly well. Public properties are state, methods are actions, @tap and friends bind events to methods, and re-rendering happens when state changes. The view layer is different tags, not a different mental model.

How is this different from React Native or Flutter?

Same destination, different vehicle. React Native bridges JavaScript to native views and Flutter paints its own widgets. NativePHP runs an actual PHP runtime on the device, converts Blade to a native UI tree in shared memory, and renders platform-real SwiftUI and Compose views. You keep Eloquent, migrations and the whole Laravel toolbox.

Can I still use a webview for some screens?

Yes. The webview element remains for legacy screens and edge cases, and v3 apps upgrade without rewriting them. The docs are blunt that new screens should be native, and after building one I see no reason to disagree.

The short version

v3 asked you to accept a webview in exchange for staying in Laravel. v4 stops asking. Blade in, SwiftUI out, Eloquent on the phone, tests in CI, and a QR code instead of Xcode.

The plugin split and the release pace are real costs, and I would wait a quarter before shipping a revenue-critical app on it. But the direction is now unmistakable: the gap between "I know Laravel" and "I shipped a native app" has never been this small.

Laravel Lock vs Cache::lock: When Entity-Scoped Locking Earns a Package

Hafiz — Mon, 24 Aug 2026 04:15:10 +0000

Originally published at hafiz.dev

Two workers pick up the same job at the same moment. Both read a stock count of 1. Both decide there is enough. Both allocate it.

You now owe someone an apology email.

Laravel has shipped Cache::lock() for years and it solves this. So when Laravel Lock turned up, a package whose entire job is distributed locking, my first reaction was that we already have this. Then I read what it actually does, and the answer got more interesting.

This is a post about when a thin wrapper earns its place in your composer.json.

What you already have

Cache::lock() is the built-in answer, and for a lot of cases it is the right one.

$lock = Cache::lock('stock_allocation_SKU-1180', 10);

if ($lock->get()) {
    try {
        $this->allocate($sku);
    } finally {
        $lock->release();
    }
}

That works. It is atomic against Redis or Memcached, it has a TTL so a crashed worker cannot hold the lock forever, and it costs you nothing extra.

But look at the key. 'stock_allocation_SKU-1180' is a string you built by hand. Somewhere else in the codebase, someone else builds 'stock-allocation-' . $sku->id and now you have two locks guarding the same resource, which is the same as having none.

That is the actual problem. Not atomicity, naming.

What the package adds

use ZaberDev\Lock\Facades\Lock;

$lock = Lock::for('shipment_dispatch', $shipment)->ttl(120);

if ($lock->acquire()) {
    try {
        $carrier->dispatch($shipment);
    } finally {
        $lock->release();
    }
}

Lock::for('shipment_dispatch', $shipment) builds the key from the name plus the model, so the same target always produces the same key. You cannot typo your way into a second lock on the same row.

There is a block() form that handles acquire and release for you:

$manifest = Lock::for('shipment_dispatch', $shipment)->block(function () use ($shipment, $carrier) {
    return $carrier->dispatch($shipment);
});

Models can carry their own locks with a trait:

use ZaberDev\Lock\HasLocks;

class Shipment extends Model
{
    use HasLocks;
}

$lock = $shipment->lock('dispatch')->ttl(120);

And routes can be guarded with middleware, which is the piece I have hand-rolled more than once:

Route::post('/warehouse/reconcile', [ReconcileController::class, 'store'])
    ->middleware('lock:warehouse_reconcile,300');

Route::post('/shipments/{shipment}/dispatch', [ShipmentController::class, 'dispatch'])
    ->middleware('lock:shipment_dispatch:{shipment},60');

That last one binds the lock to the route parameter, so two requests for different shipments do not block each other while two requests for the same one do. When the lock is already held, the middleware does not queue the request. It rejects it with a 429 before your controller runs.

Install:

composer require zaber-dev/laravel-lock
php artisan vendor:publish --provider="ZaberDev\Lock\LockServiceProvider"
php artisan migrate

It needs PHP 8.2 or newer and works on Laravel 11, 12 and 13. Cache drivers or a database table, so Redis, Memcached or your existing SQL database.

The decision

View the interactive component on hafiz.dev

The diagram is the short version. The longer version is that these three tools solve genuinely different problems and people reach for the wrong one constantly.

A database transaction is right when the thing you are protecting is a database write and nothing else. lockForUpdate() inside a transaction is stronger than any application lock, because the database enforces it. If your race is two workers updating the same row, stop reading and use a transaction.

Cache::lock() is right when the work spans more than the database. Calling a payment API, writing a file, sending a webhook. A transaction cannot protect those because they are not transactional. One lock key, one place in the code, no ceremony.

Laravel Lock starts to earn its place when the same logical resource gets locked from several places. A dispatch that can be triggered by a controller, a queued job and an artisan command is three chances to build the key differently. Entity scoping makes that impossible by construction.

Where I would not use it

If you have exactly one lock in your application, this is a dependency you do not need. Cache::lock() with a well-named constant does the same job.

If your race is purely a database one, both of these are the wrong layer. Use lockForUpdate().

And if the goal is to let a few workers through rather than exactly one, that is not a lock at all, it is a funnel. Different tool, different failure modes. I covered that in concurrency limiting with cache funnels.

And be careful with the database driver. It writes a row per lock and every acquire runs a transaction with a SELECT ... FOR UPDATE before the insert. That is correct, and it is also slower than Redis by a wide margin. If you are locking in a hot path, use a cache driver.

The version is also worth a glance. v1.0.1 landed in July 2026, so it is young. The surface is small enough that a breaking change would be cheap to absorb, but I would not put it in the path of anything that cannot fail on day one.

Locks are not a substitute for idempotency

The failure I see most often is not a missing lock. It is a lock treated as a guarantee.

A lock with a TTL can expire while the work is still running. The worker holding it does not find out. A second worker acquires the lock and starts the same work, and now you have the exact race you were preventing, except harder to reproduce because it only happens under load.

Set the TTL longer than the worst realistic runtime, not the average. And make the work idempotent anyway, so that if it does run twice the second run is harmless. The same reasoning applies to queue jobs that must not double-process, and it is the same discipline I used when three multi-tenancy queue bugs turned out to be concurrency problems wearing a different hat.

A lock narrows the window. It does not close it.

FAQ

Is this different from ShouldBeUnique on a job?

Yes. ShouldBeUnique stops a duplicate job being dispatched at all, at dispatch time. A lock protects a section of code at execution time, whoever runs it. Use the first to keep the queue clean, the second to protect the resource.

Does it work without Redis?

Yes. It supports cache drivers and a database table. The database driver writes a row per lock and takes a transaction with lockForUpdate() on each acquire, which is correct but slower. Redis or Memcached for anything hot.

What happens if the process dies while holding a lock?

The TTL releases it. That is why the TTL matters: too short and a second worker starts before the first has finished, too long and a crashed job blocks the resource until it expires. Pick a value longer than your worst realistic runtime.

Can I lock something that is not an Eloquent model?

Yes. The package resolves models, strings and integers into keys out of the box, so Lock::for('stock_allocation', 'SKU-1180') is valid. For your own value objects, implement the package's Lockable interface and the string it returns becomes the second half of the key.

Should I use this or just Cache::lock?

If you have one or two locks, use Cache::lock(). If the same resource is locked from several entry points, the entity scoping stops a whole class of key-mismatch bug and is worth the dependency.

The short version

Cache::lock() is not broken and this package does not replace it. What it replaces is the string key you were building by hand in four different files.

That is a real problem in a codebase of any size, and a boring one to solve yourself. Whether it is worth a dependency comes down to how many places lock the same thing.

The honest test is to count. If one place locks the resource, Cache::lock() and a named constant is the whole answer. If it is four places across a controller, a job and two commands, the key is going to drift, and that is what you are actually buying.