DEV Community: Hafiz

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.

Sitemap Timing Test

Hafiz — Thu, 20 Aug 2026 13:02:18 +0000

Originally published at hafiz.dev

Your Laravel MCP Server Is a Public API for Robots. Here's How to Lock It Down.

Hafiz — Wed, 19 Aug 2026 04:15:10 +0000

Originally published at hafiz.dev

There are about six good tutorials on building a Laravel MCP server. Every one of them ends at the same place: you make a tool, you connect Claude, the agent calls your tool, everyone claps. Then the tutorial stops.

That's the exact moment the interesting part starts. Because what you just built is an HTTP endpoint that lets a language model run your code. Mcp::web('/mcp/orders', OrderServer::class) is a public route by default, and the tool behind it might refund a payment, delete a record, or read a customer's data. The getting-started guides walk you right up to that door and then wave goodbye before anyone locks it.

This post is the lock. Authentication, per-tool authorization, the annotation trap that looks like a safety feature and isn't, rate limiting an endpoint an AI can call in a loop, and how to test that all of it actually holds. If you've read the Laravel MCP getting-started guide or built the app-friendly version I covered in making your Laravel app AI-agent-friendly, this is the next step you actually need before any of it goes near production.

What you're actually exposing

Start by being honest about the threat model, because it's different from a normal API.

A normal REST endpoint is called by code you wrote or a client you documented. An MCP tool is called by a language model interpreting natural language, sometimes from a user you've never met, sometimes with arguments the model invented to fit what it thought you meant. The caller is non-deterministic by design. That's the whole point of the protocol, and it's also the whole problem.

So three things are true at once. The endpoint is public unless you protect it. The arguments are model-generated, so they can be malformed or adversarial in ways a normal client never would be. And the tool descriptions you write are read by the model to decide what to call, which means a badly scoped tool gets invoked in situations you didn't picture. A deleteRecords tool with a vague description is a loaded gun with a helpful label.

None of this means MCP is unsafe. It means the safety is your job, and Laravel gives you every piece you need. The pieces just aren't assembled anywhere, so let's assemble them.

Layer one: authentication, and why local is not exempt

A web server registered with Mcp::web() is reachable by anyone who finds the URL. Authenticate it. The docs give you two real options and one trap.

Sanctum is the pragmatic choice for most apps. Add the middleware and require a bearer token:

use App\Mcp\Servers\OrderServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/orders', OrderServer::class)
    ->middleware('auth:sanctum');

Every request now needs Authorization: Bearer <token>, and inside your tools $request->user() resolves to the token's owner. For an internal server, or one your own product's agents call, this is enough.

OAuth via Passport is what the MCP spec actually standardizes on, and it's the right call when third-party MCP clients (someone else's Claude, a tool you don't control) need to connect:

Mcp::oauthRoutes();

Mcp::web('/mcp/orders', OrderServer::class)
    ->middleware('auth:api');

Here's the part worth internalizing before you rely on it: Laravel MCP uses OAuth as a translation layer to your authenticatable model, and it advertises a single mcp:use scope. Custom scopes aren't supported. So OAuth authenticates who the agent is acting as, but it does not carve up what they can do. If your mental model of OAuth includes fine-grained scopes gating individual tools, drop it here. Authentication tells you the user. Authorization is still entirely on you, and that's the next layer.

The trap is thinking local servers don't need any of this. A local server runs as an Artisan command for agents on the same machine, which feels safe. But it runs with your application's full privileges, every binding in your container, your database, your filesystem. The security boundary for a local server is whatever can start that process. If that's a coding agent executing on your dev machine with your credentials, the blast radius is your entire local environment. Treat the machine boundary as the auth boundary, and don't register a local server that does anything you wouldn't let a shell script do unattended.

Layer two: authorization, per tool, inside handle

Authentication gets you a user. Now decide what that user can do, and do it in two places, because they guard different things.

shouldRegister controls whether a tool is visible in the server's tool list:

public function shouldRegister(Request $request): bool
{
    return $request->user()?->can('refund-orders') ?? false;
}

This is good practice. It keeps tools a user can't use out of the list the model sees, which means the model won't try to call them and won't hallucinate around their existence. But understand exactly what it does: it hides the tool. Hiding is not blocking. A caller who knows the tool name can still attempt to invoke it, and shouldRegister returning false is not a guaranteed rejection at the point of execution the way an authorization check is.

So the actual gate goes inside handle(), every time, on every tool that does anything sensitive:

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;

public function handle(Request $request): Response
{
    if (! $request->user()->can('refund-orders')) {
        return Response::error('You are not authorized to issue refunds.');
    }

    $validated = $request->validate([
        'order_id' => ['required', 'integer', 'exists:orders,id'],
        'amount' => ['required', 'integer', 'min:1', 'max:500000'],
    ]);

    // ...
}

Two things are happening there and both matter. The can() check is your real authorization boundary, the one that actually stops execution. And the validation is not optional politeness, it's your defense against model-generated arguments. The exists rule stops a refund against an order that isn't there. The max stops the model refunding fifty thousand euros because it misread "500" as cents-or-not. Model input is untrusted input. Validate it exactly as hard as you'd validate a public form, because functionally that's what it is.

The pattern I hold to: shouldRegister for visibility, can() for the gate, validate() for the arguments. Skip any one of them and you've left a hole that the other two don't cover. This is the same principle behind stopping an AI agent from destroying your Laravel app, applied at the protocol boundary instead of the SDK. If you want the review-before-execution version of the same instinct, the AI SDK's human-in-the-loop tool approval pauses a call for a person; this is the authorization layer underneath it.

View the interactive diagram on hafiz.dev

The annotation trap

Laravel MCP lets you tag tools with annotations: #[IsReadOnly], #[IsDestructive], #[IsIdempotent], #[IsOpenWorld]. They look like access controls. They are not.

These are hints to the client. They travel to the AI client as metadata so it can make smarter decisions, like warning a user before calling a destructive tool or preferring a read-only one. That's useful for a well-behaved client. But nothing in your server enforces them. A client can ignore #[IsReadOnly] completely, and a compromised or hostile client absolutely will. Marking a tool #[IsReadOnly] does not prevent it writing if its handle() writes.

So use annotations, they improve the experience with honest clients and they're good documentation of intent. Just never let one stand in for a check. If a tool must not modify data, the guarantee lives in what handle() does and what can() allows, not in an attribute the client is free to disregard. The annotation describes the tool's behavior; it doesn't constrain it.

This is the single most likely place for a false sense of security in the whole feature, because the attribute reads like a policy and sits right there in the class looking authoritative.

Layer three: rate limiting an endpoint a robot can loop

A human hits your API at human speed. An agent in a retry loop, or a streaming tool processing a batch, can hit it as fast as the network allows. And MCP tools can return generators that hold an SSE stream open, which is a different resource profile from a normal request-response.

Throttle the server route like you'd throttle a login endpoint:

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

Then define the limiter against the authenticated user, not the IP, because many agents sit behind shared egress addresses:

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('mcp', function (Request $request) {
    return $request->user()
        ? Limit::perMinute(60)->by($request->user()->id)
        : Limit::perMinute(10)->by($request->ip());
});

Sixty a minute is a starting point, not a recommendation. Set it from what a legitimate session actually needs, then add headroom. The point is that an unbounded MCP endpoint is a cost and availability risk the moment a model decides to call your tool in a loop, and models do decide that. An agent will happily call the same lookup tool a dozen times in one turn, each result making it think of a new question. Cap it.

