DEV Community: Hafiz

Sitemap Timing Test

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

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

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.

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

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.

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.

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

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

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.

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

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

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.

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.

Human-in-the-Loop for Laravel AI Agents: Stop Your Agent Before It Refunds the Wrong Order

Hafiz — Mon, 03 Aug 2026 05:54:31 +0000

Your support agent has a refund tool. A customer sends a message that sounds close enough to a refund request, the model decides that's what it wants, and four thousand euros leaves your Stripe account before a human reads a single word of the conversation.

Until 21 July there was no framework-level way to stop that. Once a Laravel AI SDK agent started its tool loop, it ran to the end on its own. You could validate arguments inside handle(). You could build allowlists. You could keep the dangerous tools out of the agent entirely and accept that your agent is now read-only. What you couldn't do was put a person in the middle of the loop.

laravel/ai v0.10.0 changed that. The human-in-the-loop API pauses the agent before an approvable tool executes, hands the pending call back to you, and waits. The Laravel team announced it at Laracon US, the code landed in laravel/ai#773, and the docs cover the happy path well.

This post assumes you've already got an agent running. If you haven't, start with building your first Laravel AI SDK assistant and come back.

The happy path isn't the interesting part. The interesting part is what happens when generation fails halfway through, when two tools land in the same step, and when the person clicking "approve" isn't the person who owns the conversation.

What actually shipped

Approval is opt-in, per tool. A tool becomes approvable when it implements the Approvable contract and uses the InteractsWithApprovals trait. That's the whole opt-in:

<?php

namespace App\Ai\Tools;