For anything expensive behind a tool, the throttle is the first line, not the only one. Push the heavy work to a queue and return a job reference, the same way you would for any slow endpoint, which I went through in processing thousands of queued jobs without breaking. A tool that kicks off a job and returns immediately can't hold a worker hostage.

Testing that the locks hold

The reason this feature survives contact with production is that all of it is testable without a live model or a network call. Laravel MCP ships test helpers that let you invoke a tool as a specific user and assert on the result.

The tests that matter here aren't the happy path. They're the negative cases, the ones that prove your gates actually reject:

it('refuses refunds for unauthorized users', function () {
    $user = User::factory()->create(); // no refund permission

    $response = OrderServer::actingAs($user)
        ->tool(RefundOrderTool::class, [
            'order_id' => 42,
            'amount' => 5000,
        ]);

    $response->assertHasErrors();
});

it('rejects an amount above the ceiling', function () {
    $manager = User::factory()->refundManager()->create();

    $response = OrderServer::actingAs($manager)
        ->tool(RefundOrderTool::class, [
            'order_id' => 42,
            'amount' => 99999999,
        ]);

    $response->assertHasErrors();
});

Write the "unauthorized user is refused" test for every sensitive tool. Write the "bad arguments are rejected" test for every tool that takes model input, which is all of them. If you set up your suite the way I described in the Pest testing guide, these drop straight into it. A green suite here means the model can throw whatever it wants at your server and the boundaries hold.

A quick word on tool descriptions as an attack surface

One thing that isn't obvious until it bites you: the description you write on a tool is instructions to the model. A vague or overreaching description causes the model to call the tool in situations you didn't intend, which is a security issue dressed as a copywriting issue.

"Manages orders" invites the model to reach for that tool for anything order-shaped. "Issues a refund against a specific order, for a specific amount, when a customer reports a defect" tells the model exactly when this fires and when it doesn't. Narrow descriptions are narrow attack surfaces. Write them like you're briefing an over-eager junior who takes every instruction literally, because you are.

My take

The rule I'd publish on the team wiki: authenticate the server, authorize inside every sensitive handle(), validate every argument, throttle the route, and never trust an annotation as a control. Five things, all of them boring, all of them enforced in code you can test.

The one I'd emphasize hardest is that authentication and authorization are different jobs and MCP only hands you the first one cleanly. The single mcp:use scope means the framework knows who is calling but has no opinion on what they may do. Every "what" decision is a can() check you write. Miss that distinction and you'll ship a server that's authenticated and wide open, which is arguably worse than one with no auth at all, because it looks secure in the code review.

I'll also say the honest thing: MCP is young, the security patterns around it are younger, and the most dangerous tools are the ones that felt harmless in isolation. A read tool that exposes one customer's data is a read tool that exposes every customer's data if the authorization is wrong. Start with your least dangerous tool, get the five layers right on it, and use it as the template for everything else. Don't expose the refund tool until the lookup tool's tests are green.

Build the server. Then lock it before anyone, human or model, walks through the door.

FAQ

Does a local MCP server need authentication?

Not in the HTTP sense, since it runs as an Artisan command rather than a route. But it runs with your full application privileges, so the security boundary becomes whatever can start the process. On a dev machine driven by a coding agent, that's your entire local environment. Treat the machine access as the auth boundary.

Can I use OAuth scopes to control which tools an agent can call?

Not with Laravel MCP's built-in OAuth. It uses OAuth as a translation layer to your authenticatable model and advertises a single mcp:use scope; custom scopes aren't supported. Per-tool authorization is done with can() checks inside each tool's handle() method, not with scopes.

Do the `#[IsReadOnly]` and `#[IsDestructive]` annotations prevent a tool from doing damage?

No. They're advisory metadata sent to the AI client to help it make decisions. Your server doesn't enforce them, and a client can ignore them. A tool is only read-only if its handle() method doesn't write. Never rely on an annotation as an access control.

How do I stop an AI agent from calling my tool in a loop?

Apply Laravel's throttle middleware to the MCP route and define a rate limiter keyed by the authenticated user rather than the IP, since agents often share egress addresses. For expensive operations, push the work to a queue and return a job reference so a single call can't tie up a worker.

Is validation really necessary if I've defined an input schema?

Yes. The JSON schema gives the model a shape to aim for, but it isn't enforcement, and model-generated arguments can still be malformed or adversarial. Validate inside handle() with Laravel's validator exactly as you would for a public form, including existence and range checks.

Wrapping up

Building an MCP server is a solved problem with six good tutorials. Securing one isn't, because the docs hand you the pieces (Sanctum, Passport, can(), shouldRegister, annotations, throttling, test helpers) without assembling them into a threat model. The model is simple once you see it: the endpoint is public, the caller is non-deterministic, the arguments are untrusted, and the annotations are hints. Everything else follows.

Authenticate the route, authorize inside handle(), validate every argument, throttle the endpoint, and test the negative cases. Do that and you've got an MCP server you'd actually put on the internet.

How I Moved a Live Laravel SaaS to a New Server With 2 Minutes of Downtime

Hafiz — Mon, 17 Aug 2026 09:54:18 +0000

Originally published at hafiz.dev

Last Thursday morning, I moved a production Laravel SaaS with paying customers from one server to another. The maintenance page was up for 1 minute and 55 seconds. I know the exact number because I checked the nginx access log on the new box afterwards: old server frozen at 09:19:59 UTC, first live request served by the new one at 09:21:54. The whole server migration, planning included, took one morning.

The app is Prompt Optimizer, a prompt optimization tool with a free tier doing tens of thousands of optimizations a month and a paid tier billing real money through Stripe. So this wasn't a hobby project where downtime means nobody notices. A botched cutover here means failed checkouts and a Chrome extension that stops working for people who paid for it.

This post is the full playbook: why I moved, how the cutover stayed under two minutes, and more importantly, the four things that almost broke silently. Because the rsync commands are the easy part. The dangerous part is everything that lives outside your app directory.

Why I moved at all

The old server was a 1GB DigitalOcean droplet hosting several apps at once. It worked fine until the app grew, and then it didn't.

Two incidents forced the decision. First, PHP-FPM worker starvation: my optimize endpoint calls an AI provider that can take up to 45 seconds to respond, and with pm.max_children = 5, five slow AI calls meant the entire site stopped answering. Health checks stayed green the whole time, which made it worse. Second, an earlier out-of-memory crash had already forced me to ban every-minute cron jobs on that box, which quietly meant my Laravel scheduler never ran in production. More on that later, because it hid a broken feature for weeks.

You can patch around a resource ceiling for a while. Raise a worker count here, cache a query there. But when the fixes start fighting each other, the honest answer is a bigger box. I went with a small Hetzner server with 4GB of RAM and two vCPUs, which I compared against the managed options in Laravel Cloud vs Forge vs a plain VPS. For a solo developer running multiple small apps, the VPS still wins on cost by a wide margin.

The unfair advantage: Cloudflare was already in front

Here's the thing that made a two-minute cutover possible at all: the domain was already proxied through Cloudflare.

When your DNS is proxied, visitors never connect to your server's IP directly. They connect to Cloudflare's edge, and Cloudflare connects to whatever origin IP you've configured. Changing that origin is a dashboard edit that takes effect in seconds. No TTL waiting, no propagation anxiety, no "some users see the old server for six hours" nonsense. The classic migration problem simply doesn't exist.

If your production domain is not behind a proxy like this, set that up weeks before you migrate, not the day of. I covered the base setup in How I Hardened My VPS in One Afternoon, and the same stack carried this migration: Cloudflare in front, Tailscale between the boxes for private server-to-server transfers.

For TLS on the new origin I used a Cloudflare origin certificate instead of certbot. It's valid for 15 years, only Cloudflare needs to trust it, and there's no renewal cron to migrate. One less moving part.

Preparing the new server while the old one serves traffic

Everything in this phase happened while the site ran normally. Zero risk, no time pressure.

The new box got a dedicated PHP-FPM pool with 12 workers, sized so those 45-second AI calls can't starve anyone again. The queue worker became a proper systemd service instead of a supervisor config. Nginx got the vhost with the origin cert. Then I synced the whole deployed app tree over Tailscale: 227MB of code and vendor directory, about 20 seconds.

The database needed more thought. The app runs on SQLite in production (yes, really, 123MB serving a six-figure monthly request count without complaint). You can't just copy a SQLite file that's being written to, because you might catch it mid-transaction. SQLite has a clean answer: VACUUM INTO, available since 3.27, which writes a consistent snapshot to a new file without blocking writers.

// One consistent snapshot, no write freeze, no downtime
DB::statement("VACUUM INTO '/tmp/snapshot.sqlite'");

That snapshot went to the new server as a rehearsal database. And then came the step I'd argue is the single most valuable trick in this whole post.

Rehearse through the real edge with a probe subdomain

Testing the new server with curl --resolve proves your nginx config works. It does not prove that Cloudflare's edge can talk to your new origin. SSL mode mismatches and origin cert problems only show up on that hop, and the classic failure is discovering them after you flip DNS, live, while your site throws 526 errors.

So before touching the real records, I added one DNS entry: neworigin.mydomain.com, proxied, pointing at the new server's IP. The origin cert was a wildcard, so it covered the probe subdomain for free. Then I opened it in a browser and ran a full user flow against the rehearsal database, through Cloudflare's actual edge, TLS handshake and all.

It worked. Which meant the cutover would change exactly one variable: the origin IP behind a path already proven end to end. That's what makes a migration boring, and boring is the goal.

The cutover: 1 minute 55 seconds

Here's the full sequence. My part was scripted; the human part was clicking two DNS records.

Stop the queue worker on the old server, then php artisan down. Writers stopped first, then the maintenance page. The order matters: a worker that keeps processing jobs during your final sync is how you lose data.
Take a fresh VACUUM INTO snapshot. Writes are frozen now, so it's the final, complete state.
Rsync the snapshot plus the storage delta to the new server. The pre-sync days earlier meant this final pass moved almost nothing.
On the new box: php artisan config:cache, fix file ownership, start the queue worker, install the crontab. The full cache command list is in the Laravel Artisan commands reference.
Flip the two A records in Cloudflare to the new origin.
Verify on the live domain: health endpoint, homepage, pricing, one real optimization, and a live Stripe checkout session to confirm billing quotes the right amount.

View the interactive diagram on hafiz.dev

The old server stayed exactly as it was, frozen in maintenance mode. That's the rollback plan, and it's beautifully simple: flip the two records back, run php artisan up, restart the worker. The point of no return is the first real payment on the new box, because after that, rolling back means losing data.

The four things that almost broke

This is the part I wish someone had written before I started. Every one of these was invisible in my planning and got caught by testing rather than foresight.

The maintenance flag stowed away in the rsync

Right after the final sync, the new server started answering 503. Confusing, until I realized why: php artisan down creates a flag file at storage/framework/down, and my final rsync had faithfully copied it to the new server. The new box wasn't broken. It was dutifully in maintenance mode because I'd shipped the maintenance flag along with the data. One php artisan up on the new server fixed it, and cost about 30 seconds of the downtime window.

The SSR service that existed nowhere in the app tree

The app uses Inertia SSR, which runs as a separate node process managed by a systemd unit. That unit isn't in the git repo. It's not in the crontab. It's not in the supervisor config. Its name didn't even contain the app's name. My server inventory missed it completely, and the site ran client-side-only for about 40 minutes before a deploy script warning surfaced it. For an app where most traffic comes from organic search, silently losing server-side rendering is a real SEO problem.

The lesson: list every systemd service on the old box and ask what each one does. An app's runtime can include services you forgot you created.

The backup that would have failed silently every night at 2:30

The database backup script ships snapshots offsite to Cloudflare R2 on a cron. After the migration I ran it by hand once instead of waiting for the schedule. Exit code 127. The new server didn't have the sqlite3 CLI installed, and the cron line ends in >> /dev/null 2>&1, so the nightly run would have failed silently forever. I'd have discovered it the day I actually needed a backup, which is the one day you can't afford to.

Run every cron job by hand once on the new machine. Crons that discard output don't fail loudly. They just stop existing.

The midnight log rotation trap

Laravel's daily log driver creates a fresh log file at the first write after midnight. Whoever writes first owns the file. If that's ever root (a stray artisan command over SSH is enough), the web user can't write to it, and every request starts failing at midnight while you sleep. I'd been bitten by this before, so this time I set a default ACL on the log directory that makes any new file writable by the web user no matter who creates it:

setfacl -R -d -m u:www-data:rwX storage/logs

Then I proved it: created a file as root, appended to it as www-data, watched it succeed. The first unattended night passed clean.

What I'd tell you to do differently

Honestly? Not much about the process. But I hold two opinions after this that I didn't hold as strongly before.

First, rehearse through the real path, not a simulation of it. The probe subdomain took two minutes to set up and removed the only scary unknown in the plan. Every migration guide tells you to test the new server. Almost none tell you to test the edge-to-origin hop, and that's the one that bites.

Second, the boring deploy stack held up. My deploy is a bash script doing a local build and an rsync. No containers, no orchestration. There are sharper tools, and I've compared some of them in Scotty vs Laravel Envoy, but a deploy you fully understand beats a sophisticated one you half understand, especially at 11 in the morning with customers on the site. The same deploy script also caught the missing SSR service, which is a strong argument for running a no-change deploy as a post-migration test.

And one bonus: moving to a box that could afford an every-minute schedule:runcron revealed that some of my scheduled tasks had never actually run on the old server. Nothing was broken in the code. The entries existed in the scheduler, but no cron was firing them. Run php artisan schedule:list on your new box and check every line against what you believed was running.

FAQ

Do I need to lower DNS TTLs before migrating?

Not if your domain is proxied through Cloudflare or a similar edge. Visitors connect to the edge, not your origin, so changing the origin IP takes effect in seconds regardless of TTL. If your DNS points directly at your server, then yes, drop TTLs to 60 seconds at least a day before.

How do you copy a SQLite database that's in use?

VACUUM INTO writes a consistent snapshot without blocking writers, which is perfect for rehearsal copies while the site runs. For the final sync, stop your writers first (queue worker, then maintenance mode), take one last snapshot, and ship that. Never plain-copy a SQLite file under active writes.

Why not just use Laravel Forge or Laravel Cloud?

Both are good answers for teams that value their time over their invoice. I run several small apps on one box, I already had the hardened VPS setup, and the economics of a fixed-price server win at my scale. The trade is that every one of the gotchas in this post becomes your job. That trade is worth it to me. It might not be to you.

How long should the old server stay available?

I froze mine for a week: maintenance mode on, workers stopped, crons commented out, nothing deleted. Rollback is a DNS flip away for the whole window. Decommission only after the new box has survived real traffic, a real payment, and at least one full backup cycle.

What breaks most often after a server move?

Things that live outside your app directory: systemd services, cron entries, CLI packages your scripts assume exist, credentials in /root, log rotation permissions. Your code survives the rsync fine. The runtime around it is what gets forgotten.

The checklist is the takeaway

The migration took a morning, the downtime took 1 minute and 55 seconds, and the four near-misses took a healthy dose of paranoia to catch. If you're planning the same move, steal the sequence: prepare everything while the old server runs, rehearse through the real edge with a probe subdomain, freeze writers before the final sync, and then run every cron and service by hand once on the other side.