use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class IssueRefund implements Approvable, Tool
{
    use InteractsWithApprovals;

    public function description(): Stringable|string
    {
        return 'Refund an amount against a customer order.';
    }

    public function handle(Request $request): Stringable|string
    {
        $order = Order::findOrFail($request['order_id']);

        $order->refund($request['amount']);

        return "Refunded {$request['amount']} on order {$order->id}.";
    }

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

Once that trait is on the class, the tool requires approval every single time. Which is almost never what you want.

Everything else about the tool stays the same. The description, handle, and schema methods work exactly as they do on any other tool, so if you've already built an agent with tools and conversation memory, you're adding two lines to a class you already have.

Approving everything is the wrong default

A tool that asks permission for every call trains people to click approve without reading. That's worse than no approval at all, because now you have an audit trail that says a human reviewed something nobody reviewed.

Gate it on the arguments instead. Define a needsApproval method that returns a boolean, or an Approval instance carrying the reason the model's caller will see:

use Laravel\Ai\Approvals\Approval;

protected function needsApproval(Request $request): Approval|bool
{
    return $request['amount'] <= 20000
        ? false
        : Approval::required('Refunds over 200 EUR need a manager.');
}

Amounts are in cents here, so anything up to 200 EUR goes straight through and anything above it stops. The reason string matters more than it looks, because it's what gets rendered next to the approve button, and a reason like "approval required" tells the reviewer nothing about why this specific call is different.

You can also flip the requirement where the agent registers its tools, which is useful when the same tool is safe in one agent and dangerous in another:

public function tools(): iterable
{
    return [
        (new LookUpOrder)->withoutApproval(),
        (new IssueRefund)->requireApproval('Every refund gets reviewed.'),
    ];
}

The prerequisite buried at the top of the docs

Tool approval needs a Conversational agent whose history is actually persisted. There has to be something to resume from, and an agent that rebuilds its messages from an array in memory has nothing to come back to.

The RemembersConversations trait handles it:

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\IssueRefund;
use App\Ai\Tools\LookUpOrder;
use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

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

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

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

One trap here predates the approval API and still catches people: if you define a messages method on an agent that uses RemembersConversations, your method wins and the trait never loads history from the database. No conversation, nothing to resume.

Put an approvable tool on an agent that can't be resumed at all and you don't get a silent failure. The SDK throws ApprovalNotResumableException rather than handing back a pause nobody can resolve, which is the right call and saves you a debugging session.

The pause and the resume

When the model calls an approvable tool, the agent stops short of running it. The pending calls come back on the response:

$response = (new SupportAgent)
    ->forUser($user)
    ->prompt('Refund the damaged headphones on order 4192.');

if ($response->hasPendingApprovals()) {
    foreach ($response->pendingApprovals as $approval) {
        // $approval->id
        // $approval->tool
        // $approval->arguments
        // $approval->reason
    }
}

To resume, you continue the conversation and pass a Decisions instance keyed by tool call ID:

use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;

$response = (new SupportAgent)
    ->continue($conversationId, as: $user)
    ->prompt(Decisions::from([
        'call_abc' => Decision::approve(),
        'call_ghi' => Decision::reject('This order is outside the return window.'),
    ]));

Note what's happening there. The decisions are the prompt. You're not calling some separate approval endpoint on the SDK, you're continuing the same conversation with a different kind of input, which is why the routing for this collapses into one endpoint later.

Booleans work as shorthand for approve and reject. Every pending call needs a decision or you get an ApprovalMismatchException, and that same exception covers IDs you made up and calls that were already resolved. If you don't want to enumerate all of them, set a default for the rest:

$decisions = Decisions::from([
    'call_abc' => true,
])->rejectRemaining('Not approved.');

Decision::approveAll() and Decision::rejectAll() cover the blanket cases and return a Decisions instance, so they drop straight into the same prompt call.

There's a meaningful difference between the two kinds of rejection. Decision::reject('reason') sends that string back to the model, which keeps responding and can explain the refusal to the customer. A rejection with no result records the rejection and stops the generation loop right there. Pick deliberately. A silent stop looks like a hung chat window to whoever is on the other end.

The third decision nobody covered

Approve and reject are the two everyone writes about. There's a third:

use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;

$response = (new SupportAgent)
    ->continue($conversationId, as: $user)
    ->prompt(Decisions::from([
        'call_abc' => Decision::edit(['order_id' => 4192, 'amount' => 20000]),
    ]));

Decision::edit() approves the call with replaced arguments. The model asked to refund 4,000 EUR, the manager decides 200 is right, and the tool runs with the corrected amount. No rejection, no second round trip, no asking the customer to explain themselves again.

This is the decision type that makes approval feel like review rather than a gate, and it's the one missing from every writeup of the release so far. One rule to remember: an edit decision has to carry arguments. A bare one throws.

Here's the full round trip:

Three failure modes worth knowing before you ship

The approval you already spent. Laravel records an approved tool's result before it asks the model to continue generating. If generation blows up after that point, the tool already ran. Resubmitting the same decisions throws an ApprovalMismatchException, and the reference HTTP flow turns that into a 409 carrying the current pending approvals so a stale approval screen can refresh itself. Recover by continuing with an ordinary text prompt, never by replaying the decision map. Worth knowing alongside this: the SDK will not fail over to a backup provider on a resume once approved tools have executed, so a provider outage mid-resume surfaces as an error instead of quietly running your refund somewhere else.

Pauses are per call, not per step. If the model requests three tools in one step and only one of them is approvable, the other two run immediately while the third waits. Anything with an external side effect needs to be idempotent, and $request->toolCallId() gives you the key to deduplicate on. This is the part most people will get wrong, because the mental model everyone brings is "the agent stops", and what actually stops is one call.

Streaming and broadcasting need their own handling. Approval works with prompt, stream, queue, broadcast, broadcastNow, and broadcastOnQueue. During streaming a pause arrives as a tool_approval_request event, and under the Vercel AI SDK stream protocol it maps to that protocol's native tool approval parts. Queued agents pass the response to the then callback and dispatch a ToolApprovalRequested event. There's a matching ToolApprovalResolved event too, which is the one you want for your audit log.

Authorization is still your job

There's a sentence in the conversations docs that most people skim: continue() does not verify that the participant you pass actually owns the conversation. Authorizing that is on you.

The approval work narrows what that means. The hardening pass on the pull request added an ownership check before a resume runs any gated tool, so the obvious nightmare, one user approving a refund sitting in someone else's conversation, is closed at the framework level. Good. What isn't closed is everything around it. An unauthorized continue() still reads back conversation history, and that history now includes the arguments of every pending tool call: order IDs, amounts, file paths, whatever your tools take.

So authorize the conversation, every time:

Route::post('/chat/{conversation}', function (Request $request, Conversation $conversation) {
    Gate::authorize('view', $conversation);

    // ...
})->middleware('auth');

Then go one step past that. The SDK checks ownership, not authority. "Owns this conversation" and "may approve a 4,000 euro refund" are two different questions, and only the first one has a built-in answer. If your reviewers have tiers, inspect the tool name and arguments on the pending approval before you accept a decision, not after. A junior support rep owning the conversation they're working is normal. A junior support rep clearing a four-figure refund usually isn't.

For the coding-agent version of the same question, I wrote about what happens when you hand an AI agent too much authority in a Laravel app a few months back. Different threat model, same root question: what can this thing reach, and who said it could.

Wiring it into one endpoint

The whole thing fits in a single route, because decisions and messages are both just prompts.

Validate that you got one or the other, never both. A request carrying a message and a decisions array at the same time is ambiguous, so make the rules mutually exclusive with required_without and prohibited_with.
Map the incoming array into Decision objects. Each key is a tool call ID and each value carries an action plus an optional result string.
Build the prompt. Either a Decisions instance or the raw message string.
Continue the conversation with ->continue($conversation->id, as: $request->user()) and pass the prompt.
Return the status. If hasPendingApprovals() comes back true, hand pendingApprovals to the frontend and let it render the buttons.

$validated = $request->validate([
    'message' => ['nullable', 'string', 'required_without:decisions', 'prohibited_with:decisions'],
    'decisions' => ['nullable', 'array', 'required_without:message', 'prohibited_with:message'],
    'decisions.*.action' => ['required_with:decisions', Rule::in(['approve', 'reject'])],
    'decisions.*.result' => ['nullable', 'string'],
]);

$prompt = isset($validated['decisions'])
    ? Decisions::from(collect($validated['decisions'])->map(
        fn (array $decision) => match ($decision['action']) {
            'approve' => Decision::approve(),
            'reject' => Decision::reject($decision['result'] ?? null),
        }
    )->all())
    : $validated['message'];

$response = (new SupportAgent)
    ->continue($conversation->id, as: $request->user())
    ->prompt($prompt);

return [
    'status' => $response->hasPendingApprovals() ? 'awaiting_approval' : 'complete',
    'message' => $response->text,
    'approvals' => $response->pendingApprovals,
];

The frontend posts back a shape like {"decisions": {"call_abc": {"action": "approve"}}}, keyed by the tool call ID it received.

Testing it without touching a provider

This is the part of the release that got no coverage at all, and it's the part that decides whether the feature survives contact with your CI pipeline.

You can fake a response that's awaiting approval:

use Laravel\Ai\Approvals\PendingApproval;
use Laravel\Ai\Responses\AgentResponse;

SupportAgent::fake([
    AgentResponse::fakeWithPendingApprovals([
        new PendingApproval(
            id: 'call_abc',
            tool: 'IssueRefund',
            arguments: ['order_id' => 4192, 'amount' => 400000],
            reason: 'Refunds over 200 EUR need a manager.',
        ),
    ]),
]);

$response = (new SupportAgent)->prompt('Refund order 4192.');

expect($response->hasPendingApprovals())->toBeTrue();

And you can assert on the decisions that were submitted:

SupportAgent::assertPrompted(function (AgentPrompt $prompt) {
    return $prompt->hasApprovalDecisions()
        && $prompt->approvalDecisions->get('call_abc')->isApproved();
});

That means the interesting cases are all testable without a network call. Does an unauthorized user get blocked before their decision reaches the agent? Does a partial decision set throw? Does a rejection with no result actually stop the loop? Write those before you ship, not after the first incident. If you're setting up the suite, my Pest testing guide covers the structure I'd use here, and Pest 5's test impact analysis will keep these off the runner when you're changing something unrelated.

Upgrading to 0.10

Three breaking changes, two of which you'll actually feel. There's a new nullable approval_state column on the conversation messages table, so publish and run the migrations. Any custom ConversationStore implementation now has to provide a storeApprovalResults() method. And the Agent contract's prompt methods widened from string to accept decisions as well, which is a no-op if your agents use the Promptable trait and a signature change if you implement the contract yourself.

Then there's the behavior change that isn't filed as breaking and will surprise you anyway: the built-in WriteFile, CopyFile, and DeleteFile filesystem tools now require approval by default. If you hand agents a disk with FileStorage::all(), those three start pausing the moment you upgrade. Decide deliberately which ones get withoutApproval() rather than discovering it from a stuck conversation.

Worth saying plainly: this package is at 0.10. It's pre-1.0, the API surface around approvals is young, and the repository has open work on multi-step approval resume. Pin your version rather than floating on dev-main, and read the diff on minor bumps.

My take

Use this on anything that spends money, deletes data, or sends a message to a third party. Don't use it on reads. That line is easy to hold and it survives code review, which is more than you can say for most security policies.

The trade-off is real, though. Every approval gate is a place where a conversation stops and waits for a human who may be asleep, and an agent that pauses six times per session is a worse product than one that pauses once. Threshold-based needsApproval is the answer, and the threshold should come from your actual refund data, not from a number that felt safe on a Tuesday.

I'd also push back gently on the framing that this makes agents "safe". It makes one class of action reviewable. The agent can still be prompt-injected into calling a tool with plausible-looking arguments, and a reviewer skimming ten approvals an hour will wave that through. Approval is a control, not a guarantee. Pair it with argument validation inside handle() and allowlists at the schema level, the way the SDK's own database tool guidance recommends.

The API itself is good. It's small, it's opt-in per tool, it degrades to a normal prompt, and it's testable. That's about as much as you can ask from a first release.

FAQ

Does tool approval work with queued agents?

Yes. It's supported by prompt, stream, queue, broadcast, broadcastNow, and broadcastOnQueue. For queued agents the response arrives in the then callback and Laravel dispatches a ToolApprovalRequested event you can listen for.

What happens if I only decide on some of the pending calls?

You get an ApprovalMismatchException. Every pending call needs a decision. Use approveRemaining() or rejectRemaining() to set a default for the ones you didn't name explicitly.

Can I change the arguments before the tool runs?

Yes. Decision::edit(['amount' => 20000]) approves the call with replaced arguments instead of the ones the model proposed. The edit has to carry arguments; a bare edit decision throws.

Do I need a database for this?

Yes. Approval requires a Conversational agent with persisted history, which means running the AI SDK migrations and using RemembersConversations or your own ConversationStore.

Is one approval gate enough to secure an agent?

No. It reviews one action at one moment. You still want validated tool schemas, allowlisted tables and columns for anything touching the database, and authorization on the conversation itself before a decision is accepted.

Wrapping up

The pattern that matters here isn't the trait or the contract. It's that a dangerous tool call is now a piece of state your application can hold, inspect, authorize, and resolve later, instead of something that either happened or didn't while nobody was watching.

Start with one tool. Pick the one that would ruin your week if it fired wrong, make it approvable, gate it on arguments, and authorize the conversation before you accept a decision. That's an afternoon of work and it changes the risk profile of the whole agent.

Pest 5 TIA: Run Only the Tests Your Code Change Touched

Hafiz — Thu, 30 Jul 2026 05:22:01 +0000

Nuno Maduro announced Pest 5 on stage at Laracon US yesterday, and one feature is worth your attention today: the Tia Engine. TIA stands for Test Impact Analysis, and the pitch is simple enough to sound too good to be true. A Laravel suite that took 10 minutes now finishes in around 4 seconds, because Pest reruns only the tests your latest change could actually break and replays cached results for everything else.

This shipped yesterday, so this is a walkthrough of how it works from the docs and the release, not a battle-tested war story. I'll be clear about what's proven and what you'll want to verify on your own suite. But the mechanism is well documented, the numbers come from Pest directly, and the setup really is a one-flag start. Here's what TIA does, how to turn it on, the CI trick that makes it fast for your whole team, and the catch nobody mentions in the announcement tweets.

What Test Impact Analysis Actually Does

The idea behind TIA isn't new (large monorepos at Google and Meta have done impact analysis for years), but it's new to have it built into a PHP testing framework you already use. The concept: most of your test suite is irrelevant to any given change. You edit one model, and 765 of your 774 tests couldn't possibly behave differently. Running all 774 is wasted time. TIA figures out which handful actually depend on what you touched, runs those, and reconstructs the rest from cache.

The first run builds a baseline: Pest records a dependency graph of which tests exercise which files. Every run after that is a replay. Pest diffs your working tree against the baseline and reruns only the affected tests. The output tells you exactly what happened:

Tests:    774 passed (2658 assertions, 7 affected, 2 uncached, 765 replayed)
Duration: 3.92s

Read that line: 7 tests actually ran because their dependencies changed, 2 ran because no cached result existed yet, and 765 were served from cache. Four seconds instead of ten minutes.

The part I found most reassuring in the docs: a replay isn't a shortcut that skips coverage. Pest stores what each test covered, down to lines and branches, so a replayed run reports the same coverage as a full run. Your --coverage report, coverage thresholds, and --min all behave as if every test executed. You get the speed without lying to your coverage gate.

Turning It On

One flag on any Pest invocation:

./vendor/bin/pest --parallel --tia

There's one hard requirement, and it's the thing that'll trip people up: TIA needs a code coverage driver, either PCOV or Xdebug, installed and enabled. Pest uses it to record which files each test touches while building the baseline. No coverage driver, no dependency graph, no TIA. If you already run coverage in CI you have this; if you've never installed PCOV locally, that's your first step.

The other requirement is the bigger gate: Pest 5 requires PHP 8.4 or higher. It's built on PHP 8.4 and PHPUnit 13. If you're on an older PHP version, TIA is a reason to plan the upgrade, not something you can try this afternoon. (If you're mid-migration on the framework side, my Laravel 12 to 13 upgrade guide covers that half.)

If you'd rather not type the flag every time, configure it in tests/Pest.php:

pest()->tia()
    ->always()     // run TIA on every invocation, no --tia flag
    ->locally()    // but only on local machines, skip on CI
    ->baselined()  // fetch the shared baseline from CI when missing
    ->filtered();  // narrow PHPUnit to only affected test files

The always()->locally() pairing is the sensible default for most teams: fast replays while you work, full runs on CI where you want every test to execute for real. An explicit --tia always wins, and --no-tia disables it for a single run.

How TIA Decides What To Rerun

This is where it stops being magic and starts being understandable, and understanding it is what tells you whether to trust it. TIA maps different file types to tests in different ways:

For PHP source files, the coverage driver does the work. Change app/Models/User.php and Pest reruns only tests that touched User. For migrations, Pest intersects the change against the tables each test queried during the baseline, so a column rename in the users migration reruns only tests that hit the users table. Blade templates rerun only the tests that rendered them. If you're on Inertia, Pest walks Vite's module graph to trace which pages import a changed component and reruns only the tests that server-side-rendered those pages.

Then there's the honest fallback. Config files, route files, fixtures, anything outside the recorded graph triggers a broader pattern. Edit config/app.php and Pest reruns the entire suite, because it can't statically prove which tests depend on it. That's the correct behavior, and it's a good sign: TIA errs toward running too much rather than missing a regression. Some changes rebuild the graph itself, like composer.lock, phpunit.xml, and Node lockfiles.

The Detail That Sells It: Cosmetic Edits Run Nothing

Here's the feature that makes TIA feel different from a dumb file-timestamp cache. Pest normalizes file content before comparing. PHP files get whitespace, line comments, and docblocks stripped before hashing. Blade strips its {{-- --}} comments. JS, TS, Vue, and Svelte lose their comments too.

The practical result: a comment-only edit, a Prettier reformat, a Pint pass, or a README tweak produces an identical hash. The file never enters the changed set. Zero tests run. If you've ever watched your full suite grind through CI because someone reformatted a file, you understand why that matters.

Sharing the Baseline: The CI Trick

Recording the baseline takes as long as one full suite run, which on a large project is minutes. Paying that on every developer's machine, and every fresh checkout, would undercut the whole point. Pest's answer: record the baseline once in CI, and have everyone else download it.

You enable fetching with pest()->tia()->baselined() in tests/Pest.php (preferred for teams). When Pest finds no local graph, it uses the GitHub CLI to pull the pest-tia-baseline artifact from your latest successful baseline workflow, validates it against your project state, and adopts it if it matches. Every developer's first --tia run then replays immediately, paying no record cost.

The workflow that produces that artifact, dropped into .github/workflows/tia-baseline.yml:

name: TIA Baseline
on:
  push: { branches: [main] }
  schedule: [{ cron: '0 3 * * *' }]
  workflow_dispatch:
jobs:
  baseline:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.4', coverage: xdebug }
      - run: composer install --no-interaction --prefer-dist
      - name: Run tests
        run: ./vendor/bin/pest --parallel --tia --coverage --fresh
      - name: Resolve TIA baseline path
        id: baseline
        run: echo "path=$(./vendor/bin/pest --baseline)" >> "$GITHUB_OUTPUT"
      - name: Upload TIA baseline
        uses: actions/upload-artifact@v4
        with:
          name: pest-tia-baseline
          path: ${{ steps.baseline.outputs.path }}
          include-hidden-files: true
          retention-days: 30

Two things to know here. ./vendor/bin/pest --baseline prints the absolute path to the TIA storage directory (~/.pest/tia/<project-key>/), which is what the upload step bundles. And include-hidden-files: true is required, because that directory is dot-prefixed and Actions skips hidden files by default. Fetching relies on the GitHub CLI being installed and authenticated, so it's GitHub-only for now; on any failure Pest falls back to recording locally and tells you why. If you don't have a Pest CI pipeline yet, my GitHub Actions guide for Laravel is the place to start before wiring this in.

The Catch Nobody's Tweeting About

The announcement numbers are real, but here's what to keep in mind before you assume your suite drops to 4 seconds tomorrow.

TIA's speedup is proportional to how well-isolated your tests are. If most of your tests are unit tests touching a handful of classes, a small change reruns almost nothing and you get the headline numbers. If your suite is mostly full feature tests that boot the whole app and hit the database, more of them qualify as "affected" by any given change, and the win shrinks. The 10-minutes-to-4-seconds figure describes a well-structured suite, not a guaranteed outcome for every codebase.

There's also a trust question worth being deliberate about. TIA is deciding not to run tests. That's the entire point, and the coverage-fidelity design is reassuring, but this is day-one software. The safe pattern is exactly what the config nudges you toward: always()->locally() for fast local replays, and full untia'd runs on CI as the source of truth. Let TIA speed up your inner loop first. Trust it to gate your deploys only once you've watched it behave on your real codebase for a while. That's not skepticism about Pest; it's how you'd adopt any tool that skips work on your behalf.

What Else Shipped in Pest 5

TIA is the headline, but the release bundled several first-party plugins that matured across the Pest 4 cycle. Worth knowing they exist:

The Agent plugin gives AI coding agents a single command to verify a change actually works against your real suite, and with the Browser plugin, in a real browser too. Evals let you score LLM output and AI-generated results from inside your test suite, mixing deterministic checks with AI scorers. And PHPStan and Rector are now built in, so static analysis and automated refactoring live alongside your tests instead of as separate tooling. If you're still on Pest 4, my complete Pest 4 testing guide still applies for the fundamentals; Pest 5's testing API is the same, with these plugins layered on top.

FAQ

Do I need to change how I write tests to use Pest 5 TIA?

No. TIA works with your existing tests unchanged. You add the --tia flag (or configure it in tests/Pest.php) and Pest builds the dependency graph automatically from a normal run. Your test files, expectations, and structure stay exactly as they are.

Does TIA reduce my code coverage numbers?

No, and this is the clever part. When Pest caches a test it stores the exact lines and branches that test covered, so a replayed run reports the same coverage as a full run. Coverage thresholds, the --coverage report, and --min all behave as if every test executed from scratch.

What happens when I change a config or route file?

Pest reruns the entire suite. Files outside the recorded dependency graph, including config and route files, can't be statically traced to specific tests, so TIA falls back to running everything rather than risk missing a regression. It errs toward safety.

Can my whole team skip the slow first baseline run?

Yes, if you're on GitHub. Record the baseline once in a CI workflow, upload it as the pest-tia-baseline artifact, and enable pest()->tia()->baselined(). Each developer's first --tia run downloads that baseline and replays immediately instead of recording locally. It relies on the GitHub CLI, so it's GitHub-only for now.

Should I trust TIA to gate my production deploys?

Be cautious at first. TIA shipped at Laracon US 2026, so it's brand new. The sensible adoption path is always()->locally(): fast replays while you develop, full runs on CI as your source of truth. Once you've watched TIA behave correctly on your real suite over time, you can decide whether to lean on it further.

Does Pest 5 TIA need a specific PHP version?

Yes. Pest 5 requires PHP 8.4 or greater and is built on PHPUnit 13. TIA also needs a coverage driver (PCOV or Xdebug) to record the baseline. If you're on an older PHP version, upgrading is a prerequisite.

Wrapping Up

TIA is the kind of feature that changes a daily habit rather than adding one. The slow test suite you run less often than you should, or gate behind a coffee break, becomes something fast enough to run after every save. Add --tia, make sure you've got PHP 8.4 and a coverage driver, and let it speed up your local loop first. Wire up the CI baseline once your team wants the shared graph. And keep your CI running the full suite untia'd until you've earned trust in the replays on your own codebase.

Laravel Scout in 2026: Meilisearch vs Typesense vs Algolia vs Database Driver

Hafiz — Mon, 27 Jul 2026 06:41:24 +0000

Laravel Scout gives you full-text search on your Eloquent models with one trait and a config value. What it doesn't give you is an opinion. The docs list five drivers (Algolia, Meilisearch, Typesense, database, and collection) and treat them as interchangeable. They're not. The driver you pick decides whether search costs you nothing, a fixed monthly fee, or a bill that grows every time your product succeeds.

I've shipped Scout with three of these drivers across client projects and my own products. This post is the comparison I wish existed: what each driver actually does, what it costs at real usage levels, and a straight answer on which one to pick.

What Scout Actually Abstracts

Quick grounding for anyone who hasn't used it. Scout syncs your models to a search index automatically. Add the Searchable trait, and every create, update, and delete flows through to your search engine via model observers:

use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    public function toSearchableArray(): array
    {
        return [
            'title' => $this->title,
            'body' => strip_tags($this->body),
        ];
    }
}

Searching is one line: Post::search('pgbouncer')->paginate(15). The abstraction is the whole point: your application code stays identical across all five drivers, which means the driver decision is about operations and money, not code.

One setting that isn't optional in production: 'queue' => true in config/scout.php. Without it, every model save blocks on an HTTP call to your search engine. Push index updates through your queue workers and the write path stays fast. And a detail that surprises people: even with queueing off, Algolia and Meilisearch index asynchronously on their side. Your job finishing doesn't mean the record is searchable yet. Write your tests accordingly.

The Four Real Contenders

The collection driver filters records in PHP after pulling them all from the database. It exists for local development and works everywhere, including SQLite. It's not a production option, so it's out of the comparison. That leaves four.

The database driver runs full-text indexes and LIKE clauses against MySQL or PostgreSQL. No new infrastructure, no sync problems (it queries your actual tables), no cost. Also: no typo tolerance, no relevance tuning worth the name, no facets.

Meilisearch is an open-source engine written in Rust. Sub-50ms responses, typo tolerance, faceting, and highlighting out of the box with almost no configuration. Its defaults are good enough that most projects never touch relevance settings. Self-host it free (MIT license) or use Meilisearch Cloud.

Typesense is the closest thing Meilisearch has to a twin: open-source, typo-tolerant, instant search, written in C++. It differentiates on operational predictability. Typesense Cloud gives you a dedicated cluster priced by RAM and CPU per hour, with no per-record or per-operation charges at all. It also has more mature vector and geo search than Meilisearch.

Algolia is the incumbent hosted service. The most polished dashboards, the best frontend libraries (InstantSearch), AI re-ranking, and enterprise features nobody else matches. You pay for it with usage-based pricing that scales with your traffic.

Feature Comparison: Where They Actually Differ

On core search quality (typo tolerance, prefix matching, ranking) Meilisearch, Typesense, and Algolia are closer than their marketing suggests. All three return results in tens of milliseconds and handle "labrvel" finding "laravel" without configuration. For a typical SaaS search box, users can't tell them apart.

The differences live at the edges. Algolia leads on merchandising and AI features: synonyms management, A/B testing relevance, personalization. If you're building e-commerce search where a 2% conversion lift pays for the tooling, that matters. Typesense leads on vector search and its Search Delivery Network, which replicates your index across regions like a CDN. Meilisearch leads on getting to good results with the least configuration of the three.

The database driver isn't playing the same sport. It matches words, roughly in the order your database returns them. Search for "posgres" and you get nothing, because there's no typo tolerance. For a public-facing product search, that's disqualifying. For an admin panel where your team searches customers by name or email, it's completely fine, and I'd argue anything more is over-engineering.

The Money: What Search Actually Costs

This is where the comparison stops being close, so let's do real math. All prices verified this week; search providers change pricing often, so treat these as July 2026 numbers.

Algolia has a free Build tier (10,000 search requests a month) that's generous for prototyping. The paid Grow plan is pay-as-you-go: $0.50 per 1,000 search requests and $0.40 per 1,000 records beyond the included 10,000 requests and 100,000 records. Grow Plus, which adds the AI features, jumps to $1.75 per 1,000 requests.

Meilisearch Cloud starts at $30/month for the Build plan and climbs into the hundreds at the million-document tier. Self-hosting is free under MIT.

Typesense Cloud bills the cluster, not the usage: pick RAM and CPU, pay per hour it runs. The smallest configurations work out to roughly $7-25/month, and you can throw as many searches at it as the hardware handles. Self-hosting is free.

The database driver costs zero. Your database is already running.

Now the worked example. Say your app does 500,000 searches a month across 250,000 records, a realistic mid-sized SaaS:

Algolia Grow: 490,000 billable requests ($245) plus 150,000 extra records ($60) lands around $305/month. Every new user who searches makes next month's bill bigger. Meilisearch Cloud at that document count sits in its higher tiers, roughly the $200-300/month range. Typesense Cloud handles that load comfortably on a small dedicated cluster in the $25-70/month range, and the bill doesn't move when traffic doubles until the hardware runs out. Self-hosted Meilisearch or Typesense on a basic Hetzner or DigitalOcean instance: about €5-10/month for the server, and the real cost is you being the person who gets paged.

That's a 30x spread for the same feature. The pricing model matters more than the sticker price: Algolia charges you for growth, Typesense charges you for capacity, self-hosting charges you in responsibility.

When the Database Driver Is Honestly Enough

The advice you'll find everywhere is "just use Meilisearch," and it's not wrong. But I want to defend the boring option, because I keep seeing projects run a search server for workloads that don't need one.

Use the database driver when all of these are true: your searchable dataset is under roughly 100,000 rows, your users are internal or forgiving (admin panels, back-office tools, MVPs), and you're searching short fields like names, emails, and titles. MySQL and Postgres full-text indexes are fast at this scale, and a proper index is the only tuning you'll ever do. You skip a service, a sync pipeline, a deploy dependency, and a monthly bill.

Move up when users start expecting typo tolerance, when you need facets and filters on the search page, or when search becomes part of the product rather than a utility. You'll feel the moment. And because Scout abstracts the engine, the migration is a config change plus php artisan scout:import, not a rewrite. That's the quiet superpower of building on Scout even when you start on the database driver.

My Recommendation

For most Laravel apps in 2026: self-hosted Meilisearch if you already run a VPS, Typesense Cloud if you don't want to.

Meilisearch wins the self-host case because it's the least operational search server I've run: one binary, sane defaults, and it sits happily in 512MB of RAM for small datasets. If you deploy with Docker or manage a Hetzner box already, adding it costs you an evening. Typesense wins the managed case because resource-based pricing means your search bill is a known number, and known numbers are worth a lot to a bootstrapped product. A SaaS charging monthly should not have a cost line that scales per-search.

Pick Algolia when its extras are the point: merchandising tools, the InstantSearch frontend stack, AI ranking for an e-commerce catalog where relevance is revenue. It's the best product of the three and priced like it knows.

And pick the database driver more often than the internet suggests. Half the Scout setups I've reviewed could have been a full-text index.

One operational note whichever engine you choose: if you're running Octane or serious queue concurrency, keep Scout's queue on and give indexing jobs their own queue name. A bulk import re-indexing 100K models on the same queue as your password-reset emails is a bad afternoon.

FAQ

Can Laravel Scout do semantic or vector search?

Scout itself is engine-agnostic, so it depends on the driver. Typesense has the most mature vector search of the three engines; Meilisearch's is newer and improving fast. If semantic search is central to your product, that's a different architecture conversation than a search box, and I've covered the options in my guide to full-text, semantic, and vector search in Laravel.

Which Scout driver is fastest?

For end-user perception, Meilisearch, Typesense, and Algolia are all effectively instant (tens of milliseconds) on typical datasets. The database driver is fast at small scale and degrades as tables grow and queries lean on LIKE. If you're choosing between the three engines on latency alone, you're optimizing the wrong variable; choose on cost model and features.

Does switching Scout drivers require code changes?

Almost none, and that's Scout's best feature. Your models, toSearchableArray(), and search calls stay the same. You change SCOUT_DRIVER, add the new engine's credentials, and run php artisan scout:import to build the index. The exceptions are engine-specific features like Typesense's schema definitions or Algolia-specific query options, which you'd need to recreate or remove.

Is the database driver production-ready?

Yes, within its limits. It uses real full-text indexes on MySQL and PostgreSQL rather than naive LIKE scans, and it can't drift out of sync because it queries your actual tables. What it lacks is typo tolerance, ranked relevance, and facets. Internal tools and small catalogs: absolutely. Public product search where users type fast and expect Google-ish forgiveness: use a real engine.

Do I need Scout at all, or can I use Meilisearch directly?

You can use any engine's SDK directly, and for complex multi-index setups some teams do. Scout earns its place through the automatic model syncing and the driver abstraction that makes engines swappable. For the common case of "make these models searchable," writing your own sync layer is reinventing a wheel Scout ships for free.

Wrapping Up

Scout's driver choice is a cost-model choice wearing a technical costume. The database driver is free and underrated for internal tools. Self-hosted Meilisearch is the sweet spot for developers who already run servers. Typesense Cloud buys you a predictable bill. Algolia buys you the most product for the most money, priced per unit of your own growth. Start boring, and let Scout's abstraction make the upgrade a config change instead of a project.

Setting up search for a Laravel app, or trying to cut an Algolia bill that grew faster than revenue? I've done both and I'm happy to talk through your setup. Get in touch.

Laravel Telegram Bot: How I Cleared My YouTube Watch Later with AI Summaries

Hafiz — Thu, 23 Jul 2026 12:28:54 +0000

My YouTube Watch Later had 42 videos in it. I'd watched maybe ten. X bookmarks were worse because I couldn't even remember why I'd saved half of them. Every platform has a save button, and every save button leads to the same place: a list nobody ever opens again.

The obvious fix is "build something that syncs those lists and reminds you." I tried. That version is impossible, and knowing why shapes the whole design. So I built the opposite: a Telegram bot backed by a small Laravel app that replaces the save button instead of syncing it. I forward a link, it fetches the content, summarizes it with the AI SDK, and then, once a day, it forces me to decide: watch, snooze, or archive.

I've been running it for ten days. Here's the build, including the security bug that almost shipped and the fallback path that fires way more often than I expected.

Why You Can't Sync Watch Later (So Stop Trying)

The dream version of this tool connects to your accounts and pulls your saved items. Two hard walls and one soft one:

YouTube's Data API deliberately excludes the Watch Later playlist. Access was removed years ago and never came back. You can read any playlist except that one.

Facebook's saved items have no API at all.

X bookmarks are the soft one. They do have an API, and since April 2026 reading your own data costs $0.001 per item, so pulling a thousand bookmarks runs about a dollar. But you still need a paid developer account with credits loaded and an OAuth flow to get there, and it only solves X. YouTube and Facebook stay shut either way.

This is why no existing tool does real sync. The workaround is to own the capture step: don't read their list, become the list. On mobile that's the native share sheet, which already has Telegram in it. Share, tap the bot, done. On desktop it's a bookmarklet that POSTs the current URL to the app. Either way, the platform's save button never gets touched again.

The Architecture

The stack is deliberately boring: Laravel 13, SQLite in WAL mode, the database queue driver, and the Telegram Bot API called through plain HTTP. No Telegram SDK package. The bot surface is four methods (sendMessage, editMessageText, answerCallbackQuery, setWebhook), and a thin service class wrapping Laravel's Http client covers them in about 60 lines. Zero extra infrastructure: no Redis, no Node process, no third-party queue.

There's also no frontend. Telegram is the UI, which means the tool works on mobile, desktop, and web from day one without me writing a single screen.

The flow from save to digest looks like this:

The webhook does three jobs: it accepts new links, it answers commands like /stats, and it handles the button presses coming back from digest messages. Everything slow happens in a queued job, so the bot always answers in under a second with "Saving..." before the real confirmation arrives.

Cleaning URLs Is Half the Feature

The first thing the SaveUrl action does is canonicalize. The same video arrives as youtube.com/watch, youtu.be, a Shorts URL, or any of those with tracking junk attached (si=, utm_*, the X s= and t= params). All of them collapse to one canonical form, so saving the same video twice gets caught as a duplicate instead of cluttering the inbox. Timestamps survive the cleaning because "watch from 18:30" is information I actually want.

One small decision I like: re-saving something already watched or archived revives it back to the inbox. If I cared enough to save it twice, it's relevant again.

Fetching Content Without Scraping Anything

For YouTube, oEmbed gives me the title and channel for free, no API key. Duration comes from the Data API's videos.list if a key is present, and gets skipped when it's not. Transcripts are best-effort against the caption endpoints.

For X, the public oEmbed endpoint at publish.twitter.com returns the tweet text and author for any public tweet. No auth, no paid tier. That's the entire "X integration."

Everything else falls through to an article fetcher that grabs the title tag and meta description. Not glamorous, works fine.

Then the queue job hands whatever content it collected to the AI SDK with a schema-validated structured output request: a two-to-four sentence summary plus three to five lowercase tags, returned as strict JSON. If you haven't used structured outputs in the SDK yet, the smart assistant tutorial covers the pattern; it's the same idea here with a smaller schema.

The app runs DeepSeek by default because summaries are a cheap-model task, but the provider is configuration, not code. Two env vars switch it to Anthropic or OpenAI, and the same swap works for local models through Ollama if you want summaries that cost nothing. Since the SDK went stable, this kind of provider independence is the main reason I keep reaching for it in side projects.

The "Probably:" Fallback Fires More Than You'd Think

Here's the honest part. YouTube transcript fetching fails constantly. Captions are disabled, auto-captions aren't exposed, the endpoint shape shifts. I expected transcripts to be the normal path and the fallback to be rare. Ten days of real usage says it's closer to the other way around.

So the fallback is a first-class feature, not an error state. When there's no transcript, the model summarizes from the title and channel alone, and the summary is prefixed with "Probably:" so I know it's an educated guess rather than a digest of the actual content. Treating low confidence as something to label instead of hide turned out to be the right call. A guessed summary still answers the only question that matters at digest time: do I still care about this?

If I later want real transcripts, the escape hatch is downloading captions server-side per video. That's a v2 problem. For deciding watch-or-archive, "Probably:" is enough.

One Item a Day, Three Buttons

Every evening at 19:00 the scheduler picks exactly one item and sends it with its summary and three inline buttons: Watch, Snooze 7d, Archive.

The selection logic matters more than it looks. Due snoozes win first, oldest snooze first. Otherwise it picks from the inbox: never-surfaced items first, then whatever was surfaced longest ago. That rotation means ignoring a digest doesn't show you the same item every day forever, which is exactly the failure mode that makes reminder apps unbearable.

The buttons edit the original message in place. Tap Watch and the message updates to show the plain URL so it unfurls and I can tap through. Tap Archive and it becomes one line. No app, no tab, a two-second decision inside a chat I already have open.

And because guilt is the actual product being fought here: anything untouched for 90 days gets auto-archived by a weekly job. The clock keys on updated_at, so snoozing counts as engagement and resets it. The list can only shrink.

A /stats command replaces the dashboard I refused to build. Inbox count, watched, archived, watch rate, age of the oldest item. One message. That's the whole confession.

The Bug That Almost Shipped: hash_equals('', '')

The first live smoke test caught something the 47 passing tests didn't. With a fresh .env where the secrets weren't filled in yet, every authenticated endpoint let everyone in.

The webhook check compared the configured secret against the header Telegram sends. The ingest endpoint compared the configured token against the bearer token. Both used hash_equals(). And hash_equals('', '') returns true, because an empty string does equal an empty string. Blank config plus absent header equals open endpoint, on a public VPS.

The tests never caught it because every test sets the secrets. Real config drift is exactly the case your test suite doesn't model.

The fix is a rule worth stealing for any personal tool: fail closed when config is blank. Every auth check now short-circuits to a 403 if the configured secret is empty, before any comparison runs, with regression tests pinning it. If a required secret isn't set, the correct behavior is "nothing works," never "everything works."

What I Deliberately Didn't Build

No user accounts, no dashboard, no Chrome extension, no Facebook support, no multi-tenancy. This is a single-user tool on my own VPS, and every one of those features would have turned a weekend build into a month of speculation about users who don't exist yet.

That's also my honest recommendation if you build one: resist the SaaS reflex. The value here is that it's yours, it's small, and it costs nothing to run. SQLite plus the database queue on a box you already have is the whole bill. If strangers start asking to use it, that's a different project and a different decision, and it should be made then, with real people asking, not upfront.

FAQ

Why can't it just read my existing YouTube Watch Later list?

Because the API doesn't allow it. YouTube removed Watch Later access from the Data API years ago, and no official way back exists. Any tool claiming to sync it is scraping, which breaks routinely. Replacing the save action is the reliable path.

What happens if I don't configure an AI provider?

Links still get saved with full metadata (title, channel, duration). The bot just says no summary is configured. The AI layer is optional, not a dependency.

Why Telegram instead of WhatsApp?

Telegram's Bot API is free, instant to set up, and supports inline buttons and message editing, which the digest depends on. WhatsApp's Business API costs money and requires approval. This isn't close.

Does it handle X bookmarks?

It replaces them rather than reading them. The bookmarks API is affordable now (roughly a dollar per thousand of your own items since April 2026), but it needs a funded developer account and an OAuth flow, and it only covers X. The public oEmbed endpoint returns any public tweet's text for free, so forwarding a tweet link gets you the same summarize-and-resurface treatment with no account at all.

How does it decide which item to resurface?

Due snoozes first, then never-surfaced inbox items oldest-first, then the item that's gone longest without being shown. Ignoring the digest rotates the backlog instead of repeating one item, and anything untouched for 90 days archives itself.

Watch Rate Over Library Size

Ten days in: 12 sitting in the inbox, 7 watched, 3 archived, one snoozed. That's a 70% watch rate on the things I've actually decided about, and I'll be honest that the number flatters me. These are still the early days and the sample is ten decisions. Ask again in a month when the novelty has worn off.

The whole thing is on GitHub at hzeeshan/watch-later if you want to run your own. It's a single-user tool by design, so expect to spend ten minutes on a bot token and a cron entry rather than a signup form.

Laravel PostgreSQL Connection Pooling: Native PgBouncer Support Is Here

Hafiz — Wed, 22 Jul 2026 10:31:23 +0000

Laravel PostgreSQL connection pooling used to mean one thing: workarounds. If you've ever run Laravel against Supabase, Neon, or a self-hosted PgBouncer, you know the ritual. Set PDO::ATTR_EMULATE_PREPARES, install a community package to patch boolean bindings, keep a second connection config for migrations, and hope nobody on the team forgets which one is which.

That ritual is over. Laravel 13.17 shipped framework-level support for Postgres transaction poolers. One config flag, an optional direct block, and the framework handles everything the pooler requires. Emulated prepares, boolean binding, routing migrations around the pooler. All of it.

This post covers what the feature does, why the problem existed in the first place, the exact setup for Supabase, Neon, and self-hosted PgBouncer, and which of your old hacks you can now delete.

Why Postgres Connections Are Expensive

If you come from MySQL (like most Laravel developers), this problem probably never bit you. MySQL handles connections with lightweight threads. Postgres forks an entire OS process per connection, and each one eats roughly 5-10MB of RAM on the server. The default max_connections on most Postgres setups sits around 100.

Now do the math for a typical Laravel deployment. PHP-FPM opens a fresh database connection for every request. A moderately busy app with 50 concurrent requests is already holding 50 Postgres processes. Add a queue worker or three, a scheduler, and a second app server, and you're staring at FATAL: too many connections in your logs.

Octane makes this worse, not better. Persistent workers hold their database connection for their entire lifetime. 32 Swoole workers means 32 permanent Postgres processes, most of them idle at any given moment. There's a years-old GitHub discussion of Octane users hitting exactly this wall and hand-rolling PgBouncer setups to survive it.

The fix isn't more connections. It's a pooler.

What a Transaction Pooler Actually Does

A pooler like PgBouncer is a lightweight middleman between your app and Postgres. Your app opens hundreds of cheap connections to the pooler. The pooler multiplexes them over a small set of real Postgres connections, maybe 20.

In transaction mode (the mode that matters here), a real connection is borrowed only for the duration of a single transaction. The moment your transaction commits, that connection goes straight back into the pool for the next request. This is how Supabase's Supavisor serves thousands of clients, how Neon's pooler endpoints work, and how AWS RDS Proxy keeps Lambda functions from melting a small RDS instance.

Transaction mode has one big catch: it breaks server-side prepared statements. Your next query might execute on a different real connection, one that never saw the PREPARE. The same goes for session-level features like SET commands and LISTEN/NOTIFY. That catch is the entire reason Laravel needed framework support.

The Old Pain: What We All Had to Do Before 13.17

Before this release, running Laravel through a transaction pooler meant assembling your own solution from three parts.

First, you disabled server-side prepares by adding PDO::ATTR_EMULATE_PREPARES => true to your connection's options array. That made queries pooler-safe.

But it introduced a second bug: with emulated prepares, Laravel sends PHP booleans to Postgres as 1 and 0 instead of 'true' and 'false', and Postgres rejects them. Entire community packages exist purely to patch this. Their whole job is a custom PostgresConnection class that reformats boolean bindings. If you have one of those in your composer.json, you already know.

Third, migrations and DDL can't run through a transaction pooler at all. So you kept a second connection config pointing at the real database host and remembered to pass --database=pgsql_direct to every migrate call. Every deployment script grew a little ritual around it. Forget once and your migration hangs or fails in a way that takes twenty minutes to diagnose.

None of this was hard, exactly. It was just fragile, undocumented tribal knowledge that every team rediscovered the painful way.

What Laravel 13.17 Ships

PR #60425 (merged June 21, shipped in v13.17.0) moves all of that into the framework. Yes, the same release that gave us route metadata. 13.17 was a good week. Interesting detail: Laravel Cloud has had internal pooled-connection handling since 2025, but it was private plumbing. This PR is the first time it's a public, documented API that any Laravel app can use.

Here's the whole configuration:

'pgsql' => [
    'driver' => 'pgsql',
    'host' => env('DB_HOST'),
    'port' => env('DB_PORT', '5432'),
    'database' => env('DB_DATABASE'),
    'username' => env('DB_USERNAME'),
    'password' => env('DB_PASSWORD'),
    // ...
    'pooled' => env('DB_POOLED', false),
    'direct' => array_filter([
        'host' => env('DB_DIRECT_HOST'),
        'port' => env('DB_DIRECT_PORT'),
        'username' => env('DB_DIRECT_USERNAME'),
        'password' => env('DB_DIRECT_PASSWORD'),
        'sslmode' => env('DB_DIRECT_SSLMODE'),
    ]),
],

The main connection points at your pooler. The direct block points at the real database. With pooled => true, the framework does four things automatically:

Emulated prepares turn on for the pooled connection. Direct connections keep native prepares. You never touch PDO::ATTR_EMULATE_PREPARES yourself again.

Boolean bindings get fixed. Under emulated prepares, Postgres now receives 'true' and 'false' strings instead of integer literals. Delete the community patch package.

Schema operations route around the pooler. Migrations, schema:dump, schema load, db:wipe, db:show, and db:table all use the direct connection without you passing any flags. Your deployment script gets simpler, not more complicated. The full command list lives in the Laravel Artisan Commands reference if you want to check what else touches the schema.

php artisan db defaults to direct. When pooled mode is on and a direct endpoint exists, the interactive database CLI connects directly, which is what you want for poking at the schema. Pass --pooled if you specifically want to inspect behavior through the pooler.

And when your own application code needs the real connection (say, a LISTEN/NOTIFY listener or a long-running cursor), append the ::direct suffix:

DB::connection('pgsql::direct')->statement('LISTEN order_events');

Backward compatibility is clean. Without pooled => true, nothing changes. Existing ::read and ::write suffixes keep their meaning. Adding a direct block alone doesn't reroute anything.

Setting It Up With Real Providers

The config shape is identical everywhere. The only thing that changes is where the pooled and direct hosts come from.

Supabase

Supabase gives you two connection paths. The direct connection runs on port 5432 at your project's database host. The transaction pooler (Supavisor) runs on port 6543 at a regional pooler host. Both are on your project's Connect page.

DB_HOST=aws-0-eu-central-1.pooler.supabase.com
DB_PORT=6543
DB_POOLED=true
DB_DIRECT_HOST=db.yourproject.supabase.co
DB_DIRECT_PORT=5432

Your app traffic flows through Supavisor. Your migrations hit the database directly. No custom connection classes, no session-mode compromises.

Neon

Neon exposes the pooler through a hostname suffix: take your endpoint host and add -pooler to it. Same credentials for both.

DB_HOST=ep-cool-name-123456-pooler.eu-central-1.aws.neon.tech
DB_POOLED=true
DB_DIRECT_HOST=ep-cool-name-123456.eu-central-1.aws.neon.tech

If you're on Neon specifically for the scale-to-zero pricing, this pairing matters more than it looks. Pooled connections are what let a tiny compute instance handle bursty traffic without connection churn waking it into a bigger bill.

Self-Hosted PgBouncer

Run PgBouncer with pool_mode = transaction in pgbouncer.ini, point DB_HOST at the PgBouncer port (usually 6432), and point the direct block at Postgres itself on 5432. That's it. All the ignore_startup_parameters and prepared-statement tuning advice you'll find in old tutorials was written for the pre-13.17 world. The framework handles the client side now.

One honest note for Octane users: a pooler doesn't reduce how many connections your workers open. It makes those connections cheap. 32 workers still hold 32 client connections, but they multiplex over a fraction of the real Postgres processes, which is the resource that actually runs out.

How to Verify It's Actually Working

Don't trust the config, check the behavior. Three quick tests after enabling pooled:

First, confirm your app traffic goes through the pooler. Run a request, then check active server connections from a direct session:

SELECT count(*) FROM pg_stat_activity WHERE datname = 'your_database';

Under load, that number should stay small and stable (your pool size) while your app happily serves far more concurrent requests. If it climbs with concurrency, you're not actually connecting to the pooler endpoint.

Second, confirm schema routing. Run php artisan db:show. It should report the direct host, not the pooler host. Then run a throwaway migration on staging and watch it complete without hanging. That's the automatic routing doing its job.

Third, if you had the boolean problem before, hit a code path that writes a boolean column. On 13.17 with pooled => true it just works. No exception about invalid input syntax for type boolean, no patch package in sight.

Should You Turn This On?

If you're on Supabase, Neon, RDS Proxy, or any managed Postgres with a pooler endpoint: yes, and this feature removes the last good excuse not to. The old objection was that pooler setups in Laravel were fragile hand-rolled things. That objection died in 13.17.

If you're self-hosting Postgres for a small app with steady traffic, you don't need a pooler yet. A single server with PHP-FPM and modest concurrency lives comfortably inside default connection limits. Add PgBouncer when you see connection pressure, not before. Database indexing will buy you more performance per hour invested until then.

The setup where I'd call it non-negotiable: Octane on Postgres, or anything serverless. Persistent workers and scale-to-zero databases are both connection-hungry patterns, and transaction pooling is the standard answer in every ecosystem, ours included.

One thing to check before enabling it on an existing app: emulated prepares change how query plans are cached server-side, and code that relied on session state between queries (temporary tables, SET commands, advisory locks held across requests) will behave differently through a pooler. That's pooler physics, not a Laravel limitation. Audit for those patterns first. Multi-tenant apps that switch databases per tenant should test carefully too, since tenant connection strategies often assume dedicated connections.

FAQ

Which Laravel version do I need for native pooler support?

Laravel 13.17 or newer. The feature landed via PR #60425 and shipped in v13.17.0 in late June 2026. If you're still on Laravel 12, the upgrade to 13 is worth it for this alone if you run Postgres in production.

Does this work with MySQL or MariaDB?

No. The pooled option is specific to the PostgreSQL driver, because the problem it solves (process-per-connection cost plus prepared statements breaking under transaction pooling) is specific to Postgres. MySQL's threaded connection model doesn't need this.

Do I still need packages that patch PgBouncer boolean bindings?

Not on 13.17+. Correct boolean binding under emulated prepares is now framework behavior. Remove the package, remove any custom PostgresConnection class you copied from a gist, and remove PDO::ATTR_EMULATE_PREPARES from your connection options. The framework sets it for pooled connections automatically.

What happens to migrations if I don't configure a direct block?

Then there's nothing to route to, and schema operations go through your main connection like before. If that connection is a transaction pooler, DDL can fail or hang, exactly as it always did. The direct block is what makes the automatic routing possible, so treat it as required whenever pooled is true.

Does pooling change anything for read/write connection splits?

No. Explicit ::read and ::write suffixes and the --read/--write CLI flags keep working exactly as before and aren't rerouted to the direct connection. The ::direct suffix is a separate, additional routing option.

Wrapping Up

This is one of those features where the code change in your app is five lines of config and the actual win is everything you get to delete: the options array hack, the patch package, the second migration config, the deploy-script flags, and the tribal knowledge explaining why they all exist. Laravel apps on Supabase and Neon just got noticeably simpler to run, and Octane on Postgres finally has a first-party answer to connection exhaustion.

Filament Billing: The Missing Stripe Admin Layer for Your Panel

Hafiz — Mon, 20 Jul 2026 06:02:55 +0000

You wired up Laravel Cashier, connected Stripe, and your app takes payments. Subscriptions get created, webhooks fire, the subscriptions table fills up. Everything works.

Then a customer emails asking to cancel. Or you want to know what your MRR actually is this month. Or someone's payment failed and you need to see who's past due.

Where do you go? Not your admin panel. Cashier doesn't put anything there. You open the Stripe dashboard, or you write a tinker one-liner, or you build a one-off resource every single time. The billing runs fine, but managing it lives outside the tool you built everything else in.

That gap is the whole reason I built Filament Billing. It's a commercial plugin that adds the operator side of billing to your Filament panel: plans, subscriptions, and an MRR widget, all reading from the Cashier tables you already have.

What Cashier gives you, and what it doesn't

Cashier is really good at what it does. It handles the Stripe API calls, the subscription lifecycle, the webhook parsing, the proration math. If you've set up billing with it before (and if you haven't, my Stripe integration guide walks through the whole thing), you know it takes care of the hard parts.