View the interactive component on hafiz.dev

Laravel Head vs SEOTools vs Your Hand-Rolled Meta Partial: Who Should Actually Migrate

Hafiz — Wed, 12 Aug 2026 08:34:06 +0000

Originally published at hafiz.dev

Every production Laravel app solved the <head> problem years ago, one of three ways: artesaos/seotools with its family of facades, ralphjsmit/laravel-seo with SEO models in the database, or a hand-rolled Blade partial stuffed with <meta> lines that grew one tag at a time since 2021. This blog runs the third kind.

Then Taylor showed Laravel Head on stage during the day-one Laracon US keynote, and now there's a first-party answer: composer require laravel/head, a fluent API for titles, descriptions, canonicals, Open Graph, X cards, robots directives, JSON-LD, resource hints, and favicons, resolved per request across Blade, Livewire, and Inertia.

Laravel News already covered how to use it, and the official docs are thorough. The question nobody has answered is the one existing apps actually have: I have SEOTools calls in thirty controllers, or SEO rows in my database, or a 120-line partial. Is switching worth it, and what does the mapping look like? That answer is different for each of the three groups, so let's take them one at a time.

First, the gate everyone hits before the interesting questions: Laravel Head requires PHP 8.3 and Laravel 13.17 or later. Below that, this whole post is academic until you upgrade. It needs 13.17 specifically because withHead() is built on the native route metadata API that shipped in that release, which I covered in the route metadata breakdown when it landed.

What Head actually is, in ninety seconds

Metadata resolves through five layers, lowest to highest priority: page defaults, route group metadata, route metadata, runtime metadata, and error metadata. Higher layers replace lower ones one field at a time, so a runtime title overrides the route's title without touching the route's description.

View the interactive diagram on hafiz.dev

Site-wide defaults live in a service provider:

use Laravel\Head\Enums\OgType;
use Laravel\Head\Enums\TwitterCard;
use Laravel\Head\Facades\Head;
use Laravel\Head\HeadBuilder;

Head::defaults(function (HeadBuilder $head) {
    $head
        ->title('hafiz.dev', suffix: ' - hafiz.dev')
        ->description('Laravel, shipped honestly.')
        ->canonical()
        ->og(siteName: 'hafiz.dev', type: OgType::Website)
        ->twitter(card: TwitterCard::SummaryWithLargeImage)
        ->searchableByRobots();
});

Static pages attach metadata to the route itself, and it survives route caching because withHead() writes plain arrays through the route metadata API:

Route::view('/contact', 'contact')
    ->name('contact')
    ->withHead(
        title: 'Contact',
        description: 'Get in touch.',
    );

Dynamic pages set the rest at runtime:

public function show(Post $post)
{
    Head::title($post->title)
        ->description($post->excerpt)
        ->ogImage($post->featuredImageUrl())
        ->when($post->isDraft(), fn ($head) => $head->hiddenFromRobots());

    return view('posts.show', ['post' => $post]);
}

And the layout renders everything with one directive:

<head>
    <meta charset="utf-8">
    @head
</head>

That's the whole model. Now the migration questions.

Group one: artesaos/seotools apps

SEOTools is the incumbent at 5.2 million installs, and if you've maintained a Laravel app for more than a few years, odds are decent you're in this group. The migration is the most mechanical of the three, and it's also the one with the clearest payoff, because of something I'll call the duplication tax.

Here's a representative SEOTools controller method, straight out of the pattern its own README teaches:

use Artesaos\SEOTools\Facades\SEOMeta;
use Artesaos\SEOTools\Facades\OpenGraph;
use Artesaos\SEOTools\Facades\TwitterCard;
use Artesaos\SEOTools\Facades\JsonLd;

public function show(Post $post)
{
    SEOMeta::setTitle($post->title);
    SEOMeta::setDescription($post->excerpt);
    SEOMeta::setCanonical(route('posts.show', $post));

    OpenGraph::setTitle($post->title);
    OpenGraph::setDescription($post->excerpt);
    OpenGraph::setUrl(route('posts.show', $post));
    OpenGraph::addImage($post->featuredImageUrl());
    OpenGraph::addProperty('type', 'article');

    TwitterCard::setTitle($post->title);
    TwitterCard::setImage($post->featuredImageUrl());

    JsonLd::setTitle($post->title);
    JsonLd::setDescription($post->excerpt);
    JsonLd::addImage($post->featuredImageUrl());

    return view('posts.show', ['post' => $post]);
}

Four facades, and the title appears four times. That's the duplication tax: SEOTools treats meta, Open Graph, Twitter, and JSON-LD as four independent surfaces, so every value you care about gets set on each of them, and every future edit happens in four places. Miss one and your og:title silently drifts from your <title>, which is exactly the class of bug nobody notices until a shared link renders wrong.

The same method under Head:

use Laravel\Head\Facades\Head;
use Laravel\Head\Facades\Schema;

public function show(Post $post)
{
    Head::title($post->title)
        ->description($post->excerpt)
        ->ogImage($post->featuredImageUrl())
        ->og(type: OgType::Article)
        ->schema(
            Schema::blogPosting()
                ->name($post->title)
                ->description($post->excerpt)
        );

    return view('posts.show', ['post' => $post]);
}

The document title and description fill in og:title, og:description, and the Twitter card values automatically, and the canonical comes from canonical() in your defaults, which uses the current request URL and normalizes it to https without being told. Fifteen lines became six, and the four-surface synchronization problem is gone because there's one source of truth.

The layout side shrinks the same way. SEOTools renders through four separate calls:

{!! SEOMeta::generate() !!}
{!! OpenGraph::generate() !!}
{!! Twitter::generate() !!}
{!! JsonLd::generate() !!}

All of that becomes @head.

There's also a maintenance argument that's uncomfortable to say out loud but belongs in the decision. SEOTools has been community-maintained since 2015, sits at v1.4.1, and its Packagist page currently lists three security advisories in its history. It works, and the maintainers deserve credit for a decade of service. But a first-party package that just got keynote billing is going to out-develop it from here, and the direction of that gap only points one way.

Verdict for this group: migrate, and don't drag it out. The mapping is mechanical, each page gets shorter, and running both packages during a transition is safe as long as only one of them renders a given tag. Move page by page, and delete the SEOTools generate calls from the layout last.

Group two: ralphjsmit/laravel-seo apps

This one is a different animal, and anyone telling you it's the same migration hasn't read what the package does. ralphjsmit/laravel-seo stores SEO as Eloquent models: a HasSEO trait on your Post creates and associates an SEO row in the database, editable through whatever admin you've built, retrievable through a seo relationship.

Laravel Head has no persistence layer at all. It resolves metadata from code, per request, and stores nothing. That's a deliberate design choice, not a gap they forgot, but it means the thing ralphjsmit users actually bought (SEO as content, editable without a deploy) doesn't come in the box.

The honest migration for this group keeps the database and swaps the rendering. Your SEO columns or the existing SEO model rows stay exactly where they are, and Head becomes the output layer:

public function show(Post $post)
{
    Head::title($post->seo->title ?? $post->title)
        ->description($post->seo->description ?? $post->excerpt)
        ->ogImage($post->seo->image ?? $post->featuredImageUrl());

    return view('posts.show', ['post' => $post]);
}

That works, and it's less code than it looks once you extract it into a small HasHeadMetadata trait of your own. But notice what happened: you rebuilt the package's model integration yourself, thinly. Whether that trade is worth it depends on how much you use the rest of what Head brings, especially the route-level metadata and the Inertia story below.

Verdict for this group: no urgency. Your package is actively maintained (1.8.1 shipped in March, Laravel 13 supported), and the DB-backed workflow is a real feature Head doesn't replace. Migrate if you want the first-party trajectory and are willing to own a thin bridge trait, or when your admin-editable SEO turns out to be three fields nobody edits, which is more common than anyone admits.

Group three: the hand-rolled partial

This is the group I'm in. hafiz.dev renders its meta tags from a Blade partial fed by the Post model: title, description, canonical, OG image with dimensions, article timestamps, Twitter card. It predates both packages' current versions, it works, and like every hand-rolled meta partial it has accumulated conditionals nobody remembers the reason for.

For this group the migration case isn't about deleting a dependency, since there's no dependency to delete. It's about three things the partial approach can't do well:

Static pages stop needing controller ceremony. Contact, about, pricing, legal, the whole marketing shell around a SaaS panel: every hand-rolled setup either hardcodes their meta in per-page views or threads variables through view composers. withHead() on the route definition replaces both, and it's cacheable.

The admin noindex problem gets one line. Every app has route groups that should never be indexed. With a partial, that's a conditional inside the partial checking the route name, which is exactly the kind of accumulated conditional I just complained about. With Head it's Route::withHead(robots: 'noindex, nofollow') on the group, next to the routes it describes.

Error pages get real metadata. Hand-rolled partials almost never handle 404 and 500 pages properly because the layout context is different there. Head lets you register per-status title, description, and robots values once in a service provider, and that's a category of page most of us silently ship with default or broken meta.

The migration itself is pleasant for this group because you're not translating an API, you're replacing string soup with structure. My plan for this blog is exactly the page-by-page approach: defaults into a provider first, then the blog post route, diffing the rendered <head> against the current partial's output before and after. The Head::toArray() method is quietly useful here, since it gives you the resolved metadata as a structured array you can assert against in a test instead of regex-matching HTML.

Verdict for this group: migrate at your own pace, newest pages first. Nothing is broken today, but every new page you add to the partial is a page you'll migrate later.

What Head doesn't do, so you don't uninstall the wrong thing

Three jobs commonly live next to meta tags, and none of them moved:

Sitemaps. Head has paginate(), alternates(), and feed() links, but it doesn't generate sitemap.xml. spatie/laravel-sitemap keeps its job.
OG image generation. Head references image URLs, it doesn't create the images. If you generate OG images dynamically, the setup from my spatie/laravel-og-image walkthrough still owns that step, and its output URL is what you hand to ogImage().
Stored, admin-editable SEO content. As covered above: no database, no admin UI, by design.

If your mental model is "Head replaces my SEO stack", adjust it to "Head replaces the rendering layer of my SEO stack". Everything that produces the values still exists.

The Inertia part, which is quietly the biggest upgrade

If you run Inertia, this is the section that should decide you, because the old world was bad: metadata managed by a client-side <Head> component means crawlers and link-preview bots that don't execute JavaScript see whatever your SSR setup happens to emit, which for many apps is nothing.

Head shares the resolved metadata as rendered element strings on a head prop, and with Inertia's serverHead option (Inertia 3.5+) those tags land in the initial HTML response. Each element carries a stable data-inertia key that Inertia adopts and keeps synchronized across visits and back/forward navigation. Preview bots read real tags without running a line of JavaScript, and you delete your client-side <Head> usage entirely, which the docs are explicit about: don't let both systems manage the same element.

Session-static tags (viewport, favicons, manifest) register once through Head::inertiaGlobals() and stay out of the per-page prop. It's a carefully thought-through design, and it solves a problem the community packages never fully cracked because it needed cooperation from Inertia itself. First-party coordination is the whole pitch, and this is what it looks like in practice.

My take

For new apps this isn't a decision, it's the default: Head from day one, spatie/laravel-sitemap next to it, done.

For existing apps, the three verdicts above compress to one sentence each. SEOTools apps should migrate because they're paying the duplication tax on every page and holding a package whose maintenance trajectory now points the wrong way. ralphjsmit apps should wait until the DB-backed workflow stops earning its keep, then bridge. Hand-rolled apps should migrate opportunistically, newest pages first, because the partial only grows.

And one caution against the enthusiasm direction: don't migrate the week before something matters. Meta tags are the definition of quiet infrastructure, and the failure mode of a botched migration is invisible until search traffic dips or a shared link renders blank. Diff the rendered <head> per page type before and after, and keep the old system rendering until the diff is clean. This is a change you make boring on purpose.

FAQ

What are Laravel Head's minimum requirements?

PHP 8.3 and Laravel 13.17 or later. The 13.17 floor exists because route-level metadata through withHead() is built on the native route metadata API introduced in that release.

Does Laravel Head replace artesaos/seotools completely?

For rendering meta tags, Open Graph, Twitter cards, and JSON-LD, yes, and with less code because titles and descriptions propagate to the social tags automatically. It doesn't generate sitemaps, which SEOTools never did either.

Can I run Laravel Head and my current SEO package at the same time?

Yes, during a migration. The rule is that only one system may render a given tag on a given page, so move page by page and remove the old package's render calls from the layout only when every page has switched.

Does Laravel Head work with route caching?

Yes. withHead() stores plain arrays through Laravel's native route metadata API, which is fully compatible with route:cache.

Does Laravel Head store SEO data in the database?