But Cashier is a library, not an interface. It writes stripe_status to your database when a webhook arrives. It does not give you a screen to see that status. It cancels a subscription when you call ->cancel() in code. It does not give your support person a button to do it.

So most teams end up in one of three places. They pop open the Stripe dashboard for everything, which means context-switching out of their own app and giving more people Stripe access than they'd like. They write throwaway tinker commands, which works until you need it at 11pm and can't remember the syntax. Or they build custom Filament resources by hand, which is fine the first time and annoying the fifth.

I've done all three. The third one is what this plugin is, except built once, properly, instead of half-built on every new project.

What Filament Billing actually adds

Three things, all operator-facing.

A Plans resource where you define your billing plans inside the panel. Name, price, currency, the policy behind it. This is your reference layer for what you sell.

A Subscriptions resource that reads your Cashier subscription tables and shows them as a proper Filament list. Each row has the actions you'd expect: cancel at period end, cancel now, resume, swap. No tinker, no Stripe dashboard. Your support person can handle a cancellation without touching code or getting a Stripe login.

An MRR widget for your dashboard. It shows monthly recurring revenue, active subscriber count, and how many people are in trial. It derives the number from the plans it sums, so the currency matches your data instead of a hardcoded symbol. If you've read my admin dashboards guide, this is the metrics-at-a-glance idea applied to billing.

There's also Stripe webhook status sync that keeps subscription statuses current as Stripe events arrive. That part builds on Cashier's own webhook handling, so it works as long as you've got Stripe webhooks wired to your app the normal way.

Who this is for, and who it isn't

I'd rather you know before you buy than ask for a refund after, so here's the honest scope.

This is an operator-side tool. It's for you and your team to manage billing from the admin panel. It is not a customer-facing checkout. Your customers still create subscriptions the way they already do through Cashier. Filament Billing gives you the layer to manage what those flows produce, not a replacement for them.

It's Stripe only, through Cashier. If you're on Paddle, this isn't for you yet.

You define your plans in the panel. It doesn't auto-sync from Stripe on install. You enter what you sell once, and manage from there. (Pulling plans straight from the Stripe API is the feature I'm most likely to add next, but I'd rather ship the honest version now than promise sync that isn't there.)

And it needs Filament v5 and Laravel 11 or 12, with Cashier for Stripe. Filament v5 shipped mainly to support Livewire v4, with no functional changes from v4, so if you're on a recent v4 app the upgrade is quick. If you want to know exactly what changed, I covered that in my Filament v5 breakdown.

If you're building a Laravel SaaS on Filament and you've already got Cashier taking payments, you're the exact person I built this for. If you're still deciding between billing providers, my Cashier Stripe vs Paddle cost comparison is worth a read first, because this plugin commits you to the Stripe side.