No. It resolves everything from code at request time. If you need admin-editable SEO content, keep your existing storage (columns or a package like ralphjsmit/laravel-seo's models) and feed those values into Head at runtime.

Wrapping up

The interesting thing about Laravel Head isn't any single feature, it's that the <head> element finally has a first-party owner, which means the Blade, Livewire, and Inertia rendering paths all got solved by one team with access to all three codebases. That's the thing no community package could ever fully deliver, and it's why the Inertia integration is the best part of the release.

Figure out which of the three groups you're in, apply that group's verdict, and whichever it is, diff your rendered head before and after. Quiet infrastructure deserves boring migrations.

Filament v4.12 and v5.7: 92% Faster Forms, and the Security Fixes You Still Have to Turn On

Hafiz — Mon, 10 Aug 2026 07:49:53 +0000

Originally published at hafiz.dev

Filament shipped its biggest performance release since the v4 launch on August 6. Versions v4.12.6 and v5.7.6 promote the beta the team asked the community to test in late June onto the stable channels for both major versions, and the headline numbers are real: form fields render up to 92% faster, tables up to 52% faster, all in a non-breaking minor release.

So run composer update. Today. The same release resolves what the team describes as a handful of CVEs, and staying behind on a release with security content is not a position you want to defend.

But here's the thing the announcement undersells, and the reason this post exists: two of the three new security features in this release do nothing until you write code. Updating gets you the patched vulnerabilities and all of the performance. It does not turn on the CSV formula-injection protection, and it does not sanitize a single CSS color value. If you read "please update to keep your application secure" and stop there, you'll be running the new version with the new protections sitting unused.

Let's take the release apart properly: what's automatic, what's opt-in, and what the benchmark numbers actually mean for a real admin panel.

The performance numbers, and what they measure

The team published internal benchmarks with the release, and they're worth reading precisely because of what they measure: median render time per component, not page load.

For forms and schema components:

Component	Previous	Now	Change
`TextInput`	0.559 ms	0.044 ms	~92% faster
`Select`	0.634 ms	0.052 ms	~92% faster
`FileUpload`	0.586 ms	0.083 ms	~86% faster
`Repeater` (10 items, 2 fields)	28.077 ms	2.885 ms	~90% faster
`Checkbox`	0.314 ms	0.033 ms	~90% faster

Half a millisecond per text input doesn't sound like much until you multiply it by a real resource form, the kind you end up with on any serious admin dashboard. Thirty fields at ~0.5 ms each was 15 ms of pure framework rendering overhead before your queries, your Livewire round trip, or your validation ran at all. That's now about 1.5 ms. And every Livewire interaction that re-renders the form pays this cost again, so the win compounds across a session, not just on first load.

The Repeater row is the one that matters most in practice. Repeaters are where Filament forms get heavy: line items on an invoice, variants on a product, questions on a quiz. Going from 28 ms to under 3 ms for a ten-item repeater changes the feel of exactly the forms people complain about.

Tables got a second pass too (the team already did a big tables performance round in an earlier version):

Scenario	Previous	Now	Change
50 rows, 5 `TextColumn`s, 3 row `Action`s	27.53 ms	13.11 ms	~52% faster
50 rows, 5 columns, 1 `ActionGroup` with 3 `Action`s	33.09 ms	16.73 ms	~49% faster

One honest caveat the team includes and most coverage will drop: these are internal development benchmarks, and your results will vary. Component-level medians are a fair way to measure framework overhead, but your panel's bottleneck might still be an N+1 query the renderer can't save you from.

How they did it, and why it's a little funny

The forms speedup comes from ripping out Blade component rendering paths and replacing them with direct PHP rendering. The pull request is refreshingly blunt about the technique: large portions of repeated Blade component calls were replaced with, in the team's own words, our dear friend the old <?php tag.

There's a real lesson in that. Blade components are a beautiful authoring experience, and every single one carries framework overhead: resolving the component class, building the data array, rendering the view. That cost is invisible until you're rendering hundreds of them per request, which is exactly what a Filament form does. The fastest Blade component is the one you don't render, and the Filament team just applied that at framework scale. If you've ever profiled a slow Filament page and wondered why so much time sat inside view rendering rather than your own code, this release is the answer arriving.

The tables work is subtler: lighter rendering paths for common actions, more efficient attribute handling, and per-record caching of visibility and authorization decisions. That last one deserves a highlight. If your table calls a policy or a visibility closure per action, per record, those decisions were being recomputed repeatedly within a single render. Now they're cached per record. Tables with lots of conditional visibility and authorization logic, which describes most serious multi-user panels, benefit the most. If your panel gates actions by role or tenant the way I set up in the SaaS panel guide, this is the part of the release working for you.

The security half, sorted by what actually happens when you update

This is where the release notes needed a second read. Sorted by what you get automatically versus what you have to do:

Automatic when you update: the patched CVEs. The release resolves several vulnerabilities. The team hasn't itemized them in the announcement beyond "a handful of CVEs", which is normal for coordinated disclosure, and it's also the entire argument for updating now rather than during next month's maintenance window.

Also already in if you're current: the MFA ordering fix. A week before this release, v4.12.5 and v5.7.5 quietly shipped a fix titled "Check panel access before presenting MFA challenge." Before that patch, the MFA challenge screen could be presented before panel authorization ran. If you use Filament's multi-factor authentication, that ordering fix alone justified the update, and it rode in with no announcement at all.

Opt-in: CSV formula-injection protection. When a spreadsheet app opens a CSV, cell values starting with =, -, +, or a tab character can execute as formulas. An attacker who controls a value that ends up in your admin export (a display name, a note field) can plant a formula that fires on the machine of whoever opens the file. Filament now ships protection that prefixes dangerous cells with a " so they stay text.

It's off by default, and for a defensible reason: legitimate values like international phone numbers start with +, and silently rewriting them would corrupt real exports. The team made the right call. But that means the protection only exists in panels where someone consciously enabled it, and "someone" is you, this week, for every exporter that includes user-controlled text.

Manual: CSS color sanitization. There's a new Str::sanitizeCssColor() helper for the case where user input ends up inside a style="" attribute. A malicious "color" value can break out of the attribute and inject extra CSS or attributes. The helper closes that, but it's a helper. It sanitizes nothing until you call it at your injection points. Grep your custom columns, entries, and blade views for style= interpolations before deciding you don't have any.

Configure it: query builder limits. New maxRules() and maxNestingDepth() methods bound how many rules and how much nesting the Query Builder accepts, enforced in the UI and against tampered payloads. The team files this under performance, but read the failure mode: a hand-crafted payload with an enormous rule tree could previously burn CPU and memory until response times cratered or the server fell over. That's a denial-of-service vector through a form, and if you expose the Query Builder to any non-admin user tier, setting these limits is a security decision, not a tuning knob.

So the accurate summary of this release is: the performance is free, the patched CVEs are free, and the three new defenses are tools you now own but haven't picked up. Update first, then budget fifteen minutes for the checklist below.

The fifteen-minute audit after updating

Grep for CSV exporters. Anywhere you export tables containing user-controlled text, enable the formula-injection protection, then check whether any legitimate values (phone numbers, negative amounts) get mangled and handle those columns explicitly.
Grep for style= interpolations. Custom columns, infolist entries, and blade views that build inline styles from stored values get wrapped in Str::sanitizeCssColor().
Bound your query builders. If non-admin users can touch a Query Builder, set maxRules() and maxNestingDepth() to the most restrictive values your real use cases allow.
Confirm you're on at least .5 of your branch. That's the MFA ordering fix. The current .6 includes it.
Re-run your slowest panel page and enjoy. No action needed, this one's the reward.

The quality-of-life additions worth knowing

The release also carries a set of smaller changes, a few of which solve real irritations. User and tenant menu items can now be registered in groups instead of one flat list, and the menu actions get memoized once per request as a bonus. Nested modals get modalDismissesParentActions(), so closing an inner modal can abandon a whole multi-step flow instead of forcing users to close each layer individually. Chart widgets can define proper empty states, which finally distinguishes "no data yet" from "broken". And a scattering of dynamic configuration wins: panel content width, sidebar width, dark mode availability, and the theme switcher can all take closures at runtime now, and navigation children can reference parents by a stable key instead of the displayed label, which stops translations from silently breaking your nav hierarchy.

None of these changes the argument for updating, but the grouped menus and the stable navigation keys are the kind of small fixes that let you delete workarounds from real codebases.

Should you update today?

Yes, and this is an easier call than most minor releases.

The case is unusually clean: it's a non-breaking minor on both branches, the beta ran in community applications for over a month before promotion, there's security content, and the performance work requires zero code changes to benefit from. The team explicitly designed the release so the upgrade is nothing more than bumping to the next minor version.

Two groups should look slightly closer before hitting update in production. If you maintain a panel with heavy custom theming or custom field components, the rendering path changed underneath you, so click through your custom components in staging first; direct PHP rendering should be visually identical, but "should" is doing work in that sentence when your CSS targets Blade component markup. And if you maintain or depend on plugins, check them against the new version before rolling out, since anything that hooked into the old rendering paths is the most likely thing to notice the refactor. Maintaining a Filament billing plugin myself, running the plugin test suite against both new branches is the first item on my list before shipping the bump to clients.

If you're still on v3, this release doesn't reach you, and that's the quiet message in it: the performance investment is going into v4 and v5 only. The earlier security round in June patched v3.3 alongside v4 and v5, so v3 still gets security fixes, but the gap between the branches just got wider. If you've been deferring the upgrade decision, the v5 breakdown I wrote at release covers what the jump involves, and this release just added 92% faster forms to the "upgrade" side of the ledger.

FAQ

Do I get the performance improvements without changing any code?

Yes. The rendering optimizations are internal to Filament. Update to v4.12.6 or v5.7.6 and every form, schema component, and table renders through the faster paths automatically.

Is the CSV formula-injection protection enabled by default?

No, it's deliberately opt-in, because prefixing cells that start with characters like + would corrupt legitimate values such as international phone numbers. You need to enable it for your exports and verify your real data survives it.

Which versions contain the MFA fix?

The "check panel access before presenting MFA challenge" fix shipped in v4.12.5 and v5.7.5 on July 31. The current v4.12.6 and v5.7.6 include it. If you're on any earlier patch of these branches and use Filament's MFA, update now.

Does this release affect Filament v3?

No. The performance work and the new security features target v4.12 and v5.7 only. The June security round was the last one to include a v3 patch (v3.3.52). If you're on v3, the case for planning the v4/v5 upgrade keeps getting stronger.

Will the update break my custom theme or plugin?

The release is designed as a non-breaking minor, and it went through a month-long community beta. That said, the forms refactor replaced Blade component rendering with direct PHP rendering, so custom components and CSS that target Filament's internal markup deserve a staging pass before production.

Wrapping up

This is what a good maintenance release looks like: a real performance refactor, security content, and no breaking changes, shipped through a public beta rather than straight to stable. The one improvement I'd ask of the announcement is honesty of emphasis. "Update to keep your application secure" is true for the CVEs and incomplete for the rest, because the most interesting defenses in this release are ones you have to reach for.

So do both halves. Run the update today, then spend the fifteen minutes on the audit. The panels that get the full value of this release are the ones where someone read past the benchmark tables.

Laravel's New Image API Doesn't Replace Intervention or Spatie Media Library

Hafiz — Wed, 05 Aug 2026 07:46:39 +0000

Originally published at hafiz.dev

Laravel 13.20 landed on 14 July with a first-party image API, and within a week the takes were everywhere. Laravel replaces Intervention Image. Drop your Spatie dependency. One less package in your composer.json.

Here's the first line of the installation section in the official docs:

composer require intervention/image:^4.0

You cannot use Laravel's image manipulation without installing Intervention Image, short of writing your own driver from scratch. The GD and Imagick drivers are both backed by it. Illuminate\Image\Drivers\InterventionDriver is the only driver that ships. Laravel didn't replace Intervention, it adopted it and put a facade in front.

So the comparison people are reaching for doesn't hold. What you actually have to decide is which layer of a four-layer stack your particular job belongs at, and that's a more useful question anyway.

The stack, honestly

Four layers, and most of the confusion comes from treating them as competitors when three of them sit on top of each other.

At the bottom are the PHP extensions, GD and Imagick, which do the pixel work. Above them sit the manipulation libraries: intervention/image and spatie/image, each wrapping the extensions in a sane API. Above those is Illuminate\Image, Laravel's new fluent wrapper, which drives Intervention. And off to one side is spatie/laravel-medialibrary, which builds on spatie/image and does something categorically different: attaching files to Eloquent models.

View the interactive diagram on hafiz.dev

Read that diagram and the question answers itself. If your job is "transform this image right now", you want the middle of the stack. If your job is "this Product has five photos, each needing a thumbnail and a web-sized version", you want Media Library, and Laravel 13.20 changed nothing for you.

What 13.20 actually replaces

Not a package. A class you wrote yourself.

Nearly every Laravel app that handles uploads has one. It's called ImageService or ImageManager or HandlesImageUploads, it lives in app/Services, and it's about forty lines of Intervention calls glued to a Storage::put(). Most of them were written against Intervention v3, so they look something like this:

class ImageService
{
    public function storeAvatar(UploadedFile $file): string
    {
        $manager = new ImageManager(new Driver);

        $image = $manager->read($file->getRealPath())
            ->cover(400, 400);

        $path = 'avatars/'.Str::uuid().'.webp';

        Storage::disk('public')->put($path, (string) $image->toWebp(80));

        return $path;
    }
}

That whole class is now one chain in your controller:

$path = $request->image('avatar')
    ->cover(400, 400)
    ->toWebp()
    ->quality(80)
    ->storePublicly('avatars', 'public');

$request->image() returns an Illuminate\Image\Image or null when the field is absent, so validate the upload first as you normally would. Every transformation returns a new instance, nothing executes until you ask for output, and the storage methods generate a unique filename and hand back the path exactly like store() does for ordinary uploads.

Deleting a service class is a small win, but it's a real one, and it's the kind of decision I've written about before in the service, action, or job decision tree. A wrapper that exists only to make a package feel Laravel-native stops earning its keep the moment the framework ships the same thing.

What it doesn't touch: Spatie Media Library

Media Library is at v11.23.2 and past 44 million installs, and none of what it does overlaps with the new API.

It associates files with Eloquent models. It registers named conversions on the model that generate automatically on upload and queue themselves by default. It generates responsive image variants along with the srcset markup to serve them. It handles multiple collections per model, per-collection disks, ordering, and a media-library:regenerate command for when you change a conversion and need to reprocess everything you've already stored.

class Product extends Model implements HasMedia
{
    use InteractsWithMedia;

    public function registerMediaConversions(?Media $media = null): void
    {
        $this->addMediaConversion('thumb')->width(368)->height(232)->sharpen(10);
        $this->addMediaConversion('web')->width(1200)->format('webp')->quality(80);
    }
}

Try to rebuild that on top of Illuminate\Image and you're writing a media table, a conversions registry, a queue pipeline, a URL generator, and a regeneration command. That's not a weekend. Media Library is a different product that happens to also resize images.

The one honest thing to say is that some apps pulled in Media Library purely to resize an avatar and never touched a conversion or a collection. If that's you, the new API is a genuine simplification. If you have registerMediaConversions anywhere in your codebase, it isn't.

When you still drop to Intervention directly

The Laravel API covers resize, scale, cover, contain, crop, orient, rotate, blur, grayscale, sharpen, both flips, seven output formats, quality, and optimize. That's the common set, and for most apps it's everything.

What it doesn't expose is most of what makes Intervention v4 interesting:

Text and fonts. No text() method, no font files, no wrapping, alignment, or stroke.
Composition. No insert() or place(), so no watermarks and no layering one image over another.
Drawing. No rectangles, circles, lines, or polygons.
Animation. No frame-by-frame work on animated GIFs.
Colorspaces and ICC profiles. Nothing for print-accurate color.

Need any of those and you use Intervention directly, which you already have installed. There's no conflict in doing both: the fluent API for uploads, the library for the one endpoint that stamps a watermark.

There is a middle path worth knowing about. You can register a custom transformation as a value object and teach a driver how to apply it:

use App\Images\Transformations\Pixelate;
use Illuminate\Support\Facades\Image;
use Intervention\Image\Interfaces\ImageInterface;

Image::transformUsing('gd', Pixelate::class, function (ImageInterface $image, Pixelate $transformation) {
    return $image->pixelate($transformation->size);
});

Your transformation class implements Illuminate\Contracts\Image\Transformation and carries its own arguments. After registering the handler in a service provider, ->transform(new Pixelate(12)) drops into any pipeline. That's how you get watermarking into the fluent chain without abandoning it.

The Cloudflare driver that never shipped

If you've read about a Cloudflare driver for this API, complete with Image::pruneOrphaned('cloudflare') on a schedule and validation rules to keep BMP files away from it, that's real code but it isn't in Laravel.

It was in the pull request during review and got pulled before merge. The PR is explicit that the Cloudflare-specific driver and support were removed to keep the first version focused on local processing through GD and Imagick via Intervention. The shipped config/images.php supports two drivers. Setting IMAGE_DRIVER=cloudflare gets you an exception, not remote processing.

Some of the write-ups circulating were based on the PR description rather than the released code, which is an easy mistake to make when a feature changes shape during review. Check php artisan config:publish images and read what's actually in the file. While you're in there, the full command list lives in the Laravel Artisan Commands reference.

The interesting part is what the removal left behind. Custom drivers are a documented extension point:

use Illuminate\Contracts\Image\Driver;
use Illuminate\Image\ImagePipeline;

class VipsDriver implements Driver
{
    public function process(string $contents, ImagePipeline $pipeline): string
    {
        // Apply the pipeline's transformations and output options...

        return $contents;
    }

    public function transformUsing(string $transformation, callable $callback): static
    {
        return $this;
    }
}

Register that with Image::extend('vips', fn () => new VipsDriver) and switch per image with ->using('vips') or globally with IMAGE_DRIVER=vips.

That example name isn't arbitrary. libvips is a fast, low-memory image library that outperforms both GD and Imagick, and Intervention already maintains an official driver for it in Intervention/image-driver-vips. Spatie Media Library already accepts vips as an image_driver value too. Laravel's InterventionDriver only exposes gd and imagick, so you can't reach vips through IMAGE_DRIVER today. But the hard part is done. A Laravel driver for it is a thin adapter over a maintained package, not a from-scratch build, and it's the most obvious gap in the ecosystem right now.

Three things the docs don't make obvious

The queueing advice contradicts the API. The introduction tells you to move heavy processing to a queued job, which is correct advice. But Image instances cannot be serialized, and passing one to a job throws an ImageException. You store first and pass the path, then rebuild with Image::fromStorage() inside the job. Worth knowing before you dispatch, and if you're pushing real volume through, the patterns in processing 10,000 queued tasks without breaking apply here too.

Processing is lazy and cached, which cuts both ways. Nothing runs until you call toBytes(), width(), store(), or cast to string. After that first output the result is reused, so calling width() then store() doesn't process twice. The trap is the other direction: because instances are immutable, branching off a base image to make three variants means three separate pipelines, each doing its own decode.

Storage failures return false, they don't throw. store(), storeAs(), and the public variants return false if the image couldn't be stored. If you assign the result straight to a database column you'll write a boolean into a string field and find out later. Check it.

The decision, in one table

Your job	Reach for
Resize or convert an upload in a controller	`Illuminate\Image`
Generate a few variants from one source	`Illuminate\Image`, one pipeline each
Model has attached files with named sizes	Spatie Media Library
Responsive images with `srcset` markup	Spatie Media Library
Watermarks, text, drawing, animated GIFs	Intervention Image directly
Same, but inside the fluent chain	Custom `Transformation` class
Large volumes, memory pressure	Custom driver over libvips

Memory and CPU are the constraint that decides most of this in production. If you're processing anything sizeable in the request cycle you'll hit it, and the same advice applies as with any big upload path, which I've covered in handling large file uploads without crashing your server.

My take

Use it. For the resize-an-upload case it's cleaner than what you have, it's one less abstraction you maintain, and the immutable pipeline is a better design than the mutable managers both underlying libraries expose.

The criticism raised during review deserves an airing, though. A reviewer argued that bolting image manipulation onto Request, a class already at critical mass, adds bloat, and that image processing is a resource hog that shouldn't be quite this reachable. Both points are fair. $request->image('avatar')->cover(400, 400)->store('avatars') is a very short path to doing something expensive inside a web request, and the docs' warning about queueing is one sentence in an introduction most people skim.

My rule: if the source is user-supplied and unbounded in size, it goes to a queue regardless of how convenient the one-liner looks. The API being easy doesn't make the work cheap.

The part I'd actually watch is the driver contract. A fluent, Laravel-native API where the engine underneath is swappable is more interesting than the transformation methods, because it means the ceiling on this component isn't set by what GD can do. That's also why the Cloudflare removal reads as deliberate rather than a retreat. Ship the extension point, let the drivers arrive later.

FAQ

Does Laravel 13.20 mean I can remove Intervention Image?

No, the opposite. You have to install intervention/image:^4.0 for the GD and Imagick drivers to work. It isn't a hard requirement in the framework's own dependencies, but it's required in practice for anything the shipped drivers do.

Should I replace Spatie Media Library with the new API?

Only if you never used what Media Library is for. If your codebase has registerMediaConversions, media collections, or responsive images, you'd be rebuilding a mature package by hand. If you pulled it in just to crop an avatar, switching is a reasonable simplification.

Can I pass an image instance to a queued job?

No. Image instances aren't serializable and attempting it throws an ImageException. Store the image first, pass the path, and rebuild inside the job with Image::fromStorage().

Is there a Cloudflare driver?

Not in the released framework. It existed in the pull request and was removed before merge so the first version could focus on GD and Imagick. Only gd and imagick are supported out of the box, though the driver contract is public if you want to build your own.

How do I add a watermark with the new API?

Not with the built-in methods, since there's no composition or text support. Either use Intervention Image directly for that operation, or write a custom Transformation class and register a handler with Image::transformUsing() so it works inside the fluent chain.

Wrapping up

The question worth asking isn't which of these three to pick. It's how far up the stack your problem lives. Transforming bytes right now is the bottom, attaching media to models is the top, and 13.20 filled a gap in the middle that most of us had been filling with a service class of our own.

If you're picking between the three for an existing app, start by grepping for registerMediaConversions. If it's there, nothing changes for you. If it isn't, and you've got a hand-rolled image wrapper somewhere in app/Services, you can probably delete it this afternoon. That's also the moment to revisit whether your upload path belongs in the request at all, something I went through in detail while building a full-stack upload system with Vue and S3.

DEV Community: Hafiz

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

The question that decides it

Spatie Permission: permissions are names

Bouncer: abilities can point at a row

Policies still sit on top of both

Multi-tenancy is where they diverge again

The cache bug that catches both

What I'd actually choose

FAQ

Can I migrate from Spatie to Bouncer later?

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

Which one for a multi-tenant SaaS?

Is Bouncer still maintained?

The thing worth remembering

Every AI Word You Keep Hearing, Explained With Laravel Code

Layer 1: what the model actually is

Layer 2: what turns a model into an agent

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

Layer 4: how it reaches the rest of your system

Layer 5: how you stop it hurting you

What to build first

What I'd skip

FAQ

Do I need Python for any of this?

Do I need a vector database like Pinecone or Qdrant?

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

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

The thing worth remembering

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

What a failed query actually writes

Where that string ends up

The switch in Laravel 13.27

The part the announcement gets slightly wrong

Cleaning up what's already there

What you lose, and how to get it back

FAQ

Does this affect Laravel 12 or older?

Will masking change how my error tracker groups events?

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

Is this a GDPR requirement?

The one line, and the second one

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

The idea: one box, many windows

The stack, and why each piece

The blueprint

Provisioning: four scripts and four manual steps

The three commands you'll actually use

Staging behind Cloudflare Access

Migrating a project onto the box

Working from the phone

The control panel

Everything that broke

What it costs and what it feels like

FAQ

Why not just use Tailscale for the staging sites too?

Does Claude Code keep running when the phone disconnects?

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

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

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

The mental model in one line

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

What SuperNative actually does

The setup, and the first wall

Build the screen

The data layer is just Laravel

The component

The view

Run it on your phone without Xcode

You can test screens without a device

The sharp edges

Should you build with it?

FAQ

Do I need a Mac to try this?

Is NativePHP v4 free?

Does my existing Livewire knowledge transfer?

How is this different from React Native or Flutter?

Can I still use a webview for some screens?

The short version

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

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

Do the `#[IsReadOnly]` and `#[IsDestructive]` annotations prevent a tool from doing damage?