Why I shipped it narrow

I've made the mistake before of building a big, clever thing nobody used. So this one is deliberately small. Operator-side only. Stripe only. No customer checkout, no dunning flows, no churn analytics, no Paddle. Just the three pieces that solve the actual daily pain: seeing subscriptions, acting on them, and knowing your MRR.

That narrowness is a feature. It means the plugin does what it says, installs cleanly, and doesn't drag half-finished functionality into your app. If it turns out people want plan-sync or Paddle or a customer portal, those come later, driven by what buyers actually ask for, not by what I imagined in advance. This is the same ship-narrow-to-validate approach I wrote about in my Building a SaaS with Laravel and Filament guide, where I built this billing layer by hand the first time. I've since packaged that admin side into this plugin so you don't have to rebuild it.

Pricing and how to get it

Two one-time tiers: €69 for a single project, €149 for unlimited projects. No subscription, no recurring fee for the plugin itself. You buy it, you get the private Composer repository access, you install it with your license key. You can grab it on Anystack here.

Installation is the standard Anystack flow: configure the repository, add your license credentials, composer require hafizdev/filament-billing, then run the install command. It reads your existing Cashier setup and adds the resources and widget to your panel.

FAQ

Does this replace Laravel Cashier?

No. It sits on top of Cashier and reads its tables. You still need Cashier installed and configured for Stripe. Think of this as the admin interface Cashier never shipped.

Can my customers use it to subscribe or manage their own plans?

Not in this version. It's operator-side only. Your customers create subscriptions through your existing Cashier flows; this is for you and your team to manage them from the panel.

Does it work with Paddle?

No, Stripe only for now. Paddle support depends on demand, so if that's a blocker for you, let me know.

Do I need to be on Filament v5?

Yes, v5 with Laravel 11 or 12. Since v5 exists mainly for Livewire v4 support with no functional changes from v4, upgrading a recent v4 app is quick.

Will it pull my plans from Stripe automatically?

Not yet. You define your plans in the panel once. Automatic sync from the Stripe API is the most likely next addition.

Get it or ask me

If you're running Cashier on a Filament panel and you're tired of opening Stripe to cancel a subscription, this is the layer that fixes it. It's live now on Anystack.

Building something with Filament and Stripe and want to talk through whether this fits, or what's missing for your case? Get in touch. I read every message, and buyer questions are what shape where this goes next.

DEV Community: Hafiz

Sitemap Timing Test

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

What you're actually exposing

Layer one: authentication, and why local is not exempt

Layer two: authorization, per tool, inside handle

The annotation trap

Layer three: rate limiting an endpoint a robot can loop

Testing that the locks hold

A quick word on tool descriptions as an attack surface

My take

FAQ

Does a local MCP server need authentication?

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

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

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

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

Wrapping up

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

Why I moved at all

The unfair advantage: Cloudflare was already in front

Preparing the new server while the old one serves traffic

Rehearse through the real edge with a probe subdomain

The cutover: 1 minute 55 seconds

The four things that almost broke

The maintenance flag stowed away in the rsync

The SSR service that existed nowhere in the app tree

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

The midnight log rotation trap

What I'd tell you to do differently

FAQ

Do I need to lower DNS TTLs before migrating?

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

Why not just use Laravel Forge or Laravel Cloud?

How long should the old server stay available?

What breaks most often after a server move?

The checklist is the takeaway

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

What Head actually is, in ninety seconds

Group one: artesaos/seotools apps

Group two: ralphjsmit/laravel-seo apps

Group three: the hand-rolled partial

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

The Inertia part, which is quietly the biggest upgrade

My take

FAQ

What are Laravel Head's minimum requirements?

Does Laravel Head replace artesaos/seotools completely?

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

Does Laravel Head work with route caching?

Does Laravel Head store SEO data in the database?

Wrapping up

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

The performance numbers, and what they measure

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

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

The fifteen-minute audit after updating

The quality-of-life additions worth knowing

Should you update today?

FAQ

Do I get the performance improvements without changing any code?

Is the CSV formula-injection protection enabled by default?

Which versions contain the MFA fix?

Does this release affect Filament v3?

Will the update break my custom theme or plugin?

Wrapping up

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

The stack, honestly

What 13.20 actually replaces

What it doesn't touch: Spatie Media Library

When you still drop to Intervention directly

The Cloudflare driver that never shipped

Three things the docs don't make obvious

The decision, in one table

My take

FAQ

Does Laravel 13.20 mean I can remove Intervention Image?

Should I replace Spatie Media Library with the new API?

Can I pass an image instance to a queued job?

Is there a Cloudflare driver?

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