Forem: Hafiz

Livewire 4 Single-File Components: Build a Live Search in One File

Hafiz — Wed, 08 Apr 2026 05:29:47 +0000

If you ran php artisan make:livewire after upgrading to Livewire v4 and noticed the file landed in resources/views/components/ instead of app/Livewire/, that wasn't a mistake. That's the new default. Livewire 4 shipped single-file components as the standard format in January 2026, and most Livewire developers are still building with the old two-file pattern out of habit.

This tutorial covers how single-file components actually work, when to use them versus the multi-file format, what's changed about scoped CSS and JavaScript in v4, and how to build something real with it: a live search component with filtering, scoped styles, and an Island for expensive data. No shortcuts , just the format you'll be using from now on.

The Problem With the Old Two-File Pattern

In Livewire v3, creating a component meant two files minimum. The PHP class lived in app/Livewire/SearchPosts.php, and the Blade view lived in resources/views/livewire/search-posts.blade.php. If you wanted component-specific JavaScript, you'd reach for @script or @push('scripts'). CSS was either inline or pushed to a stack.

It worked. But every time you built a component, you mentally held two files together. When you searched for a component in your editor, you got two results. When you read a diff, the logic and the template were on separate lines of the PR. The connection between them existed only in your head and in render().

Livewire 4 puts everything in one file. PHP class, Blade template, scoped CSS, component JavaScript. One file, one search result, one diff chunk. That's the entire point.

What a Single-File Component Looks Like

Create one with:

php artisan make:livewire search-posts

This generates a file at resources/views/components/⚡search-posts.blade.php. The structure is:

<?php

use Livewire\Component;
use Livewire\Attributes\Computed;
use App\Models\Post;

new class extends Component {

    public string $query = '';

    #[Computed]
    public function results()
    {
        if (strlen($this->query) < 2) {
            return collect();
        }

        return Post::where('title', 'like', "%{$this->query}%")
            ->limit(10)
            ->get();
    }

};

?>

> **[View the interactive component on hafiz.dev](https://hafiz.dev/blog/livewire-4-single-file-components-tutorial)**

Both the <style> and <script> blocks are served as native .css and .js files with browser caching. Livewire handles the bundling. You don't touch Vite config or webpack.mix.js to make this work.

One thing to flag: the bare <script> tag works in single-file and multi-file components. If you're still on class-based components where the Blade view is separate from the PHP class, you need @script instead. That's the v3 pattern and it still works, but it's no longer the default.

Adding an Island for Expensive Data

Our search component runs a database query on every keystroke (debounced to 300ms). That's fine for a simple search. But what if the component also needs to show some stats , total posts, most searched terms , that are expensive to compute and don't change with every search?

That's where Islands come in. They let you mark a region of your component to update independently from the rest:

<?php

use Livewire\Component;
use Livewire\Attributes\Computed;
use App\Models\Post;

new class extends Component {

    public string $query = '';

    #[Computed]
    public function results()
    {
        if (strlen($this->query) < 2) {
            return collect();
        }

        return Post::where('title', 'like', "%{$this->query}%")
            ->limit(10)
            ->get();
    }

    #[Computed]
    public function stats()
    {
        return [
            'total' => Post::count(),
            'published' => Post::where('status', 'published')->count(),
        ];
    }

};

?>

<div>
    <input
        wire:model.live.debounce.300ms="query"
        type="search"
        placeholder="Search posts..."
        class="search-input"
    />

    @if($this->results->isNotEmpty())
        <ul class="results-list">
            @foreach($this->results as $post)
                <li>
                    <a href="{{ route('posts.show', $post) }}">
                        {{ $post->title }}
                    </a>
                </li>
            @endforeach
        </ul>
    @endif

    @island(name: 'stats', lazy: true)
        <div class="stats">
            <span>{{ $this->stats['total'] }} total posts</span>
            <span>{{ $this->stats['published'] }} published</span>
        </div>
    @endisland
</div>

When the user types, only the search results re-render. The stats island loads lazily and stays cached until you explicitly tell it to refresh. The database queries for stats() don't run on every keystroke. That's the key performance win , you're isolating the expensive parts of your component rather than paying for them on every interaction.

Rendering the Component

Include it in any Blade template the same way as any other Livewire component:

<livewire:search-posts />

The component name is derived from the filename. The ⚡ prefix and directory structure are stripped automatically. So ⚡search-posts.blade.php becomes search-posts. You can switch between single-file and multi-file formats without changing this reference.

For full-page components (search results as a standalone page, for example), use the pages:: namespace:

php artisan make:livewire pages::search

And register the route with Route::livewire():

Route::livewire('/search', 'pages::search');

When to Use Single-File vs Multi-File

Single-file is the right default for most components. It works well up to a few hundred lines, covers the vast majority of real-world use cases, and keeps everything co-located.

Multi-file makes sense when a component gets complex enough that one file becomes hard to navigate, or when you want a dedicated test file alongside the component. Create one with:

php artisan make:livewire post.editor --mfc

This generates a directory:

resources/views/components/post/⚡editor/
├── editor.php
├── editor.blade.php
├── editor.js
└── editor.css

The directory structure doesn't change how you reference the component. <livewire:post.editor /> still works. And you can convert between formats at any time:

# Single-file → Multi-file
php artisan livewire:convert search-posts

# Multi-file → Single-file
php artisan livewire:convert post.editor --single

If a multi-file component has a test file, Livewire will warn you before converting to single-file since test files can't be preserved in that format.

Migrating a v3 Component

If you have existing v3 class-based components, nothing breaks. They keep working. But if you want to move a specific component to the new format, here's the before and after.

Before (v3 class-based):

app/Livewire/SearchPosts.php:

<?php

namespace App\Livewire;

use Livewire\Component;
use App\Models\Post;

class SearchPosts extends Component
{
    public string $query = '';

    public function render()
    {
        return view('livewire.search-posts', [
            'results' => Post::where('title', 'like', "%{$this->query}%")
                ->limit(10)
                ->get(),
        ]);
    }
}

resources/views/livewire/search-posts.blade.php:

<div>
    <input wire:model.live="query" type="search" />

    @foreach($results as $post)
        <li>{{ $post->title }}</li>
    @endforeach
</div>

After (v4 single-file):

resources/views/components/⚡search-posts.blade.php:

<?php

use Livewire\Component;
use Livewire\Attributes\Computed;
use App\Models\Post;

new class extends Component {

    public string $query = '';

    #[Computed]
    public function results()
    {
        return Post::where('title', 'like', "%{$this->query}%")
            ->limit(10)
            ->get();
    }

};

?>

<div>
    <input wire:model.live="query" type="search" />

    @foreach($this->results as $post)
        <li>{{ $post->title }}</li>
    @endforeach
</div>

The main differences: no separate class file, no render() method, results accessed via $this->results with the #[Computed] attribute instead of being passed as view data, and the anonymous class definition instead of a named class in the App\Livewire namespace.

One v4 change worth knowing if you're migrating: wire:model no longer listens to events that bubble up from child elements. In v3, wire:model on a container element would catch input events from nested inputs inside it. That's gone in v4 , wire:model only responds to events directly on the element it's attached to. If you need the old behavior, add the .deep modifier: wire:model.deep. This catches most developers off guard the first time they hit it.

FAQ

Do I have to rewrite my existing v3 components?

No. Class-based components still work exactly as before. Single-file is the new default for components you create going forward, but nothing forces you to migrate old ones.

Can I use Filament with Livewire 4 single-file components?

Yes. Filament v5 runs on Livewire v4. Your Filament resources and custom pages are separate from your own Livewire components , they coexist without conflict. If you're building a Filament admin panel, you don't need to change anything about how Filament works.

Is the #[Computed] attribute required for properties accessed in the template?

No. You can still pass data to the template through a render() method if you want. #[Computed] is a convenience attribute that caches the result for the lifetime of the request and makes the property accessible as $this->results directly in the template. It's the cleaner pattern for v4.

Does wire:model.live work the same as in v3?

The debouncing behavior is the same, but the event bubbling behavior changed. In v4, wire:model only listens to events that originate directly on the element , not events that bubble up from children. For forms with standard inputs (text, select, textarea), you'll notice no difference. The change only affects non-standard uses like wire:model on a container element.

Can I still use Alpine.js inside single-file components?

Yes, fully. Alpine directives work in the template exactly as before. The <script> block gives you access to $wire for crossing the PHP-JavaScript boundary when you need it. Alpine handles client-side state, $wire handles server state.

The single-file format doesn't unlock anything that was impossible in v3 , it just removes the overhead of managing two files for every component. For small to medium components that's a genuine improvement, and for anything with scoped CSS or component-specific JavaScript it's significantly cleaner. If you're building a SaaS with Livewire and Filament, starting new components in the v4 format now means less context-switching and fewer files to track as the app grows.

Check the official Livewire v4 docs for the full component reference, including namespaces, slots, and attribute forwarding.

If you're planning a build and unsure whether Livewire or Inertia is the right call for your specific project, the Livewire 4 vs Inertia.js 3 comparison covers the decision in detail.

If you're building something with Livewire and want another dev to look it over, reach out.

Scotty vs Laravel Envoy: Spatie's New Deploy Tool Is Worth the Switch

Hafiz — Mon, 06 Apr 2026 05:38:54 +0000

Spatie released Scotty on March 30th. It's a new SSH task runner that does what Laravel Envoy does: run deploy scripts on remote servers. But it uses plain bash syntax instead of Blade templates, and gives you significantly better terminal output while tasks run.

Freek Van der Herten wrote about it on his blog: "Even though services like Laravel Cloud make it possible to never think about servers again, I still prefer deploying to my own servers for some projects." That's exactly the scenario Scotty targets. If you're on a DigitalOcean droplet, a Hetzner box, or anything you manage yourself, and you're either still SSH-ing in manually or running Envoy, Scotty is worth a look.

Let's break down what it actually does differently, whether it's a meaningful upgrade, and how to migrate or set it up from scratch.

The Problem With Laravel Envoy

Envoy works. I'm not going to pretend it's broken. But there are two friction points that come up every time you actually use it.

The first is the Blade file format. Your deploy script is an Envoy.blade.php file full of @task, @servers, @story directives and {{ $variable }} syntax. It looks like PHP, but it's not quite PHP. Your editor treats it differently depending on how your Blade support is configured. Shell linting won't touch it. Autocompletion for bash commands doesn't work inside the Blade blocks. It's a hybrid format that's slightly awkward for what is fundamentally a shell scripting task.

The second is the output. When Envoy runs, you see the commands executing one after another in a plain stream. There's no step counter, no elapsed time per task, no summary at the end. When something takes 40 seconds you're just watching text scroll by hoping nothing's wrong.

Scotty addresses both directly.

What Scotty Does Differently

Plain bash with annotation comments. Your script is a Scotty.sh file with a #!/usr/bin/env scotty shebang. Tasks are regular bash functions. Server targets and macros are annotation comments. It looks like this:

#!/usr/bin/env scotty

# @servers remote=deployer@your-server.com
# @macro deploy pullCode runComposer runMigrations clearCaches restartWorkers

APP_DIR="/var/www/my-app"
BRANCH="${BRANCH:-main}"

# @task on:remote confirm="Deploy to production?"
pullCode() {
    cd $APP_DIR
    git pull origin $BRANCH
}

# @task on:remote
runComposer() {
    cd $APP_DIR
    composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev
}

# @task on:remote
runMigrations() {
    cd $APP_DIR
    php artisan migrate --force
}

# @task on:remote
clearCaches() {
    cd $APP_DIR
    php artisan config:cache
    php artisan route:cache
    php artisan view:cache
    php artisan event:cache
}

# @task on:remote
restartWorkers() {
    cd $APP_DIR
    php artisan horizon:terminate
}

That's a complete deploy script. Notice that BRANCH="${BRANCH:-main}" is just bash. It defaults to main and accepts an override from the command line. No Blade interpolation needed. Your editor highlights it correctly. shellcheck can lint it. Bash autocomplete works inside the functions.

Live output with a summary table. While tasks run, Scotty shows each one with its name, a step counter, elapsed time, and the current command executing. When everything finishes, you get a summary table showing how long each step took. It's a small thing but it makes a real difference when a deploy takes two minutes and you need to know if the three-second Composer install is suspicious.

Pause and resume. If you need to interrupt a deploy mid-flight, press p and Scotty waits for the current task to finish, then pauses. Hit Enter to resume. This matters more than it sounds when you're deploying a hot fix at 11pm and something looks off.

The scotty doctor command. Run scotty doctor before your first deploy and it validates your Scotty.sh file, tests SSH connectivity to each server, and checks that PHP, Composer, and Git are installed on the remote machine. A pre-flight check that catches most setup issues before a deploy even starts.

--pretend mode. Before running a deploy on a new server for the first time, add the --pretend flag:

scotty run deploy --pretend

Scotty prints every SSH command it would execute without actually connecting to anything. scotty doctor checks your setup. --pretend checks your script logic. Run both before you touch production for the first time.

Installing Scotty

Install it as a global Composer package:

composer global require spatie/scotty

Make sure Composer's global bin directory is in your $PATH. If you're not sure where it is:

composer global config bin-dir --absolute

Once installed, verify it works:

scotty list

To create a new Scotty file in your project, run:

scotty init

It asks for your server SSH connection string and generates a starter Scotty.sh file. Or just create the file manually. The format is simple enough that you don't really need a generator.

Migrating From Envoy

If you already have an Envoy.blade.php, you don't have to rewrite it immediately. Scotty reads Envoy files out of the box. Just run scotty run deploy against your existing Envoy file and it works.

When you're ready to migrate to the native format, the mental model is clear:

Envoy	Scotty.sh
`@servers(['web' => 'user@host'])`	`# @servers remote=user@host`
`@story('deploy') ... @endstory`	`# @macro deploy task1 task2`
`@task('pullCode', ['on' => 'web'])`	`# @task on:remote` followed by `pullCode() { }`
`{{ $branch }}`	`$BRANCH` (plain bash variable)
`@setup $branch = 'main'; @endsetup`	`BRANCH="${BRANCH:-main}"` at the top of the file

The actual shell commands inside tasks don't change at all. You're just rewriting the wrappers.

Zero-Downtime Deployments

This is where Scotty shines for production apps. The Scotty docs include a complete zero-downtime deploy script, and it's the same pattern Spatie uses for all their own applications.

The idea: instead of updating files in place (which means there's always a window where your code is half-updated), you clone each release into a new timestamped directory and flip a symlink when everything's ready. Here's what the directory structure looks like on the server:

/var/www/my-app/
├── current -> /var/www/my-app/releases/20260406-140000
├── persistent/
│   └── storage/
├── releases/
│   ├── 20260406-130000/
│   └── 20260406-140000/
└── .env

Your Nginx document root points to /var/www/my-app/current/public. The current symlink gets updated atomically at the end of a successful deploy. If Composer fails or a migration breaks, current still points to the last working release and your users see nothing wrong.

Here's the complete zero-downtime script:

#!/usr/bin/env scotty

# @servers local=127.0.0.1 remote=deployer@your-server.com
# @macro deploy startDeployment cloneRepository runComposer buildAssets updateSymlinks migrateDatabase blessNewRelease cleanOldReleases

BASE_DIR="/var/www/my-app"
RELEASES_DIR="$BASE_DIR/releases"
PERSISTENT_DIR="$BASE_DIR/persistent"
CURRENT_DIR="$BASE_DIR/current"
NEW_RELEASE_NAME=$(date +%Y%m%d-%H%M%S)
NEW_RELEASE_DIR="$RELEASES_DIR/$NEW_RELEASE_NAME"
REPOSITORY="your-org/your-repo"
BRANCH="${BRANCH:-main}"

# @task on:local
startDeployment() {
    git checkout $BRANCH
    git pull origin $BRANCH
}

# @task on:remote
cloneRepository() {
    [ -d $RELEASES_DIR ] || mkdir -p $RELEASES_DIR
    [ -d $PERSISTENT_DIR ] || mkdir -p $PERSISTENT_DIR
    [ -d $PERSISTENT_DIR/storage ] || mkdir -p $PERSISTENT_DIR/storage
    cd $RELEASES_DIR
    git clone --depth 1 --branch $BRANCH git@github.com:$REPOSITORY $NEW_RELEASE_NAME
}

# @task on:remote
runComposer() {
    cd $NEW_RELEASE_DIR
    ln -nfs $BASE_DIR/.env .env
    composer install --prefer-dist --no-dev -o
}

# @task on:remote
buildAssets() {
    cd $NEW_RELEASE_DIR
    npm ci
    npm run build
    rm -rf node_modules
}

# @task on:remote
updateSymlinks() {
    rm -rf $NEW_RELEASE_DIR/storage
    cd $NEW_RELEASE_DIR
    ln -nfs $PERSISTENT_DIR/storage storage
}

# @task on:remote
migrateDatabase() {
    cd $NEW_RELEASE_DIR
    php artisan migrate --force
}

# @task on:remote
blessNewRelease() {
    ln -nfs $NEW_RELEASE_DIR $CURRENT_DIR
    cd $NEW_RELEASE_DIR
    php artisan config:cache
    php artisan route:cache
    php artisan view:cache
    php artisan event:cache
    php artisan cache:clear
    php artisan horizon:terminate
    sudo service php8.4-fpm restart
}

# @task on:remote
cleanOldReleases() {
    cd $RELEASES_DIR
    ls -dt $RELEASES_DIR/* | tail -n +4 | xargs rm -rf
}

Run with:

scotty run deploy

Or deploy a specific branch:

scotty run deploy --branch=develop

A few things worth noting about this script. The startDeployment task runs locally: it checks out and pulls the branch on your machine first, so you catch any git conflicts before touching the server. The blessNewRelease task is where the symlink actually flips, so everything before that step is safe to fail. And cleanOldReleases keeps the three most recent releases on disk in case you ever need to inspect one.

If you're running queue workers with Horizon, php artisan horizon:terminate tells Supervisor to restart it with the new code once the current jobs finish. If you have a Laravel queue setup, this is the step that picks up your latest job definitions.

So Is It Worth Switching?

If you're starting a new project: yes, use Scotty from the beginning. The bash format is strictly better than Blade for shell scripting, and there's no migration cost.

If you're on Envoy and it's working: the migration is low-effort since Scotty reads your existing file as-is. The question is whether the output improvements and scotty doctor are worth 20 minutes of your time. For most projects, they are.

If you're on Laravel Forge's built-in deployment: Scotty isn't for you. Forge handles this well and gives you a UI for it. Scotty is for developers who prefer terminal-native control and version-controlled deploy scripts that live inside the repo.

If you're on Laravel Cloud: also not for you. The whole point of Cloud is that you don't manage servers. Scotty is specifically for self-hosted apps where you control the environment, whether that's a plain VPS or a Dockerized Laravel setup.

The honest verdict: Scotty is a clean, well-considered tool. It doesn't reinvent deployment, it just makes the script format sane and the output readable. For anyone self-hosting Laravel apps and already using Envoy, it's the obvious upgrade. For anyone who's never set up deploy automation at all, the docs give you a complete production-ready script to start from.

FAQ

Does Scotty work with multiple servers?

Yes. You can define multiple servers in the # @servers line and specify on:web, on:workers, etc. in individual tasks. You can also run tasks on multiple servers in parallel by adding the parallel option.

What's the difference between a task and a macro?

A task is a single function that runs shell commands on a target, either local or remote. A macro is a named sequence of tasks. It's what you actually run with scotty run deploy. Think of macros as your deploy pipeline definition.

Can I run Scotty in CI/CD?

Yes. Since it's a global Composer package, you install it in your CI environment the same way you would locally. It works anywhere you have SSH access to your server.

What happens if a task fails mid-deploy?

Scotty stops immediately at the failing task and shows you the error output. If you're using the zero-downtime script, the current symlink hasn't been updated yet, so your live application is untouched.

Do I need to commit the Scotty.sh file to my repo?

Yes, that's the recommended approach. The script lives in version control alongside your code, so your whole team has access to the same deploy process and changes to it go through normal code review.

Scotty's documentation is at spatie.be/docs/scotty and the source is on GitHub. If you're building out your server setup and want to harden it before adding deploy automation, the VPS hardening guide covers SSH keys, Cloudflare, and Tailscale on a fresh DigitalOcean droplet.

If automated deployments aren't on your radar yet because you're still in the build phase, reach out. Getting the deploy pipeline right early saves a lot of pain later.

Livewire 4 vs Inertia.js 3: Which Laravel Frontend Stack Should You Use in 2026?

Hafiz — Fri, 03 Apr 2026 05:47:17 +0000

If you asked a room of Laravel developers "Livewire or Inertia?" two years ago, the answer split cleanly down one fault line: do you want to write JavaScript? Livewire for PHP purists. Inertia for anyone with Vue or React muscle memory.

That framing still holds as a starting point. But it doesn't tell the whole story anymore. In January 2026, Livewire shipped version 4. In March 2026, Inertia.js shipped version 3. Both are major releases, and both of them solved problems that used to tip the scale one way or the other. The comparison has shifted.

So let's answer the question properly, with both tools at their current state.

What Livewire 4 Actually Changed

Livewire 4 shipped in January 2026 with substantially more than a few incremental improvements. The most visible change is how you write components. Instead of two files (a PHP class and a Blade view), you now put everything in a single file with a ⚡ prefix:

<?php
// resources/views/components/⚡counter.blade.php

new class extends Livewire\Component {
    public int $count = 0;

    public function increment(): void
    {
        $this->count++;
    }
}
?>

<div>
    <button wire:click="increment">+</button>
    <span>{{ $count }}</span>
</div>

This is now the default when you run php artisan make:livewire. Your existing class-based components still work. The new format is opt-in, and you can convert between formats anytime with php artisan livewire:convert.

More interesting is the Islands feature. It lets you define isolated regions inside a component that update independently from the rest of the page, without creating separate child components:

@island(name: 'stats', lazy: true)
    <div>{{ $this->expensiveStats }}</div>
@endisland

This matters a lot if you've ever hit a wall with Livewire's re-render behavior on complex dashboards. Islands let you pin expensive sections to their own update cycle, which means better performance without restructuring your entire component tree.

Two other v4 changes worth knowing before you upgrade. Requests now run in parallel, so wire:model.live on multiple fields no longer blocks each other. And wire:model changed its event bubbling behavior: it now only listens to events originating directly from the element itself, not from child elements. That last one is a silent breaking change for anyone using wire:model on container elements like modals. It won't throw an error. It'll just stop working.

What Inertia.js 3 Actually Changed

Inertia.js 3 shipped stable in late March 2026 after a beta period. The headline change is architectural: Axios is gone. Inertia now ships its own built-in XHR client, removing roughly 15KB gzipped from your bundle by default. If you rely on Axios interceptors, you can still plug Axios back in as an optional adapter.

The setup story is also dramatically simpler. In v2, every project required a resolve callback, a setup callback, and a separate SSR entry point. In v3, you add the new Vite plugin and call createInertiaApp() with no arguments:

// resources/js/app.js
import { createInertiaApp } from '@inertiajs/vue3'
createInertiaApp()

That's it. The plugin resolves pages from your ./Pages directory, handles lazy-loading and code splitting, and wires up SSR automatically during npm run dev. No separate Node process. No build step just to preview server-side rendering. This was a real friction point in v2, and it's gone.

Two new features deserve mention. useHttp is a new hook for making plain HTTP requests (to a search endpoint or autocomplete API, for example) without triggering a page navigation. It mirrors the API of useForm, so there's no new pattern to learn. And optimistic updates are now first-class. You can apply data changes instantly before the server responds, with automatic rollback on failure:

router.optimistic((props) => ({
    post: { ...props.post, likes: props.post.likes + 1 },
})).post(`/posts/${post.id}/like`)

The upgrade from v2 has a handful of breaking changes worth reading before you update. I covered those in detail in the Inertia.js v3 upgrade guide.

The Fundamental Difference Is Still the Same

Here's the thing: all of the above are improvements within each tool. They didn't change what each tool is fundamentally for.

Livewire is still a server-side component framework. When a user clicks a button or types in an input, a network request goes to your Laravel server, the component re-renders in PHP, and the diff gets applied to the DOM. The browser never runs your component logic. JavaScript is minimal and optional.

Inertia is still a protocol layer. Your Laravel controllers return JavaScript page components instead of Blade views. The frontend is fully Vue, React, or Svelte, with access to the entire npm ecosystem. The backend handles routing and data, but the rendering happens in JavaScript.

Neither is a replacement for the other. They're built on different philosophies, and v4 and v3 didn't change that.

The Real Decision in 2026

Here's a decision flowchart, then some concrete scenarios:

Pick Livewire 4 if you're building an admin panel, SaaS dashboard, or anything where the UI is form-heavy and data-driven. Livewire is faster to ship for this kind of work because you're not managing a separate frontend build or serializing everything through props. If Filament is in the stack (and for a lot of Laravel SaaS projects, it should be). Filament v5 already runs on Livewire v4, so the ecosystem stays consistent. You also get strong SEO defaults since content renders server-side first.

The Islands feature in v4 specifically removes one of Livewire's older weaknesses: the performance ceiling you'd hit with complex dashboards. That's not a complete answer to "can Livewire handle this complex UI?" but it moves the ceiling noticeably higher.

If your team is primarily PHP developers, Livewire also keeps context-switching minimal. You stay in Laravel and Blade. No shift to TypeScript types or JSX syntax mid-afternoon.

Pick Inertia.js 3 if your team is already productive with Vue or React. Full stop. If the developers on your project think in components, reach for useState, or have strong TypeScript instincts, giving them Inertia is a productivity multiplier. Don't make React developers write Blade components.

You should also pick Inertia when your UI needs the npm ecosystem. Complex drag-and-drop, advanced charting libraries, animation tools like Framer Motion, component libraries like shadcn. These integrate naturally into an Inertia project. Livewire can interface with Alpine.js for a lot of this, but there's a point where you're fighting the grain of the tool.

The type safety story is also better with Inertia. Tools like Laravel Wayfinder give you end-to-end TypeScript coverage from your Laravel routes down to your Vue or React components, which matters as a codebase grows. If you want to see what that looks like in practice with Vue, the Laravel + Vue 3 Composition API post is a good reference.

The gray area. Most SaaS products fit either tool. If you're starting fresh as a solo developer or small team, and no one has a strong JS framework preference, I'd default to Livewire. You'll ship faster in the early stages, Filament handles your admin needs, and you can always reach for Alpine.js for the handful of things that need client-side state.

The mistake I see most often: picking Inertia because it feels more "modern" without actually needing the React ecosystem. That just adds complexity for no gain. The flip side is picking Livewire for a public-facing app with real-time features when your entire team thinks in React. That's the wrong tool for the wrong people.

My Take

I use both depending on the project. Livewire and Filament for anything admin-heavy or SaaS-internal. Inertia and Vue for public-facing products where the team has frontend experience and the UI benefits from the full Vue ecosystem.

What I don't do is agonize over the choice. Both are well-maintained, both have strong ecosystems, and both just shipped major versions that made them better.

The real risk isn't picking the "wrong" one. It's spending three weeks researching and not shipping anything.

FAQ

Can I use Livewire and Inertia in the same Laravel project?

Technically yes, but it's not a great idea unless you have a very clear architectural separation. The more common pattern is Livewire for internal admin sections and a different approach for the public-facing frontend. Running both adds mental overhead without a compelling reason.

Does Livewire 4 require Filament v5?

No. Filament v5 requires Livewire v4, but Livewire v4 works fine without Filament. You can upgrade Livewire independently. If you're on Filament, just verify your Filament version supports Livewire v4 before updating.

Is Inertia.js still the right pick if my frontend is mostly CRUD?

Probably not, if you're the only developer on the project. CRUD-heavy UIs are exactly where Livewire shines: you get reactive forms, real-time validation, and table interactions without touching JavaScript. Inertia makes more sense when the UI complexity justifies bringing in the JS ecosystem.

Which performs better?

It depends heavily on what you're building. For server-rendered content, Livewire has the edge because there's no JavaScript hydration cost. Inertia v3's Instant Visits feature narrows that gap for navigation, and SSR is now much easier to set up. For complex client-side interactions, Inertia's JavaScript-native approach typically performs better because state stays in the browser.

Inertia.js v3 Is Out: The Upgrade Guide Every Laravel Developer Actually Needs

Hafiz — Wed, 01 Apr 2026 05:07:52 +0000

Inertia.js v3 went stable on March 25. If you missed the announcement, it's a real major release, not one of those "major" bumps that changes nothing. Axios is gone, ESM is the only output format, React 18 and Svelte 4 are both dropped, and a handful of event names and APIs have changed. There's also a config file restructure that'll catch you off guard if you don't read the upgrade guide first.

The good news: v3 is genuinely better. The bundle is smaller, SSR works in dev without a separate Node.js process, and two new APIs (the useHttp hook and optimistic updates) solve problems that previously needed awkward workarounds. If you've been putting off upgrading to take stock of the situation first, this post is for you.

We also just went through a similar exercise with the Laravel 12 to 13 upgrade, which had zero breaking changes. Inertia v3 is different. Worth actually reading before you touch anything.

What's Actually New in v3

Before we get into what breaks, let's talk about why you'd want to upgrade at all.

The Vite plugin. This is the biggest quality-of-life change. Previously, setting up an Inertia app meant writing a resolve callback, a setup callback, and a separate SSR entry point with its own config. Now you just install @inertiajs/vite and your entry point can be a single createInertiaApp() call with no arguments. Page resolution, code splitting, and SSR config all happen automatically. It removes a surprising amount of boilerplate that you'd copy-paste from the docs and forget about for years.

SSR in dev mode. Before v3, if you were running SSR, you had to start a separate Node.js server to see it during development. Now the Vite plugin handles it automatically as part of npm run dev. No extra process, better error messages (it logs the component name and URL when SSR fails), and a flash-of-unstyled-content fix is included.

The useHttp hook. This one fills a genuine gap. In v2, if you needed to make an HTTP request that didn't trigger a page visit, like hitting a search endpoint or submitting to an API route, you'd reach for Axios or raw fetch and lose the reactive state you get from useForm. The new useHttp hook gives you the same developer experience as useForm (reactive processing, errors, progress, isDirty state) but for plain JSON requests. No page navigation, no full Inertia lifecycle.

// Vue example
const http = useHttp({ query: '' })

function search() {
  http.get('/api/search', { query: http.data.query })
}

If you've been mixing Axios calls inside Inertia components because there was no clean alternative, this replaces that pattern entirely. Pairs nicely with the REST API patterns covered here if you're calling your own endpoints.

Optimistic updates. Inertia now has first-class support for applying a UI change immediately before the server confirms it, then rolling it back automatically if the request fails. It works on the router, useForm, and useHttp. Concurrent optimistic requests are handled too, each with its own rollback snapshot.

router
  .optimistic((props) => ({
    post: { ...props.post, likes: props.post.likes + 1 },
  }))
  .post(`/posts/${post.id}/like`)

Before v3, building this pattern meant managing local state manually, writing your own rollback logic, and being careful about race conditions. Now it's one chained method call.

Layout props. You can now pass typed data from a page component into its persistent layout without needing an event bus or provide/inject. Pages declare layout props alongside the layout component, and the layout receives them as regular component props. Much cleaner than the workarounds people were using.

Instant visits. When navigating, Inertia can now swap to the target page component immediately using shared props, then merge in the page-specific props once the server responds. The navigation feels instant even though a full server request still happens. Opt in per-link with :instant or globally via config.

Can You Upgrade Right Now?

Before reading any further, this diagram gives you the quick answer based on your setup.

If the diagram lands you at "Upgrade now", the rest of this guide is your step-by-step path. If you're in one of the "migrate first" branches, come back once that's done. This post isn't going anywhere.

Before You Run composer update: Check Your Requirements

This is the part that'll bite you if you skip it. Inertia v3 has hard version requirements that you need to meet before installing anything.

PHP 8.2 and Laravel 11 are the minimum. If you're on Laravel 10 or PHP 8.1, you need to upgrade those first. Laravel 13 is fully compatible and has zero issues with Inertia v3. The Laravel adapter was tested against both L12 and L13 and there are no compatibility problems to worry about on the PHP side.

React 19 is required if you're using the React adapter. React 18 is no longer supported. This is the requirement most likely to cause a ripple effect through your dependency tree, since React 19 also requires updating things like react-dom, form libraries, and animation packages.

Svelte 5 is required for the Svelte adapter. Svelte 4 is dropped entirely. All Svelte code needs to be updated to Svelte 5's runes syntax: $props(), $state(), $effect(), and so on. This isn't a small change. If you're on Svelte 4, factor in real migration time.

Vite 7+ is required. Vite 6 is no longer supported. If you're on Vite 8 already, you're fine. If you're somewhere behind, check your package.json first.

Vue 3 users? You don't have any of these extra adapter concerns. The Vue adapter upgrade is the cleanest path.

The Upgrade Steps

With requirements confirmed, here's the actual upgrade sequence. Don't skip the last two commands, they're not optional.

One thing to check before you start: if you're using third-party Inertia packages like Inertia Modal, Inertia Table, or any community adapters, verify they have v3 support before upgrading. Some packages ship separate major versions for Inertia v3 compatibility (Inertia Table v3 for example targets Tailwind v4). Check each package's GitHub releases page. There's no point upgrading Inertia core if a critical package in your app isn't ready yet.

# Install the client adapter (pick your framework)
npm install @inertiajs/vue3@^3.0
# or: npm install @inertiajs/react@^3.0
# or: npm install @inertiajs/svelte@^3.0

# optional but recommended: install the Vite plugin
npm install @inertiajs/vite@^3.0

# upgrade the Laravel adapter
composer require inertiajs/inertia-laravel:^3.0

# republish the config file (it has been restructured in v3)
php artisan vendor:publish --provider="Inertia\\ServiceProvider" --force

# clear cached views (@inertia directive output has changed)
php artisan view:clear

After the package installs, work through this checklist before you test anything. It covers every breaking change you'll need to handle.

Breaking Changes to Fix

Here's the full breakdown of what needs changing, with before/after code for each.

Event renames

Two global router events have been renamed. If you've got router.on() listeners anywhere in your app, search for both of these.

// Before (v2)
router.on('invalid', (event) => { /* ... */ })
router.on('exception', (event) => { /* ... */ })

// After (v3)
router.on('httpException', (event) => { /* ... */ })
router.on('networkError', (event) => { /* ... */ })

You can also handle these per-visit now using onHttpException and onNetworkError callbacks, which didn't exist in v2.

Axios, qs, and lodash-es are gone

Inertia no longer bundles any of these. For most apps this means nothing changes, because you weren't importing them directly from Inertia's internals. But if any of your code does import axios from 'axios', import qs from 'qs', or import _ from 'lodash-es' and those packages were implicit transitive dependencies, you'll need to install them directly.

npm install axios   # if you still need it
npm install qs      # if your code imports it directly
npm install lodash-es  # if your code imports it directly

Axios is still usable, just not required. The built-in XHR client supports interceptors natively, so if you were using Axios interceptors you can migrate them directly.

The `inertia` head attribute became `data-inertia`

Open your root Blade template and look in the <head> section. Any element with the inertia attribute needs it renamed.

<!-- Before (v2) -->
<title inertia>My App</title>

<!-- After (v3) -->
<title data-inertia>My App</title>

Small change, easy to miss. Affects any head element you're managing with Inertia's <Head> component.

`router.cancel()` became `router.cancelAll()`

// Before (v2): only cancelled synchronous requests
router.cancel()

// After (v3): cancels all request types by default
router.cancelAll()

// To match v2 behavior exactly (sync only)
router.cancelAll({ async: false, prefetch: false })

`Inertia::lazy()` is removed

If you were using Inertia::lazy() on any backend response, switch it to Inertia::optional(). Same behaviour, different name. The LazyProp class is also removed.

// Before (v2)
return Inertia::render('Users/Index', [
    'users' => Inertia::lazy(fn () => User::all()),
]);

// After (v3)
return Inertia::render('Users/Index', [
    'users' => Inertia::optional(fn () => User::all()),
]);

Progress indicator exports

// Before (v2)
import { hideProgress, revealProgress } from '@inertiajs/vue3'
hideProgress()
revealProgress()

// After (v3)
import { progress } from '@inertiajs/vue3'
progress.hide()
progress.reveal()

The `future` config block is gone

If you were using v2's future options in createInertiaApp, just delete the entire future block. All four options are now always enabled and can't be toggled.

// Before (v2)
createInertiaApp({
    defaults: {
        future: {
            preserveEqualProps: true,
            useDataInertiaHeadAttribute: true,
        },
    },
})

// After (v3): just remove it
createInertiaApp({
    // ...
})

Config file restructuring

After running vendor:publish --force, open the new config/inertia.php and compare it side by side with your old one. Page-related settings have moved under a pages key, and the testing section is simplified. Don't just overwrite and hope. Review the diff. The Diff Checker tool is handy for this if you saved a copy of your old config.

ESM-only output

All Inertia packages now ship as ES Modules only. CommonJS require() imports no longer work.

// Before (v2): worked in some setups
const { router } = require('@inertiajs/vue3')

// After (v3): ESM only
import { router } from '@inertiajs/vue3'

If your build setup was relying on CommonJS in any way, this is the one to audit carefully.

Two Things Worth Using Right Away

Once the upgrade is done, two features are worth reaching for immediately.

useHttp for non-navigation requests. If you're building a Laravel + Vue SPA and have any search boxes, autocomplete fields, or background data fetches that aren't page visits, replace them with useHttp. You get reactive state, proper error handling, and upload progress for free. No more mixing Axios calls into Inertia components.

Optimistic updates for interactive actions. Like buttons, follow buttons, toggles, anything where the user takes an action and you're confident it'll succeed. Chain .optimistic() before the request, define the expected state change, and let Inertia handle the rollback if something goes wrong. It's the kind of UX improvement that takes days to implement correctly from scratch and ten minutes with v3.

If you're also using Wayfinder with Inertia for type-safe routing, the Laravel Wayfinder guide here is worth revisiting since Inertia v3's typed form generics pair well with Wayfinder's typed route parameters.

Should You Upgrade This Weekend?

Depends on your stack.

Upgrade now if you're on Vue 3, Laravel 11+, PHP 8.2+, and Vite 7+. The breaking changes are real but mechanical. Search and replace, rename two or three methods, republish the config, clear views. Most of the checklist items above take less than five minutes each. You'll be done in an afternoon. The Vite plugin alone makes it worth it, and the removed Axios dependency is a free bundle size reduction you'd otherwise have to work for.

Wait if you're on the React adapter and haven't upgraded to React 19. That's a separate, larger upgrade and you shouldn't do both at once. Get your React 19 migration done first, make sure everything still works, then layer in Inertia v3. Same story for Svelte 4 apps. The Svelte 5 runes migration is a real rewrite, not a find-and-replace. Don't combine it with an Inertia upgrade in the same PR.

Don't rush if you're running a production app with SSR and you haven't got a proper staging environment to test on. The SSR improvements in v3 are genuinely good, but SSR changes are also the most likely to surface behaviour differences between environments. Test on staging, watch it for a day, then deploy.

One more thing worth knowing: Laravel Boost ships with an UpgradeInertiaV3 prompt if you're using it. It walks through the upgrade automatically. Worth checking before you do it manually.

v2 isn't going anywhere immediately, so there's no pressure. But v3 is the better version, and if your requirements are already met, there's no reason to sit on it.

Frequently Asked Questions

Do I have to use the new Vite plugin?

No. The @inertiajs/vite plugin is optional. Your existing setup with resolve and setup callbacks still works in v3. The plugin just simplifies things if you want it to.

Can I still use Axios with Inertia v3?

Yes. Axios is no longer bundled or required, but it's still available as an optional peer dependency. Install it manually and use the Axios adapter if you prefer to keep your existing interceptor setup.

What if I'm on Laravel 10?

The Laravel adapter v3 requires Laravel 11 at minimum. You'd need to upgrade Laravel first. Laravel 10 reaches end of life in August 2026, so the upgrade is worth doing regardless.

Does Inertia v3 work with Filament?

Filament uses Livewire under the hood, not Inertia. The two don't interact. If you're building an admin panel with Filament alongside an Inertia-powered frontend, the Inertia upgrade doesn't affect Filament at all.

Is the useHttp hook available in all three adapters?

Yes. Vue, React, and Svelte all have it. The API is the same across adapters: reactive processing, errors, progress, and isDirty state, plus get(), post(), put(), patch(), and delete() methods.

What's Next

The upgrade itself isn't the hard part. The actual work is auditing your codebase for the three or four breaking changes that affect you specifically. Run through the checklist above item by item, fix what needs fixing, and test on a feature branch before touching main.

If you're building a new Laravel app from scratch and debating whether to use Inertia at all, v3 is the most compelling version yet. Smaller bundle, less configuration, and a feature set that competes seriously with decoupled SPA setups for most use cases.

Got a specific upgrade question or a weird edge case you ran into? Reach out, happy to dig into it.

Cache::funnel() in Laravel: Concurrency Limiting Without Redis

Hafiz — Mon, 30 Mar 2026 06:04:56 +0000

Picture a queue of jobs that each call an external AI provider. Your API key allows 5 concurrent requests. Any more and you start getting 429s. Any fewer and you're leaving throughput on the table.

The classic Laravel solution was Redis::funnel(). Which meant you needed Redis. Not great when your project runs on the file or database cache driver. And genuinely painful in tests, where you either had to mock the Redis facade (fragile), spin up a real Redis instance in CI (annoying), or skip testing the concurrency logic altogether (common, but not ideal).

Laravel 12.53.0 shipped Cache::funnel(). Same concept, same API shape, but backed by any lock-capable cache driver. File, database, Redis, or the array driver in tests. Your concurrency logic stops being coupled to your infrastructure choice.

Here's what it does, how to use it, and when it actually matters.

A Quick Recap of What Redis::funnel() Was Doing

Before the new API makes sense, it's worth understanding the old one.

Redis::funnel() used Redis Lua scripts to manage a pool of execution slots atomically. You'd define a key for the resource you wanted to protect, set a limit on concurrent executions, and the Lua script handled the semaphore logic on the Redis side.

Redis::funnel('ai-api-calls')
    ->limit(5)
    ->releaseAfter(120)
    ->block(30)
    ->then(function () {
        // at most 5 of these running at once
    }, function () {
        $this->release(60);
    });

It worked well. Still works well. But you couldn't use it without Redis, and you couldn't test it without Redis either. That's the friction Cache::funnel() resolves.

The New API

Cache::funnel() lives on the Cache facade and uses the cache layer's lock primitives rather than Redis-specific scripts. Any driver implementing LockProvider works: database, file, Redis, and the array driver you're probably already using in tests.

use Illuminate\Support\Facades\Cache;

Cache::funnel('ai-api-calls')
    ->limit(5)
    ->releaseAfter(120)
    ->block(30)
    ->then(function () {
        // slot acquired
    }, function () {
        // couldn't get a slot within block time
    });

If you've used Redis::funnel() before, this reads identically. That's intentional. Let's break down each method so nothing is ambiguous.

limit()

Sets the maximum number of concurrent executions that can hold a slot. ->limit(5) means at most 5 closures are running simultaneously. The 6th caller blocks or fails, depending on your block() setting.

releaseAfter()

The safety TTL, in seconds. If a process acquires a slot and then crashes or gets killed before finishing, the slot auto-expires after this many seconds. It's not a timeout for how long your work should take. Think of it as a dead-man's switch so slots don't stay locked forever after a crash.

Set this realistically. If your job can legitimately take four minutes, a releaseAfter(60) means crashed processes release slots after one minute and new executions grab them before previous ones are done. When in doubt, overestimate.

block()

How long a caller should wait for a slot to become available before giving up. ->block(30) means wait up to 30 seconds. ->block(0) means don't wait at all: try once, and if no slot is available right now, immediately run the failure callback.

then()

Two callables. The first runs when a slot is acquired. The second runs when the block time expires without getting one. The slot releases automatically when the first callable returns, so the next waiting caller can grab it.

If you'd rather handle failure via exceptions than a callback, leave the second argument out:

use Illuminate\Cache\Limiters\LimiterTimeoutException;

try {
    Cache::funnel('ai-api-calls')
        ->limit(5)
        ->releaseAfter(120)
        ->block(30)
        ->then(function () {
            // runs with a slot
        });
} catch (LimiterTimeoutException $e) {
    // block time expired, no slot acquired
    Log::warning('Could not acquire concurrency slot', ['key' => 'ai-api-calls']);
}

And if you need a specific store rather than the default:

Cache::store('database')->funnel('ai-api-calls')
    ->limit(5)
    ->releaseAfter(120)
    ->block(30)
    ->then(function () {
        // locked to the database store explicitly
    });

One thing to flag upfront: Memcached doesn't implement LockProvider. Calling Cache::funnel() on a Memcached-backed store throws BadMethodCallException. If Memcached is your default driver, call Cache::store('database')->funnel() or Cache::store('redis')->funnel() explicitly instead.

Here's how the full slot acquisition flow works when you call Cache::funnel():

The key thing to notice: the slot releases automatically when the success closure returns. You don't call anything manually. And if a process crashes before returning, releaseAfter handles the cleanup on a timer.

Use Case 1: Throttling External API Calls in Queue Jobs

This is the most common reason to reach for concurrency limiting. You have a pool of jobs calling an external service and you need to stay within its concurrency cap.

If you're not on Laravel 12.53.0 yet, check the upgrade guide first, since Cache::funnel() isn't available in earlier versions.

Here's a queue job that limits itself to 5 concurrent calls against an external AI API:

class ProcessAiRequest implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 10;
    public int $backoff = 60;

    public function __construct(private readonly string $prompt) {}

    public function handle(): void
    {
        Cache::funnel('ai-api-concurrency')
            ->limit(5)
            ->releaseAfter(120)
            ->block(30)
            ->then(
                function () {
                    $response = Http::withToken(config('services.ai.key'))
                        ->timeout(90)
                        ->post('https://api.example.com/v1/generate', [
                            'prompt' => $this->prompt,
                        ]);

                    // process $response
                },
                function () {
                    // no slot within 30 seconds, re-queue
                    $this->release(60);
                }
            );
    }
}

The slot releases the moment the closure returns, so the next waiting job can grab it. If the job crashes mid-execution, the slot releases after 120 seconds. Workers just keep pulling from the queue and the funnel manages the cap invisibly.

The funnel key 'ai-api-concurrency' is global here, meaning the limit applies across all workers and all processes combined. That's usually exactly what you want when limiting against a shared external resource with a fixed API key.

If you're structuring more complex pipelines with different agent types, the multi-agent queue patterns post covers how to approach those. Per-agent-type limits fit naturally into that kind of setup, where you'd just make the key more specific: "ai-concurrency:{$agentType}".

Use Case 2: Per-User Report Generation

Classic SaaS problem. Users can kick off report generation, and you want at most 2 running per user at once. More than that and the server starts to feel it. Less than that is fine: just tell the user their report is queued.

public function generateReport(User $user, Report $report): void
{
    Cache::funnel("report-generation:{$user->id}")
        ->limit(2)
        ->releaseAfter(300)
        ->block(0)
        ->then(
            function () use ($report) {
                $report->generate();
            },
            function () use ($report) {
                $report->markAsQueued();
                UserNotification::send($report->user, 'Your report is queued and will start shortly.');
            }
        );
}

->block(0) is intentional. You don't want to hold up the current request waiting for a slot. If both slots are taken, fall into the failure callback immediately and handle it gracefully.

The funnel key includes the user ID, so each user gets their own independent slot pool. One user hammering the generate button a dozen times doesn't affect anyone else's quota. That's the real value: fine-grained per-entity control with very little code.

This kind of control complements the queue topology patterns covered in the queue jobs post. You can configure your workers to run a large number of concurrent jobs at the queue level, then use Cache::funnel() inside jobs to apply more targeted limits based on the resource being accessed.

Use Case 3: Testing Without Infrastructure

This is the improvement I'm most excited about, and the one the PHP community noticed quickest when the PR landed.

Before Cache::funnel(), testing concurrency logic meant wrestling with infrastructure. Your choices with Redis::funnel() were: mock the Redis facade (you're testing your mock, not your logic), spin up Redis in CI (more setup, more cost), or skip testing it at all (the most honest option, and the most common).

With the array driver, all of that goes away. Your concurrency logic tests run in pure in-memory isolation with zero infrastructure:

use Illuminate\Support\Facades\Cache;

it('blocks executions beyond the concurrency limit', function () {
    $acquired = 0;
    $blocked = 0;

    for ($i = 0; $i < 5; $i++) {
        Cache::store('array')->funnel('test-resource')
            ->limit(2)
            ->releaseAfter(60)
            ->block(0)
            ->then(
                function () use (&$acquired) { $acquired++; },
                function () use (&$blocked) { $blocked++; }
            );
    }

    expect($acquired)->toBe(2);
    expect($blocked)->toBe(3);
});

No Redis connection, no Docker service, no special test helpers. The test proves your concurrency logic works correctly and runs in milliseconds.

This testing story alone is a compelling reason to migrate away from Redis::funnel() in any application where you actually want to test this kind of behaviour.

Using It in Job Middleware

So far all the examples put the funnel logic inside handle(). That works, but there's a cleaner pattern for queue jobs: defining it in the job's middleware() method.

use Illuminate\Support\Facades\Cache;

class ProcessAiRequest implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function middleware(): array
    {
        return [
            function ($job, $next) {
                Cache::funnel('ai-api-concurrency')
                    ->limit(5)
                    ->releaseAfter(120)
                    ->block(0)
                    ->then(
                        fn () => $next($job),
                        fn () => $job->release(60)
                    );
            },
        ];
    }

    public function handle(): void
    {
        // handle() only runs if the funnel granted a slot
        $response = Http::withToken(config('services.ai.key'))
            ->post('https://api.example.com/v1/generate', [
                'prompt' => $this->prompt,
            ]);
    }
}

The advantage here is separation of concerns. The concurrency limit is declared alongside the job's other infrastructure concerns (retries, backoff, timeout) rather than buried inside the business logic. The handle() method stays focused on what the job actually does.

This pattern is especially useful when multiple job types need the same concurrency limit. You can extract the middleware closure into a shared class and reference it from each job rather than duplicating the funnel configuration everywhere.

Cache::funnel() vs Cache::withoutOverlapping()

Both live in the concurrency limiting section of the Laravel docs and it's easy to confuse them. They solve different problems.

Cache::withoutOverlapping() is for single-instance control: only one execution at a time, globally. Use this for scheduled commands where two copies running simultaneously would be a bug.

Cache::withoutOverlapping('nightly-data-sync', function () {
    DataSync::runAll();
});

Cache::funnel() is for controlled parallelism: up to N concurrent executions, but not unlimited. Use this when some concurrency is fine, you just need a ceiling on it.

The classic CS framing: withoutOverlapping is a mutex (one at a time), funnel is a semaphore (N at a time). Reach for withoutOverlapping when concurrency is always wrong for the operation. Reach for funnel when it's acceptable but needs a cap.

Should You Migrate Away From Redis::funnel()?

If you're already using Redis::funnel() and it works, nothing is broken and nothing is deprecated. There's no urgent reason to change.

The migration itself is a straight swap at each call site:

// Before
Redis::funnel('ai-api-calls')
    ->limit(5)
    ->releaseAfter(120)
    ->block(30)
    ->then(fn () => $this->callApi(), fn () => $this->release(60));

// After
Cache::funnel('ai-api-calls')
    ->limit(5)
    ->releaseAfter(120)
    ->block(30)
    ->then(fn () => $this->callApi(), fn () => $this->release(60));

Just the facade changes. Everything else is identical. If you're on Redis in production, the behaviour is equivalent since Cache::funnel() delegates to the same lock primitives on the Redis driver.

That said, there are three concrete reasons to prefer Cache::funnel() going forward.

First, no hard Redis dependency. If your cache driver ever changes, your concurrency logic moves with it. No code changes, no surprise errors in a staging environment that uses a different driver than production.

Second, it's testable without infrastructure. Array driver in tests, real driver in production. You write tests that actually exercise the concurrency logic rather than mocking around it.

Third, it's one fewer abstraction to maintain. Redis::funnel() lives in the Redis documentation. Cache::funnel() lives in the Cache documentation. One facade, one section of the docs, one mental model for your team.

The underlying mechanism differs: Redis::funnel() uses Lua scripts, Cache::funnel() uses the lock primitives the cache driver exposes. But for application-level concurrency control, the behaviour is equivalent and the difference is invisible to your application code.

Things to Watch Out For

Memcached is unsupported. If your default cache driver is Memcached, Cache::funnel() throws BadMethodCallException. Either switch to a supported driver or call a specific store like Cache::store('database')->funnel().

Set releaseAfter conservatively. If the work could legitimately take five minutes, a 60-second TTL means crashed processes release slots before work finishes and new ones grab them. You end up with more concurrent executions than your limit() intended. Overestimate rather than underestimate.

block(0) needs a failure handler you actually wrote. With zero wait time, any call that doesn't immediately get a slot hits the failure callback. Returning nothing silently from that callback is almost always wrong. Re-queue the job, notify the user, log a warning, or do something intentional.

This is application-level, not queue-level. Cache::funnel() doesn't configure Horizon or tell your queue supervisor to run fewer concurrent workers. If you need to control queue-level concurrency, that's a separate configuration. These are complementary tools.

The key is global across all workers. The funnel key 'api-calls' applies across every worker process and every server. That's what you want when the limit comes from a shared external resource. If you need per-server limits, scope the key: "api-calls:{$serverId}".

FAQ

Which Laravel version introduced Cache::funnel()?

It was merged February 21, 2026 and shipped in Laravel 12.53.0. It's also in Laravel 13 from the initial release.

Which cache drivers support it?

Redis, database, file, and array drivers all implement LockProvider and work with Cache::funnel(). Memcached does not, and calling funnel() on it throws BadMethodCallException.

What happens if a process crashes mid-execution?

The slot auto-releases after the releaseAfter timeout. Set it long enough to cover legitimate execution time, otherwise crashed processes release slots early and new executions start before previous ones are done.

Can I skip the failure callback?

Yes. Omit the second argument to ->then() and LimiterTimeoutException is thrown when block time expires without getting a slot. Useful if you'd rather handle failure in a catch block than a closure.

Is this the same as rate limiting middleware?

No. The throttle middleware controls request frequency: how many requests per minute from a given client. Cache::funnel() controls concurrent executions: how many can run at the same time. Different problems, different tools.

Can I use this in a scheduled command?

Yes, but Cache::withoutOverlapping() is usually the better fit for commands where you want zero overlap. Use Cache::funnel() when some parallelism is fine but you need a specific cap.

Wrapping Up

Cache::funnel() is one of those changes that quietly fixes a real friction point. Concurrency logic in Laravel shouldn't require Redis. Tests for that logic shouldn't require infrastructure.

If you've been relying on Redis::funnel(), the migration is straightforward: same method chain, different facade call. If you've been avoiding concurrency limiting because the Redis dependency was awkward or the testing story was painful, those excuses are gone now.

The pattern is genuinely useful once you start seeing where it applies. Per-user limits, per-resource limits, per-API-key throttling. Most queue-heavy features have at least one spot where Cache::funnel() simplifies the code and removes a dependency you didn't need.

Questions or edge cases I didn't cover? Get in touch and we can dig into it.

Laravel AI SDK: 3 Multi-Agent Patterns Worth Using in Production (and 2 to Skip)

Hafiz — Fri, 27 Mar 2026 06:56:08 +0000

Most Laravel developers building AI features make the same mistake. They read about multi-agent patterns, get excited, and wire up an orchestrator-workers system on their very first feature. A week later they're debugging dynamic planning logic, API costs are unpredictable, and the feature still hasn't shipped.

The Laravel AI SDK makes spinning up agents so easy that it lowers the barrier to overengineering. That's not a criticism of the SDK. It's just a trap worth naming before you fall into it.

Anthropic's original research identified five multi-agent patterns. The official Laravel blog covered all five on March 13 with clean code examples. What it didn't say is which ones you should actually reach for first, and which ones will cost you more than they're worth in a typical SaaS context.

This is that post.

A quick note on approach: all the code examples below use proper Agent classes generated with php artisan make:agent, not the agent() helper shorthand you'll see in most tutorials. The helper is great for prototyping. But in production, you want Agent classes. They're testable with the SDK's built-in fakes, the instructions live in one place, and when a prompt breaks in production you know exactly where to find it.

What Multi-Agent Patterns Actually Are

A single agent is one AI call with a system prompt. You send a prompt, you get a response. Simple. Multi-agent patterns are structured ways to chain, route, or run multiple AI calls together so complex tasks get broken into focused steps.

The five patterns Anthropic identified: prompt chaining, routing, parallelization, orchestrator-workers, and evaluator-optimizer. Each solves a different problem. Three of them are practical for most Laravel SaaS apps today. Two of them are expensive and difficult to debug unless you've got a very specific use case.

Let's go through the three worth shipping first.

Pattern 1: Prompt Chaining

This is the assembly line. Agent A does step 1 and passes its output to Agent B, which does step 2 and passes to Agent C. Each agent has one job and does it well.

Laravel's built-in Pipeline handles this naturally. Each step wraps a dedicated Agent class and enriches the payload before passing it forward.

Here's a real-world example: a lead enrichment pipeline for a CRM. A salesperson drops in a company name, and three agents run in sequence to produce a ready-to-send outreach email.

php artisan make:agent LeadResearcher
php artisan make:agent LeadScorer
php artisan make:agent OutreachDrafter

Each Agent class defines focused instructions:

<?php

namespace App\Ai\Agents;

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

class LeadResearcher implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a B2B lead researcher. Given a company name, write a 3-sentence brief: what they do, their likely tech stack, and their growth stage. Be concise and factual.';
    }
}

The pipeline steps wrap each agent and pass the enriched payload forward:

<?php

namespace App\Ai\Pipeline;

use App\Ai\Agents\LeadResearcher;
use Closure;

class ResearchStep
{
    public function handle(array $payload, Closure $next): array
    {
        $brief = (string) (new LeadResearcher)->prompt($payload['company']);

        return $next([...$payload, 'research' => $brief]);
    }
}

Wire it together in a controller or job:

use Illuminate\Support\Facades\Pipeline;

$result = Pipeline::send(['company' => 'Acme Corp'])
    ->through([
        ResearchStep::class,
        ScoringStep::class,
        OutreachStep::class,
    ])
    ->thenReturn();

That's it. Three agents, three focused jobs, one clean result. You can test each step independently, which is genuinely valuable when something breaks in production. The instructions live in their own class, so updating the researcher prompt doesn't touch the scorer or the drafter.

Chaining also scales well with complexity. Need to add a "tone check" step between scoring and drafting? Add one pipeline class. Need to skip the scoring step for returning customers? Add a conditional in that step. The structure absorbs changes cleanly, which is more than you can say for a single 800-word system prompt trying to do five things at once.

Use chaining when: the task has a clear sequence where each step depends on the previous one. Draft, validate, refine. Extract, classify, format. Research, score, write.

Pattern 2: Routing

Routing means classifying the input first, then sending it to the right specialist. One agent reads the request and decides which agent should handle it. Different input types get different instructions. Different complexity levels can get different models and different costs.

This is the pattern that makes the most economic sense for support bots and anything where inputs vary widely.

php artisan make:agent TicketClassifier
php artisan make:agent BillingAgent
php artisan make:agent TechnicalAgent
php artisan make:agent GeneralSupportAgent

The classifier returns a single category word, nothing else:

class TicketClassifier implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'Classify the support ticket into exactly one of: billing, technical, general. Respond with just the category word, nothing else.';
    }
}

The router reads that category and dispatches to the right specialist:

<?php

namespace App\Support;

use App\Ai\Agents\BillingAgent;
use App\Ai\Agents\GeneralSupportAgent;
use App\Ai\Agents\TechnicalAgent;
use App\Ai\Agents\TicketClassifier;

class SupportRouter
{
    public function route(string $ticket): string
    {
        $category = (string) (new TicketClassifier)->prompt($ticket);

        return match (trim(strtolower($category))) {
            'billing'   => (string) (new BillingAgent)->prompt($ticket),
            'technical' => (string) (new TechnicalAgent)->prompt($ticket),
            default     => (string) (new GeneralSupportAgent)->prompt($ticket),
        };
    }
}

You can take this further by specifying different providers per agent in the prompt() call. Simple billing questions can go to a cheaper, faster model. Complex technical issues go to a more capable one. The classifier call pays for itself quickly once you're handling real volume.

Here's what that looks like for the technical agent specifically:

use Laravel\Ai\Enums\Lab;

// In TechnicalAgent's caller, or via the prompt() override:
(string) (new TechnicalAgent)->prompt(
    $ticket,
    provider: Lab::Anthropic,
    model: 'claude-opus-4-5-20251101'
);

// Billing uses the default cheaper model from config/ai.php
(string) (new BillingAgent)->prompt($ticket);

The total cost for a billing ticket drops significantly while technical tickets still get the full model. That's a cost profile that actually makes sense in production, especially at scale.

Here's what the routing flow looks like:

Use routing when: inputs vary significantly in type or complexity, and a single prompt can't handle all cases cleanly without turning into a mess of conditional instructions.

Pattern 3: Parallelization

When multiple agents need to look at the same input independently, there's no reason to run them one by one. Laravel's Concurrency::run() lets you kick all of them off simultaneously and collect results when they're done.

The time difference is real. Three agents in parallel takes roughly the same wall-clock time as one. Three agents in sequence takes three times as long.

Here's a document analysis example. You've got a contract and want legal, financial, and risk assessments all at once:

php artisan make:agent LegalReviewer
php artisan make:agent FinancialAnalyzer
php artisan make:agent RiskAssessor
php artisan make:agent ContractSummaryAgent

Run the three specialists in parallel, then feed their outputs to a summary agent:

use App\Ai\Agents\ContractSummaryAgent;
use App\Ai\Agents\FinancialAnalyzer;
use App\Ai\Agents\LegalReviewer;
use App\Ai\Agents\RiskAssessor;
use Illuminate\Support\Facades\Concurrency;

[$legal, $financial, $risk] = Concurrency::run([
    fn () => (string) (new LegalReviewer)->prompt($contract),
    fn () => (string) (new FinancialAnalyzer)->prompt($contract),
    fn () => (string) (new RiskAssessor)->prompt($contract),
]);

$summary = (string) (new ContractSummaryAgent)->prompt(
    "Legal review:\n{$legal}\n\nFinancial analysis:\n{$financial}\n\nRisk assessment:\n{$risk}"
);

The ContractSummaryAgent only runs after all three are done, so it has the full picture. This pattern also pairs naturally with queued jobs when you're processing documents asynchronously. If you're not already confident with Laravel queues at scale, this breakdown on processing large job volumes covers the fundamentals worth knowing before you lean into async agent pipelines.

Note: Concurrency::run() was introduced in Laravel 11. If you're still on Laravel 10, you'll need to handle parallelism through process pools or queued jobs instead.

One thing worth handling in production: if one of the parallel agents fails, Concurrency::run() will throw. Wrap it in a try/catch and decide whether you want to fail the whole request or fall back to running the failed agent synchronously. For document analysis, falling back gracefully is usually better than failing the whole operation over one specialist's timeout.

Use parallelization when: multiple independent specialists need to look at the same input, or when you need several separate analyses that don't depend on each other's results.

The Two Patterns to Skip (For Now)

Orchestrator-Workers

This one sounds compelling. A manager agent receives a complex task, breaks it into subtasks dynamically, delegates to worker agents, and assembles the result.

The problem in practice: the orchestrator runs an internal agentic loop. It needs to reason about what steps are required, call worker tools in an order it determines at runtime, and figure out when it's done. That means you can't predict token usage, you can't easily trace what happened when something breaks, and testing becomes genuinely hard.

For most SaaS features, the required steps aren't actually unknown at runtime. You just think they are. Nine times out of ten, you can replace a dynamic orchestrator with a well-structured chaining pipeline and end up with something cheaper, faster, and debuggable. A three-step pipeline that you wrote is easier to maintain than a planning loop you're hoping the model executes correctly.

The orchestrator pattern earns its place when the task genuinely varies in structure. A code generation agent that might need to create five files or fifteen depending on the feature request. A research agent that needs to decide how many sources to query. If your task has a predictable shape, use chaining. You'll know when orchestration is actually necessary because a fixed pipeline genuinely can't handle the variability.

Evaluator-Optimizer

This pattern loops: generate output, score it, rewrite if it doesn't meet the bar, repeat up to N times. Sounds great for quality. It's brutal on cost.

Think about what "3 refinement iterations" actually means in production. That's up to four API calls per user action: one write, one evaluate, one rewrite, one final evaluate. If you're generating content at any real volume, that multiplier compounds fast. A feature that processes 1,000 requests per day and costs $0.01 per single-agent call becomes $0.04 with a 3-iteration evaluator loop. Doesn't sound like much until it's running for a month.

There's also the latency problem. Each iteration adds a full round-trip to an AI provider. If you're doing this synchronously in a web request, you're looking at 10-20 seconds of wait time by the third iteration. That's not a user experience you want to ship.

The evaluator pattern genuinely earns its place when output quality is business-critical and a human would otherwise review every result. Legal document drafting. Medical content. Anything where a bad output has real consequences. For most SaaS AI features, a single well-prompted agent with a clear output schema and structured output validation does the job at a fraction of the cost.

If you're building a RAG-powered support system and want better response quality without retry loops, the Part 2 tutorial on tools and memory covers how to get more out of a single agent before reaching for the evaluator.

A Simple Decision Framework

Before picking a pattern, ask two questions: does the task have a predictable structure, and do the steps depend on each other?

Situation	Pattern
Clear sequence, each step depends on the previous	Chaining
Inputs vary in type or complexity	Routing
Multiple independent analyses of the same input	Parallelization
Steps are genuinely unknown until runtime	Orchestrator-workers
Output quality needs iterative refinement	Evaluator-optimizer

Start with a single well-prompted Agent class. If one agent can't do the job cleanly, reach for chaining first. Then routing or parallelization if the shape fits. The orchestrator and evaluator are there when you actually need them, and you'll know when you do.

FAQ

Do I need to pick one pattern, or can I mix them?

You can mix them freely. A routing pattern that dispatches tickets to specialist agents could use chaining inside the technical agent for complex multi-step resolution. The patterns compose. Just start with the simplest thing that works and layer from there.

What's the actual cost difference between chaining and parallelization?

Same number of API calls, different wall-clock time. Chaining runs them in sequence so total time is the sum of all agent response times. Parallelization runs them simultaneously so total time is roughly the slowest single agent. Costs are identical. Pick based on whether the steps depend on each other, not on cost.

Does this work with Laravel 11, 12, and 13?

Yes. The Laravel AI SDK supports all three. Concurrency::run() for parallelization requires Laravel 11 or later. For Laravel 10 you'll need a different approach to parallel execution. The Agent class patterns for chaining and routing work on any supported version.

How do I test multi-agent workflows?

The AI SDK includes built-in fakes. You can fake each Agent class in tests and assert it was called with the right prompt in the right order. The 30-minute SDK tutorial covers the testing utilities in detail before you start wiring up multi-step pipelines.

When should I use php artisan make:agent vs. the agent() helper?

The agent() helper is fine for one-off calls and prototyping. For production multi-agent workflows, use proper Agent classes. They're testable, reusable, and the instructions live in one place. When you need to update a system prompt, you know exactly where to look. The complete Claude Code and Laravel ecosystem guide covers how Agent classes fit into a larger agentic dev setup if you want the full picture.

Wrapping Up

Multi-agent patterns are a real leap in what you can build with AI in Laravel. But the best one to start with is almost always the simplest one that solves the actual problem. Get a single agent working first. Then use chaining to add structure, routing to handle variety, and parallelization to cut wait time. Save the orchestrator and evaluator for when the task genuinely demands them.

The Laravel AI SDK makes all of this feel like writing normal Laravel code. The Pipeline is already there. Concurrency is already there. You're just pointing agents at it. And because each Agent class is a plain PHP class with a well-defined interface, your tests stay clean and your prompts stay maintainable as the feature evolves.

The patterns you skip today aren't gone forever. Once you've shipped chaining in production and have a handle on your real API costs and latency profile, you'll have a much clearer sense of whether an orchestrator or evaluator is worth reaching for. Most of the time you'll find the simpler patterns got you further than you expected.

If you're building multi-agent workflows for a client project or a SaaS and want a second set of eyes on the architecture, get in touch.

Laravel 13 Queue::route(): One Place to Control Your Entire Queue Topology

Hafiz — Wed, 25 Mar 2026 06:08:00 +0000

Every Laravel app I've worked on ends up with the same queue mess eventually. You start clean: one default queue, all jobs go there, life is simple. Then a client complains that emails are slow, so you spin up a dedicated emails queue with its own worker. Then Stripe webhooks start backing up, so billing gets its own queue too. Then AI processing jobs show up and they're eating into everything else, so heavy points at a beefier Redis connection with more memory.

Six months later, your queue topology lives in three different places at once: $queue properties on some job classes, ->onQueue() chains scattered across controllers and scheduled commands, and a handful of jobs that never got configured and quietly fall into the default queue. Change one queue name and you're grep-ing the entire codebase. Add a new developer and they have no idea where to look. The answer to "where does ProcessInvoice go?" is: everywhere, depending on who wrote the dispatch call.

Laravel 13 ships Queue::route(). Same philosophy as RateLimiter::for() for rate limits, or Route::model() for model binding. Infrastructure config belongs in one place, not spread across twenty job classes. This is the post I wished existed when I was cleaning up a SaaS codebase with eleven queues and zero consistency.

Here's how it works, how to use interface-based routing to make it scale, and how to migrate an existing app without breaking anything.

The Two Patterns You're Probably Mixing Right Now

Before Queue::route(), you had two real options when you needed a job on a specific queue.

Option one: class properties. Works, but it makes the job class aware of your infrastructure.

class ProcessInvoice implements ShouldQueue
{
    use Queueable;

    public string $queue = 'billing';
    public string $connection = 'sqs';
}

ProcessInvoice shouldn't care that you're using SQS in production but database in staging. That's an environment concern, not a business logic concern. And if you want to move this job to a different queue, you have to touch the class itself. That should only happen when the business logic changes, not because you're reorganizing infrastructure.

Option two: chaining at dispatch. Pushes the infrastructure knowledge to the caller instead.

ProcessInvoice::dispatch($invoice)
    ->onQueue('billing')
    ->onConnection('sqs');

Now every controller, command, and listener that dispatches this job has to remember to chain the right queue and connection. Miss one call site and the job silently lands on the default queue. No errors. No warnings. Just slower billing processing and a confused dev watching the billing Horizon worker idle while the default queue grows.

In practice, most apps end up mixing both patterns. Some jobs use class properties. Some use dispatch chaining. A few have it in both places and one overrides the other in a way nobody can remember without checking. When you onboard someone new, there's no obvious place to look. You just have to grep and hope.

Queue::route() replaces both patterns with one.

How Queue::route() Works

You register your queue topology once, in AppServiceProvider::boot():

use Illuminate\Support\Facades\Queue;

public function boot(): void
{
    Queue::route(ProcessInvoice::class, connection: 'sqs', queue: 'billing');
    Queue::route(SendWelcomeEmail::class, queue: 'emails');
    Queue::route(GenerateReport::class, connection: 'redis', queue: 'heavy');
    Queue::route(ProcessPodcast::class, queue: 'media');
}

Done. Every dispatch of ProcessInvoice now automatically lands on the billing queue using the sqs connection, regardless of where in your codebase you dispatch it. No chaining. No class properties required.

// Goes to billing/sqs automatically
ProcessInvoice::dispatch($invoice);

// So does this, from anywhere in the app
dispatch(new ProcessInvoice($invoice));

The job class itself stays clean:

class ProcessInvoice implements ShouldQueue
{
    use Queueable;

    public function __construct(
        public readonly Invoice $invoice,
    ) {}

    public function handle(): void
    {
        // just business logic here
    }
}

No $queue. No $connection. No infrastructure noise at the top of a class that's supposed to be about billing logic.

Laravel also ships an array shorthand for batch registration:

Queue::route([
    ProcessInvoice::class   => ['billing', 'sqs'],  // queue + connection
    SendWelcomeEmail::class => 'emails',             // queue only, default connection
    GenerateReport::class   => ['heavy', 'redis'],
]);

Both styles work. I prefer the per-line approach because it's easier to diff in code review, but the array syntax is useful when your service provider is getting long.

The Actually Clever Part: Interface and Trait Routing

Routing individual job classes is useful. But routing by interface is where the feature gets genuinely powerful, especially as your app grows.

Say you have a dozen jobs that all belong to your billing system: ProcessInvoice, RefundPayment, ChargeSubscription, GenerateReceipt, and so on. You could register each one individually. But you'd have to update AppServiceProvider every time a new billing job is added. That's the same maintenance overhead you were trying to escape.

Instead, create a marker interface:

namespace App\Contracts;

interface BillingJob {}

Implement it on every billing job:

class ProcessInvoice implements ShouldQueue, BillingJob
{
    use Queueable;
    // ...
}

class RefundPayment implements ShouldQueue, BillingJob
{
    use Queueable;
    // ...
}

class ChargeSubscription implements ShouldQueue, BillingJob
{
    use Queueable;
    // ...
}

Then register once:

Queue::route(BillingJob::class, connection: 'sqs', queue: 'billing');

Any job that implements BillingJob automatically routes to billing/SQS. Add a new billing job tomorrow, implement the interface, and it's routed correctly. No service provider changes needed.

The same pattern works with parent classes if you prefer inheritance over interfaces:

abstract class BillingJob implements ShouldQueue
{
    use Queueable;
}

class ProcessInvoice extends BillingJob {}
class RefundPayment extends BillingJob {}

And with traits if you prefer composition:

trait IsBillingJob {}

Queue::route(IsBillingJob::class, connection: 'sqs', queue: 'billing');

Pick whichever fits how you already organize your jobs. The routing resolution works the same way regardless of whether you pass a concrete class, an interface, a trait, or a parent class.

One thing worth understanding about precedence: a direct class registration always wins over an interface match. So if you route BillingJob to billing/sqs, but then add a specific route for ProcessInvoice pointing to billing-priority/sqs, the more specific rule wins for that one class while everything else continues using the interface route. Specific beats general. That's the behaviour you'd expect.

A Visual: How Dispatch Resolution Works

Here's the full picture of what happens after you've set up Queue::route():

flowchart LR
    A[ProcessInvoice::dispatch] --> R{Queue::route resolver}
    B[RefundPayment::dispatch] --> R
    C[SendWelcomeEmail::dispatch] --> S{Queue::route resolver}
    D[GenerateReport::dispatch] --> T{Queue::route resolver}
    R --> F[billing queue / SQS]
    S --> G[emails queue / default]
    T --> H[heavy queue / Redis]

Every dispatch passes through the resolver. The resolver checks the job class against registered routes, then any interfaces, traits, and parent classes. First match wins. If nothing matches, the job falls through to the default queue for the connection, exactly as before.

Your dispatch call sites stay clean regardless of where in the app they live.

A Real Before and After

Here's what a typical app with three queues looks like before this change. Four dispatches, four different patterns:

// InvoiceController.php
ProcessInvoice::dispatch($invoice)
    ->onQueue('billing')
    ->onConnection('sqs');

// RefundController.php: someone forgot onConnection, wrong connection in production
RefundPayment::dispatch($refund)->onQueue('billing');

// SendWelcomeEmail.php: hardcoded property on the job class
class SendWelcomeEmail implements ShouldQueue
{
    public string $queue = 'emails';
}

// ReportCommand.php: no routing at all, silently falls to default queue
GenerateReport::dispatch($report);

After the refactor, AppServiceProvider is the single source of truth:

public function boot(): void
{
    Queue::route(BillingJob::class, connection: 'sqs', queue: 'billing');
    Queue::route(SendWelcomeEmail::class, queue: 'emails');
    Queue::route(GenerateReport::class, queue: 'heavy');
}

Every dispatch site becomes the same clean call:

ProcessInvoice::dispatch($invoice);
RefundPayment::dispatch($refund);
SendWelcomeEmail::dispatch($user);
GenerateReport::dispatch($report);

The RefundPayment connection bug is gone. The silent GenerateReport routing issue is fixed. And anyone reading the codebase knows exactly where to look for queue config.

Migrating an Existing App

If you're upgrading to Laravel 13, this refactor pairs well with the upgrade itself. My Laravel 12 to 13 upgrade guide covers the upgrade process; this refactor can slot in right after or during.

Start by finding every $queue and $connection property across your job classes:

grep -rn 'public string \$queue\|public string \$connection' app/Jobs/

Then find every dispatch call with explicit routing:

grep -rn 'onQueue\|onConnection' app/

For each job you find, register a route in AppServiceProvider, remove the property from the class, and clean up the dispatch call. Run your test suite after each one. Don't try to do them all at once.

One important point: Queue::route() takes precedence over class properties if both exist. So you can register the route first, confirm it works in staging, and then clean up the property in a second commit. You're never in a state where the class property silently overrides your new central config during the transition.

One thing I'd also recommend doing during the migration: group your jobs by concern before writing the routes. Look for natural clusters: billing jobs, email jobs, media processing jobs, AI jobs. If you have a natural grouping, that's a sign you should probably use interface-based routing for the whole group rather than registering each class individually. Taking ten minutes to plan this before writing any code will save you a much longer conversation when the team wants to move a whole category of jobs to a new connection.

For a deep dive into how workers actually pick up named queues, set priorities, and handle Supervisor config, the post on processing 10,000 queue jobs without breaking covers all of that in detail. Worth reading alongside this refactor if your worker config is also a mess.

When ->onQueue() Still Makes Sense

Queue::route() sets the default for a job class. You can still override it at the dispatch site. The feature doesn't remove any flexibility. It just changes what happens when you don't specify.

This matters for priority overrides. Say you route most invoices to the billing queue, but premium customers need to jump ahead of the line:

// Standard dispatch: goes to billing via Queue::route()
ProcessInvoice::dispatch($invoice);

// Premium customer: override to fast-track queue
if ($customer->isPremium()) {
    ProcessInvoice::dispatch($invoice)->onQueue('billing-priority');
}

The central default handles 99% of cases. Edge cases get explicit overrides at the dispatch site. Clean split between the rule and the exception.

Trade-offs Worth Being Honest About

It's only in Laravel 13+. If you're on Laravel 12, you can't use this. That's also a reasonable push to upgrade. Not because 12 is insecure (it gets security fixes until February 2027), but because the quality-of-life improvements add up. PHP Attributes for models, jobs, and commands. Cache::touch(). This. They're individually small. Together they make day-to-day work cleaner. The PHP Attributes post covers that side of the release if you want the full picture.

Discoverability moves to the service provider. A developer reading ProcessInvoice.php won't see which queue it uses without also knowing to check AppServiceProvider. If your team values job classes being fully self-documenting about their infrastructure setup, that's a real trade-off worth discussing. My take: infrastructure config shouldn't live on the class. The same argument came up when RateLimiter::for() shipped, and nobody complains about that pattern now. Centralization is the right call.

Test assertions still work, but for different reasons. If you have tests using Queue::assertPushedOn('billing', ProcessInvoice::class), those tests will still pass after the migration. But now they pass because of Queue::route() rather than an explicit ->onQueue() chain. That's actually more correct behavior. But it can be briefly confusing during migration if a previously-failing test suddenly passes. It's not a bug. It's the feature working as intended.

FAQ

Does Queue::route() work with Horizon?

Yes. Horizon reads queue names when picking up jobs. Queue::route() resolves before the job hits the queue, so Horizon sees the job on the correct named queue. Your Horizon config still controls worker counts and priorities per queue. Nothing about that changes.

What happens if I dispatch a job with no registered route and no class property?

It falls back to the default queue for the connection, exactly as before. Queue::route() is purely additive. Existing behavior doesn't break.

Does this work with batched and chained jobs?

For batched jobs, yes. Each job in a batch resolves its route independently through Queue::route(). For chained jobs, it depends on how the chain is configured. If you dispatch a chain with an explicit ->onQueue() or ->onConnection() at the chain level, those values take precedence over registered routes for all jobs in the chain, since chain-level queue settings apply to all jobs unless individually overridden. If no queue is specified at the chain level, Queue::route() resolves as normal for each job. Bottom line: test chain behavior in your specific setup before relying on it.

Can I use Queue::route() and still override at the dispatch site?

Yes. ->onQueue() and ->onConnection() at the dispatch site always override a registered route. The route is just the default when nothing is specified explicitly.

Does this work with mailables and notifications that implement ShouldQueue?

No. Queue::route() applies to job classes specifically. Mailables and notifications use their own onQueue() method and aren't affected by this feature.

What if a job matches multiple interface routes?

Direct class registrations win over interface registrations. Among interfaces, the first matching route wins. Design your interfaces so a job only ever matches one route. It keeps things predictable and avoids the kind of subtle ordering dependency that bites you six months later.

Conclusion

Queue::route() isn't flashy. It won't make it into any conference keynote highlight reel. But it's the kind of feature you notice every single day once you're using it: one file, one place to look, no surprises about where a job ends up.

Queue topology is infrastructure config. It belongs in AppServiceProvider next to rate limiters and model bindings. Not embedded in job classes and not repeated at every dispatch call site. If you're on Laravel 13 and have more than two queues, this refactor is worth an hour of your time this week. It's exactly the kind of thing that prevents the "wait, which queue does this job actually go to?" conversation at 2am when something's backing up.

The pattern also makes you think more clearly about your queue topology in general. When everything is in one file, you can see at a glance whether your infrastructure matches your mental model. Gaps become obvious. Misconfigurations stand out. It's a small change with a surprisingly large effect on how well the team understands the system.

Claude Code Channels: How to Control Your AI Agent from Your Phone

Hafiz — Mon, 23 Mar 2026 09:03:50 +0000

You kick off a big database migration on staging, get up to make coffee, and come back 45 minutes later. Claude hit a permission prompt 3 minutes in. Everything's been frozen since then. You had no idea.

That's the specific problem Claude Code Channels fixes.

Shipped on March 20, 2026 as a research preview, Channels is a feature that turns your running Claude Code session into something you can message from anywhere. Fire off a task before a meeting. Check in from your phone. Get a reply in Telegram when it's done. Your laptop stays open, your session stays alive, and you're not chained to the terminal waiting for output.

This isn't a tutorial about what Channels is. If you want that, the official docs cover it fine. This is about what you actually do with it inside a real Laravel project. The setup takes 5 minutes. The workflows take longer to figure out on your own, so I'm going to save you the trial and error.

What Channels Actually Is (The Short Version)

A Channel is an MCP server that runs locally alongside your Claude Code session. It acts as a bridge between an external messaging platform and your active terminal session.

The key word is "local." Your code never leaves your machine. When you send a message from Telegram, the plugin (running on your laptop) receives it and injects it directly into your open Claude Code session as an event. Claude processes it with full access to your filesystem, your MCP servers, your git history, everything. Then it replies back through the same channel.

Claude Code
Channels Message Flow

Your
Phone

Bot
API

polls

MCP
Plugin

event

Claude
Session

reads

Your
Codebase

One thing the docs are clear about: events only arrive while your session is open. Close the terminal and messages sent during that time are gone. They won't queue up and deliver later. So for anything you want to monitor while you're away, you need to keep Claude Code running in a tmux or screen session. More on this in a minute.

Getting Set Up (The Minimum You Need to Know)

Before you start: Channels requires Claude Code v2.1.80 or later, a claude.ai login (API key auth doesn't work), and the Bun runtime. Not Node. Bun. This trips up a lot of people. If you install the plugin and nothing happens, Bun is almost certainly the reason.

# Check your Claude Code version first
claude --version

# Install Bun if you don't have it
curl -fsSL https://bun.sh/install | bash

Once you're past that, the Telegram setup is three commands inside an active Claude Code session:

# Install the official plugin
/plugin install telegram@claude-plugins-official

# Save your BotFather token
/telegram:configure YOUR_BOT_TOKEN_HERE

Then exit and relaunch with the channels flag:

claude --channels plugin:telegram@claude-plugins-official

DM your bot on Telegram. It replies with a 6-character pairing code. Go back to your terminal:

/telegram:access pair YOUR_PAIRING_CODE

Done. You're connected. Send a message from Telegram and Claude responds in the chat.

One more thing to do immediately: lock down access.

/telegram:access policy allowlist

By default, anyone who messages your bot gets a pairing code reply. That's fine for testing, but you don't want strangers trying to pair with your session. Run the allowlist command before you forget.

Now. Let's talk about what you actually use this for.

Scenario 1: Long-Running Artisan Commands

The migration scenario from the intro is the most common pain point. You're running something that takes time and needs a yes/no at some point in the middle. A data import. A multi-step migration. A batch reprocessing job on a large table.

With Channels, the workflow looks like this. You kick off the command and tell Claude what to expect:

You: Run the import:customers artisan command against the staging database.
    It'll ask for confirmation before it starts writing. Wait for my approval
    before you proceed.

Then you walk away. When Claude hits the confirmation step, it messages you in Telegram:

Claude: The import is ready to begin. It found 14,832 customer records 
to process. The command is asking for confirmation before writing. 
Should I proceed? (yes/no)

You reply "yes" from your phone. Claude approves the prompt in the terminal and the import runs.

This works for any scenario where you want a human checkpoint in the middle of a longer task. Migrations against production data. Seed scripts that drop and recreate tables. Any --force command you want to consciously approve rather than just automate past.

Scenario 2: Queue Failures While You're Not at Your Desk

If you're running a Laravel app with queued jobs, you already know the late-night failed job routine. Horizon shows something red. You get an email. You sigh and open the laptop.

Laravel Queue Jobs: Processing 10,000 Tasks Without Breaking covers the architecture side well. Channels adds the response layer.

Keep Claude Code running in a tmux session on your development machine with your project loaded:

tmux new-session -d -s claude-session
tmux send-keys -t claude-session \
  'cd ~/clients/myapp && claude --channels plugin:telegram@claude-plugins-official --dangerously-skip-permissions' Enter

Now from your phone, whenever something looks off:

You: Check the failed jobs in Horizon. What's failing and why?

Claude reads the failed job records, checks the exception messages, looks at the relevant code, and replies:

Claude: 3 jobs failed in the last hour. All are ProcessInvoicePdf jobs.
The exception is: Unable to find class App\Services\PdfRenderer.
Looks like a namespace change that wasn't reflected in the job class.
The fix is a one-line update in ProcessInvoicePdf.php line 23.
Want me to fix it and restart the queue?

You reply "yes, fix it" from Telegram. Claude makes the change and tells you when it's done. No laptop needed.

The --dangerously-skip-permissions flag is doing real work here. Without it, every file write would pause and wait for terminal confirmation, which defeats the purpose when you're trying to resolve something remotely. I'll be honest about the trade-off: you're giving up the permission safety net. Only use this on machines and projects you trust, in environments where the blast radius of a bad action is acceptable.

Scenario 3: Client Bug Reports When You're Away from the Desk

This one happens constantly in client work. Someone messages you about a bug at 7pm. You're not at your computer. Before Channels, your options were: ignore it until morning, or open the laptop.

One thing to understand clearly before you rely on this scenario: three conditions must all be true at the same time. Your machine has to be on. Claude Code has to be running with --channels in a tmux session. And the right client project has to be loaded in that session. If you have two active clients, you need two named tmux sessions:

tmux new-session -s client-a   # client A project loaded here
tmux new-session -s client-b   # client B project loaded here

Each session runs Claude Code pointed at the right directory. When a bug comes in for client 1, you're messaging into the session that already has their codebase loaded. This is the setup that makes Scenario 3 actually work in practice.

With that in place, when a client reports a bug you forward it to Claude in Telegram:

You: Client just reported that the invoice filter on the dashboard isn't
    working. When they select "overdue" from the dropdown, it shows all
    invoices instead of filtering. Look at InvoiceController and the
    related Vue component and tell me what's wrong.

Claude reads both files, traces the issue, and comes back to you in the chat:

Claude: Found it. In InvoiceController@index, the 'overdue' case in the
switch statement is missing a break, so it falls through to the default
'all' query. The fix is adding `break;` on line 67. The Vue component
is fine. Want me to write the fix and a test for it?

You reply "yes, write the fix and test, but don't commit yet." Claude writes both. In the morning you sit down, review what it wrote, and either commit or adjust. The diagnosis work is already done. Half the problem is solved before you've touched the keyboard.

This is where Channels starts to feel less like a tool and more like having a developer you can text. You're not directing every step. You're checking in, approving things, and staying informed without being present.

Scenario 4: Kicking Off Feature Work Before You Step Away

This one pairs well with the Ralph Wiggum Technique and git worktrees approach.

Start a well-scoped task before you leave for lunch or a meeting. Give Claude a clear spec via Telegram, with the project already loaded in the session:

You: Build the notification preferences page. Users should be able to toggle
    email notifications on/off for: new invoice, payment received, invoice
    overdue. Save preferences to user_notification_preferences table (create
    the migration). Vue component in resources/js/Pages/Settings/Notifications.vue.
    Use the existing NotificationService. Don't build the actual email sending,
    just the preferences UI and storage.

Claude starts working. The Telegram typing indicator shows it's active. When it finishes (or hits something it needs to ask about), it messages you:

Claude: Done. Here's what I built:
- Migration: create_user_notification_preferences_table
- Model: UserNotificationPreference with fillable and relationship on User
- Controller: NotificationPreferenceController (store/update)
- Route: PATCH /settings/notifications
- Vue component: Notifications.vue with three toggles, auto-saves on change
- I didn't find NotificationService in your app, so I left a TODO comment
  where it should be called. Can you point me to the right file?

You clarify. It continues. Back and forth over Telegram, no laptop open.

The MCP server setup matters a lot here. The more context Claude has about your project conventions and codebase, the less you have to explain in each Telegram message. Get your MCP configuration right first and these remote sessions become much more productive.

The Session-Open Requirement and tmux

One thing to understand clearly: Channels is not a cloud service. Claude Code isn't running somewhere persistent on Anthropic's servers waiting for your messages. It's running on your machine. Close the terminal, and it's gone.

For workflows where you want to kick something off and check in later, you need to keep the session alive. tmux is the standard solution:

# Start a persistent session
tmux new-session -s claude

# Later, reattach from any terminal
tmux attach -t claude

# Or check what's running
tmux ls

Start Claude Code inside the tmux session with the channels flag, and it'll keep running even if you close your terminal window. The session persists until your machine restarts or you explicitly kill it.

One thing that still requires the terminal: permission prompts. If you're not using --dangerously-skip-permissions and Claude hits a prompt it needs answered, the session pauses. You can't approve it from Telegram. You have to get back to the terminal. This is a known limitation during the research preview, and based on the docs it sounds like remote permission approval is on the roadmap.

What Channels Isn't

Worth being honest about the current state. This is a research preview. A few things that don't work yet or have rough edges:

No message history. The Telegram Bot API doesn't expose message history. If Claude replies while your phone has no signal, the message is gone. You won't see it when you reconnect.

Only Anthropic-whitelisted plugins for now. During the preview, --channels only accepts plugins from claude-plugins-official. If you want to build a custom Slack channel or a webhook bridge for something like Forge deploy notifications, you need the --dangerously-load-development-channels flag, which disables the allowlist entirely.

Availability is still rolling out. Some accounts don't have it yet even after updating. If the --channels flag doesn't register anything on startup, you may just not have access yet.

If you were using OpenClaw on Forge before, Channels covers most of the same ground with better first-party support. OpenClaw still has an edge on platform breadth (iMessage, WhatsApp, Slack), but for Telegram and Discord use cases, Channels is the cleaner option.

FAQ

Do I need a special Claude plan to use Channels?

You need a claude.ai login. It works on Pro, Max, Team, and Enterprise plans. Console and API key authentication aren't supported. Team and Enterprise orgs also need an admin to enable it in managed settings before individual setup works.

Can I use Discord instead of Telegram?

Yes. The setup is slightly more involved (you need to create a bot in the Discord Developer Portal and enable Message Content Intent under Privileged Gateway Intents), but the workflow is the same. Run /plugin install discord@claude-plugins-official and /discord:configure YOUR_TOKEN in your Claude Code session, then relaunch with --channels plugin:discord@claude-plugins-official.

Is it safe to use --dangerously-skip-permissions?

It depends entirely on your environment. On a local dev machine with a project you fully control, it's fine. On a machine with production database credentials and live API keys, think carefully. The flag removes all permission checkpoints. If Claude misinterprets an instruction, it'll execute without asking. Use it where the blast radius of a mistake is acceptable.

What happens to messages I send when Claude Code isn't running?

They're lost. The channel plugin runs locally and only polls while Claude Code is active. If the session is closed, no one's listening. This is why tmux matters for always-on setups.

Can I run multiple channel plugins at the same time?

Yes. Space-separate them in the --channels flag: claude --channels plugin:telegram@claude-plugins-official plugin:discord@claude-plugins-official. Both channels will be active in the same session.

The Shift That Actually Matters

The practical change here is smaller than the hype suggests, but it's real. You go from "I have to be at my terminal to do anything with Claude" to "I can start something, step away, and stay in the loop from wherever I am."

For client work especially, that's meaningful. A bug comes in at 7pm. You don't have to choose between ignoring it and sitting back down at your desk. You fire off the investigation from your phone and handle it on your own schedule.

Set up tmux, get the Bun requirement sorted first, and lock down your allowlist before you share your bot token anywhere. The rest is just workflow.

How to Build a Laravel MCP Server with Filament

Hafiz — Sat, 21 Mar 2026 09:06:25 +0000

If you've been using Claude Code or Cursor on a Filament project, you already know the frustration. You ask the agent to add a filter to your OrderResource, and it invents a column that doesn't exist. You ask it to fix a relationship display issue, and it writes code for the wrong Filament version. The agent isn't bad. It just has no idea what's actually inside your app.

That's the exact problem Laravel MCP solves. Instead of an agent guessing at your schema from vague documentation references or grep results, it queries a server you control. You define exactly what it can see. You decide what gets exposed, what stays private, and how the data is shaped before the agent ever touches it.

In this tutorial I'm going to walk through building a practical Laravel MCP server specifically for a Filament admin. The examples use an e-commerce order management setup because it's concrete and easy to follow, but the patterns apply directly to any Filament project regardless of domain. We'll create tools that expose your Eloquent data with filters, a resource that gives agents a map of your admin panel structure, and wire everything up for both local development and remote HTTP access.

If you're new to MCP in Laravel, read my earlier post on Laravel Boost and MCP servers first. This tutorial assumes you know what MCP is and why it matters. We're going straight to the implementation.

Why Filament Projects Specifically Need This

Most MCP tutorials stop at exposing raw database tables. That's useful, but it misses a big chunk of what Filament apps actually need. When you're working in a Filament project, your domain logic is split between Eloquent models and Filament Resources. The resources define how data is filtered, how forms are structured, which columns are displayed, and how permissions work. None of that lives in the database schema.

An AI agent that only has database access can tell you what columns exist. It can't tell you which OrderResource pages are registered, what the create form looks like, or how your custom widgets pull data. That's the gap a Filament-aware MCP server fills. You're giving the agent structured access to both layers, the data and the admin layer on top of it.

The second reason is practical: Filament apps tend to be complex. Multi-panel setups, custom pages, resource relations, polymorphic relationships. The more complex your app, the more the agent needs structured context rather than broad guessing. A one-hour investment in MCP setup pays back consistently across every dev session after it.

Prerequisites

You'll need:

Laravel 12 or 13 (the laravel/mcp package doesn't support earlier versions)
A running Filament v3+ installation
PHP 8.2 or higher

If you're starting fresh with Filament, check out this guide on building admin dashboards with Filament before continuing. It covers panel setup and resource structure in detail.

Installing Laravel MCP

Start with a single Composer command:

composer require laravel/mcp

Then publish the routes file:

php artisan vendor:publish --tag=ai-routes

This creates routes/ai.php. Think of it as routes/api.php but for AI clients. You'll register your MCP servers here, control which middleware runs on each one, and decide which servers are local (stdio-based) vs. web (HTTP-based). You can mix both in the same file.

Creating the Filament Server

Run the generator:

php artisan make:mcp-server FilamentAdminServer

You'll find the new class at app/Mcp/Servers/FilamentAdminServer.php. The PHP attributes on the class matter more than most people realise. The #[Instructions] attribute is literally the first thing the AI model reads about this server. It uses it to decide whether to query this server at all, so vague instructions produce vague agent behavior.

<?php

namespace App\Mcp\Servers;

use Laravel\Mcp\Server\Attributes\Instructions;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Version;
use Laravel\Mcp\Server;

#[Name('Filament Admin Server')]
#[Version('1.0.0')]
#[Instructions('Provides AI agents with structured access to this application\'s Filament admin resources, Eloquent data, and panel navigation. Use this server when you need to inspect or query application data, understand the resource structure, or generate code that interacts with Filament resources.')]
class FilamentAdminServer extends Server
{
    protected array $tools = [];
    protected array $resources = [];
    protected array $prompts = [];
}

"Provides access to data" tells the agent nothing. "Provides structured access to Filament admin resources, Eloquent data, and panel navigation" tells it exactly when to reach for this server. The more precise you are here, the fewer times you'll have to manually prompt the agent to use the right tool.

Building Your First Tool: List Records

The most immediately useful tool for a Filament app is one that lets the agent query actual data with business-logic filters, not raw SQL. Let's build ListOrdersTool.

php artisan make:mcp-tool ListOrdersTool

Here's the full implementation:

<?php

namespace App\Mcp\Tools;

use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tool;

#[Description('Lists orders from the database. Supports filtering by status and limiting results. Returns order ID, reference, status, total, and customer name.')]
#[IsReadOnly]
class ListOrdersTool extends Tool
{
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'status' => 'nullable|string|in:pending,processing,completed,cancelled',
            'limit'  => 'nullable|integer|min:1|max:50',
        ], [
            'status.in'  => 'Status must be one of: pending, processing, completed, cancelled.',
            'limit.max'  => 'Limit cannot exceed 50 records.',
        ]);

        $orders = Order::query()
            ->with('customer')
            ->when(!empty($validated['status']), fn ($q) => $q->where('status', $validated['status']))
            ->latest()
            ->limit($validated['limit'] ?? 10)
            ->get();

        return Response::structured(
            $orders->map(fn ($order) => [
                'id'            => $order->id,
                'reference'     => $order->reference,
                'status'        => $order->status,
                'total'         => $order->total,
                'customer_name' => $order->customer?->name,
                'created_at'    => $order->created_at->toDateTimeString(),
            ])->toArray()
        );
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'status' => $schema->string()
                ->enum(['pending', 'processing', 'completed', 'cancelled'])
                ->description('Filter orders by status. Omit to return all statuses.'),

            'limit' => $schema->integer()
                ->description('Number of records to return. Defaults to 10, max 50.')
                ->default(10),
        ];
    }
}

Three decisions here worth explaining. First, Response::structured() returns a proper JSON object the AI client can parse and reason about, not just a text blob. When you return plain text, the agent has to interpret natural language. When you return structured data, it can reliably extract the id or status and use them in the next step. Second, #[IsReadOnly] tells the client this tool won't modify any state, so it can be called freely without requesting confirmation. Third, the validation error messages are written for the AI, not for a human form. They're specific and tell the agent exactly what to fix.

Register it in your server's $tools array before moving on. The pattern here, validate inputs clearly, query with explicit field selection, return structured output, is the same pattern you'll follow for every tool you add. Once you've built two or three, each new one takes about ten minutes.

Building a Deeper Tool: Get a Single Record

A list tool is a good start, but agents often need to inspect one record in full detail before writing code that touches it. Without this, the agent calls your list tool, gets back a summary, and then has to guess what relationships and fields are available on the full record. That's where hallucinations creep back in.

php artisan make:mcp-tool GetOrderTool

<?php

namespace App\Mcp\Tools;

use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tool;

#[Description('Retrieves a single order with full details including line items, customer, and status history.')]
#[IsReadOnly]
class GetOrderTool extends Tool
{
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'id' => 'required|integer|exists:orders,id',
        ], [
            'id.required' => 'You must provide an order ID.',
            'id.exists'   => 'No order found with that ID. Use the list-orders tool first to find valid IDs.',
        ]);

        $order = Order::with(['customer', 'items.product', 'statusHistory'])
            ->findOrFail($validated['id']);

        return Response::structured([
            'id'        => $order->id,
            'reference' => $order->reference,
            'status'    => $order->status,
            'total'     => $order->total,
            'customer'  => [
                'id'    => $order->customer?->id,
                'name'  => $order->customer?->name,
                'email' => $order->customer?->email,
            ],
            'items' => $order->items->map(fn ($item) => [
                'product_name' => $item->product?->name,
                'quantity'     => $item->quantity,
                'unit_price'   => $item->unit_price,
            ])->toArray(),
            'created_at' => $order->created_at->toDateTimeString(),
        ]);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'id' => $schema->integer()
                ->description('The database ID of the order to retrieve.')
                ->required(),
        ];
    }
}

The id.exists validation message tells the agent exactly what to do next. That's a pattern worth following across every tool you build. Good MCP validation errors guide the agent's next action. They don't just report failure and leave it stuck.

Add both tools to your server:

protected array $tools = [
    ListOrdersTool::class,
    GetOrderTool::class,
];

Adding a Resource: Expose Your Filament Navigation

Tools handle queries. Resources handle context. There's a real difference. A tool runs on demand and returns fresh data from a specific request. A resource is something the agent reads once to orient itself, like a map of your application. It answers questions like: what resources exist, what models do they manage, and what are the correct admin URLs?

This is the thing that prevents the agent from inventing route names or misidentifying which Resource class handles which model. Without it, the agent has to grep your codebase and hope it finds everything.

php artisan make:mcp-resource FilamentNavigationResource

<?php

namespace App\Mcp\Resources;

use Filament\Facades\Filament;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Attributes\MimeType;
use Laravel\Mcp\Server\Attributes\Uri;
use Laravel\Mcp\Server\Resource;

#[Description('Lists all registered Filament resources, the Eloquent models they manage, and their admin panel index URLs.')]
#[Uri('filament://resources/navigation')]
#[MimeType('application/json')]
class FilamentNavigationResource extends Resource
{
    public function handle(Request $request): Response
    {
        // Adjust 'admin' to match your panel ID if it's different
        $panel = Filament::getPanel('admin');

        $resources = collect($panel->getResources())
            ->map(fn ($resourceClass) => [
                'class'        => $resourceClass,
                'model'        => $resourceClass::getModel(),
                'plural_label' => $resourceClass::getPluralModelLabel(),
                'index_url'    => $resourceClass::getUrl('index'),
            ])
            ->values()
            ->toArray();

        return Response::structured([
            'panel_id'  => $panel->getId(),
            'resources' => $resources,
        ]);
    }
}

Register it in your server's $resources array. When Claude Code reads this resource at the start of a session, it knows the exact class name for every resource in your admin, which model each one manages, and the correct index URL. That's a concrete, useful context dump. Compare that to an agent starting cold with no information, and the difference in code quality is noticeable immediately.

Registering the Server

Open routes/ai.php. You have two options.

For Claude Code or Cursor running locally, use local. The server runs as a subprocess your MCP client starts over stdio:

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

Mcp::local('filament-admin', FilamentAdminServer::class);

For remote HTTP clients (a web-based AI assistant, an external agent, anything outside your local machine), use web with authentication middleware:

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

Both can live in the same file simultaneously. Here's how the full flow looks once everything is connected:

flowchart TD
    A[Claude Code / Cursor] -->|calls tool or reads resource| B[FilamentAdminServer]
    B --> C{Request type}
    C -->|ListOrdersTool| D[Eloquent query with filters]
    C -->|GetOrderTool| E[findOrFail with relations]
    C -->|FilamentNavigationResource| F[Filament panel + resources]
    D --> G[Response::structured]
    E --> G
    F --> G
    G --> A

Testing with the MCP Inspector

Before connecting a real client, use the built-in inspector to verify everything works. For a local server:

php artisan mcp:start filament-admin --inspector

The inspector gives you a browser UI to call each tool manually and inspect the raw JSON responses. It's the quickest way to catch a missing eager load, a validation rule mismatch, or a Filament API method that doesn't exist in your version, before they cause confusion in a real agent session.

When your tool returns data, paste it into a JSON formatter to inspect the structure clearly before you commit to it as the tool's output contract. Changing the response shape later forces you to update any agent workflows that already depend on it.

Security: What Not to Skip

A few things to get right before any of this goes beyond local dev.

Gate write tools with shouldRegister. Any tool that creates, updates, or deletes data should check permissions before it appears in the tool list at all:

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

When shouldRegister returns false, the tool doesn't appear in the available tools list. The agent can't call what it can't see. That's much better than returning an auth error after the fact, because it gives the agent an accurate picture of what it can actually do.

Use Sanctum for web servers. The auth:sanctum middleware on your Mcp::web() registration means clients need a valid token. Issue tokens with short expiry for AI integrations, same as you would for any external API client. Don't reuse tokens across different agents or sessions.

Never return raw Eloquent models. Always explicitly select the fields you're exposing. The field mappings in the tools above are intentional, not lazy. You don't want the agent accidentally receiving password hashes, internal flags, or anything else sitting on the model that shouldn't leave the server.

When to Build a Custom Server vs. Just Using Boost

If you're doing local development with Claude Code, Laravel Boost already gives the agent schema inspection, log reading, and Tinker access out of the box. You don't need a custom MCP server for those things. Don't duplicate what Boost already does well.

Build a custom server when you need business-logic-aware queries the agent can call on demand, not just raw schema access. When you're connecting a non-developer AI client. When you need fine-grained control over data visibility. Or specifically when you're working with Filament's resource and panel structure, which Boost knows nothing about.

They're not mutually exclusive. A mature Filament project will often use both. And if you're building AI features into the app itself rather than just using AI for development, you'll want to look at the Laravel AI SDK alongside this.

Frequently Asked Questions

Does this work with Filament v3 and v4?

Yes. The MCP server doesn't depend on a specific Filament version. FilamentNavigationResource uses Filament::getPanel() and $panel->getResources(), both available in v3 and v4. On Filament v5, verify the Facades API because some method signatures changed between major versions.

Can I expose Filament form schemas as a resource?

You can, but it's rarely worth the effort. Filament form schemas are PHP class structures. Turning them into JSON via reflection is messy and the agent rarely needs that level of detail for code generation tasks. Model data and resource navigation cover 90% of what agents actually ask for.

What's the difference between Mcp::local() and Mcp::web()?

local servers run as a subprocess started by your MCP client (like Claude Code) over stdio. web servers run as HTTP endpoints, suitable for any MCP-compatible client that can make POST requests. For day-to-day development, local is simpler. For production deployments where multiple external clients need access, web is the right choice.

Should I cache tool responses?

For read-heavy tools, yes. Wrap your Eloquent query in Cache::remember() with a short TTL. 30 to 60 seconds works well for most cases. Agents often call the same tool multiple times in one session, and caching stops you from hammering the database with identical queries. Don't cache anything that changes frequently or carries sensitive state.

Can I conditionally register tools based on which Filament panel is active?

Yes. Inside shouldRegister, check Filament::getCurrentPanel()?->getId() and return false if the active panel doesn't match. This is useful in multi-panel setups where you want a clean separation of what each AI client can access based on which panel they've authenticated against.

Conclusion

Laravel MCP turns your Filament admin from a codebase AI agents have to guess about into one they can actually query. A handful of well-designed tools give any MCP-compatible client real access to your data, your resource structure, and your business logic. No hallucinated columns. No invented route names. No code written for a Filament version you're not running.

The setup takes less than an hour on an existing Filament project, and the improvement in agent output quality is immediate. If you're already making your Laravel app AI-agent friendly, this is the natural next step specifically for Filament.

Laravel 12 to 13 Upgrade Guide: Zero Breaking Changes Doesn't Mean Zero Work

Hafiz — Thu, 19 Mar 2026 06:58:27 +0000

Laravel 13 dropped on March 17. The official messaging is "zero breaking changes," and for most apps that's pretty close to the truth. But close isn't the same as zero. There are a handful of defaults that changed quietly, one PHP requirement that will block your upgrade entirely if you ignore it, and a new first-party tool that makes the whole process significantly faster. This guide covers all of it.

This isn't a feature tour. If you want before/after examples of PHP Attributes or Cache::touch(), I've already covered those. This post is only about the upgrade process itself, in the order that matters.

Why "Zero Breaking Changes" Isn't the Full Story

The phrase is technically accurate for application-level code. Your routes, controllers, Eloquent models, and business logic almost certainly don't need touching.

But "breaking changes" in the Laravel changelog only covers the framework itself. It doesn't cover your infrastructure, your .env defaults, or your third-party packages. That's where things can catch you off guard.

Specifically:

If your server runs PHP 8.2, your upgrade fails before it starts
If you've never explicitly set CACHE_PREFIX or SESSION_COOKIE in your .env, those values will silently change after the upgrade
If you reference pagination view names as strings anywhere in your codebase, those names changed
If you have custom cache store implementations, a new contract method is now required

None of these are application logic. All of them can quietly break a production app.

So when Laravel says smooth upgrade, they're right. But smooth still requires knowing what to look at. Let's go through it in the order that matters.

Step 1: PHP 8.3 First

This is the only hard blocker. Do not change your composer.json until this is sorted.

php -v

If you're on PHP 8.2 or earlier, you need to upgrade your server runtime before touching anything else. On Ubuntu/Debian with Ondrej's PPA:

sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install php8.3 php8.3-fpm php8.3-mbstring php8.3-xml php8.3-curl php8.3-mysql

Don't forget to update your Nginx or Apache config to point at the new FPM socket. And update composer.json's PHP constraint while you're there:

"php": "^8.3"

If you're on Forge or Vapor, it's a one-click PHP version switch in the server panel. If you're on a shared host still defaulting to PHP 8.1, that's the actual problem to solve first. Docker is a clean escape hatch here if you need runtime flexibility without touching production infrastructure directly.

Once you've confirmed php -v returns 8.3+, move to the next step.

Step 2: Pin Your .env Before Touching Composer

This is the step most upgrade guides skip. It's also the one most likely to cause silent, user-facing problems on deploy day.

Laravel 13 changed two default naming patterns for cache and session:

Cache and Redis key prefixes now use hyphenated suffixes. The generated default changed from myapp_cache_ to myapp-cache-.

Session cookie names now use Str::snake() instead of Str::slug() with underscores.

Here's the critical part: this only affects apps that have never explicitly configured these values. If your config/cache.php and config/session.php already reference .env variables that you've set explicitly, nothing changes for you.

But if you're relying on framework-generated fallback values (more common than you'd think, especially on apps that were scaffolded quickly), every active user session will be invalidated the moment you deploy. Their cookie won't match the new session cookie name. And your cached data becomes unreachable because the key prefix changed.

Fix this before running the upgrade. Check what your app is currently generating:

php artisan tinker
>>> config('cache.prefix')
>>> config('session.cookie')

Then pin those exact current values in your .env:

CACHE_PREFIX=myapp_cache_
REDIS_PREFIX=myapp_cache_
SESSION_COOKIE=myapp_session

Once they're explicitly set, the change in framework defaults becomes irrelevant. Your app keeps using whatever you've defined, regardless of what the framework generates as a fallback.

This two-minute step prevents a lot of pain.

Step 3: The Composer Update

With PHP sorted and .env pinned, the actual upgrade is a single command:

composer update laravel/framework --with-all-dependencies

The --with-all-dependencies flag matters. Without it, transitive dependencies can stay on older versions and cause conflicts that are annoying to debug. Use it.

Not sure what's blocking you before you run it? Check first:

composer why-not laravel/framework:^13.0

This tells you exactly which packages don't support Laravel 13 yet. For most major packages (Filament, Livewire, Inertia, Spatie) support landed on or shortly after March 17. But some smaller packages might need a day or two to catch up, and it's better to know that before you're halfway through an upgrade on a branch.

If a package you rely on isn't compatible yet, you've got two options: wait for the maintainer to tag a new release, or hold the upgrade until then. Don't force it. A "^12.0|^13.0" constraint in your own packages is the right pattern to use while the ecosystem catches up, but that's for packages you control.

After the update runs successfully:

php artisan optimize:clear
php artisan config:clear
php artisan cache:clear

Then run your test suite. Don't skip this step even if you're confident. The tests will catch the things this guide doesn't know about your specific app.

The Breaking Changes That Can Actually Bite You

The official upgrade guide documents a fair number of changes, but most of them only apply to edge cases. Here are the ones most likely to affect a real production application.

Cache Serialization Hardening

Laravel 13 adds a serializable_classes option to config/cache.php, defaulting to false. This is a security change. It prevents PHP deserialization gadget chain attacks if your APP_KEY ever leaks.

For most apps this has zero impact because you're caching arrays and scalar values. But if you're caching actual PHP objects (Eloquent model instances, DTOs, anything like that), you need to explicitly allow them:

'serializable_classes' => [
    App\Data\CachedDashboardStats::class,
    App\Support\CachedPricingSnapshot::class,
],

If you're unsure whether your app caches objects, search for Cache::put and Cache::remember calls and check what's being stored. Primitives and arrays are fine. Objects need to be on the list.

Pagination View Names

This one only bites you if you're passing pagination view names as strings anywhere directly. The names changed:

// Laravel 12
'pagination::default'
'pagination::simple-default'

// Laravel 13
'pagination::bootstrap-3'
'pagination::simple-bootstrap-3'

If you use $results->links() with no arguments, nothing changes. But if you have anything like $results->links('pagination::default') hardcoded somewhere, update those strings.

MySQL DELETE with JOIN

If your app has query builder calls that combine DELETE, JOIN, and either ORDER BY or LIMIT, the generated SQL changed. In previous versions the ORDER BY and LIMIT clauses were silently ignored on joined deletes. Laravel 13 includes them, which can throw a QueryException on MySQL/MariaDB setups that don't support this syntax combination.

Run a quick search:

grep -r "->join(" app/ --include="*.php" | grep -v ".test."

Then check whether any of those query chains also call ->delete(). It's probably rare in your codebase. But it's worth 30 seconds to verify.

Custom Contract Implementations

If you've built a custom cache store driver, the Illuminate\Contracts\Cache\Store contract now requires a touch method. A few other contracts also gained new methods. If you don't maintain any custom framework interface implementations, skip this. If you do, check the official upgrade guide for the complete list.

The Fast Path: Laravel Boost and /upgrade-laravel-v13

If you already have Laravel Boost configured with your AI editor, there's a dedicated slash command worth knowing about:

/upgrade-laravel-v13

Run it in Claude Code, Cursor, OpenCode, or VS Code. Boost is a first-party Laravel MCP server, and this command gives your AI assistant a guided upgrade prompt that knows the official breaking change documentation. It scans your codebase for patterns that match the documented changes and flags them.

It won't upgrade PHP for you. It won't fix the .env defaults issue (that's environment-level, not code-level). But for the contract changes, event listener signature updates, and model boot method issues, it does the scan automatically instead of you manually grep-ing through a large codebase.

Think of it as an automated first pass that catches the obscure stuff. You still do a final review, but it does the heavy lifting.

What to Adopt Now vs What to Skip

Upgrading to Laravel 13 and adopting its new features are two separate decisions. Don't conflate them.

After the upgrade, just make sure everything still works. That's the only goal for day one.

Once that's confirmed, here's how I'd think about the new features:

Cache::touch() is a quick win. If your app extends cache TTLs anywhere (rate limiting, user session renewal, anything like that), you're currently doing a get + put round trip. Cache::touch() collapses that into a single EXPIRE command on Redis. Low risk, tiny refactor, immediate improvement.

// Before: two round trips, full value transferred
$value = Cache::get('rate_limit_key');
Cache::put('rate_limit_key', $value, now()->addMinutes(10));

// After: single EXPIRE command, value never leaves the server
Cache::touch('rate_limit_key', now()->addMinutes(10));

PHP Attributes for models, jobs, and commands are optional. The old property-based syntax still works and there's no deprecation timeline. For a new project, start with Attributes. For an existing codebase, migrate gradually or not at all. There's no urgency.

The Reverb database driver (no Redis required for WebSockets) is promising. For smaller apps that don't want to provision Redis just for WebSocket scaling, this removes a real infrastructure dependency. I'd run benchmarks at your expected connection count before switching in production, but for a new real-time feature it's worth starting with the database driver.

Passkeys via Fortify are now built-in for new Laravel 13 installations. For existing apps it's still a migration project, not a one-liner. Good time to evaluate it for your next auth system refresh.

The AI SDK is stable. But read the stable release notes before dropping it into production. There were config changes between beta and stable that matter if you were running the beta.

FAQ

Do I need to upgrade now?

No. Laravel 12 receives bug fixes until August 2026 and security fixes until February 2027. If you're starting a new project today, use 13. If you're maintaining an active production app, plan it properly and upgrade when you have test coverage to back it up.

Will my packages break?

Run composer why-not laravel/framework:^13.0 before you start. This shows you exactly which packages are blocking the upgrade and what version they need to be at. Most major packages are already compatible.

Should I use Laravel Shift or do it manually?

Shift costs $29 per upgrade and handles around 80-90% of the mechanical changes. For large codebases the time savings justify the price. For smaller apps the manual approach in this guide covers everything. Your call.

What if I'm on Laravel 10 or 11?

You need to upgrade version by version: 10 to 11, then 11 to 12, then 12 to 13. You can't skip versions. Each major release has its own migration path and skipping them compounds the breaking changes significantly.

How long does this actually take?

Depends on your PHP version situation and how many of the edge cases apply to you. If you're already on PHP 8.3 and don't have custom contract implementations, the upgrade itself can be done in under an hour. The PHP upgrade on a production server is the wildcard.

Go Upgrade

Laravel 13 really is one of the smoothest major upgrades the framework has ever shipped. The "zero breaking changes" messaging isn't wrong. But smooth upgrades still require knowing which three or four things to check before you run composer update.

Pin your .env values first. Upgrade PHP before anything else. Run the Boost slash command if you have it. Then do the composer update and run your tests. That order matters.

How I Hardened My VPS in One Afternoon: SSH, Cloudflare, and Tailscale

Hafiz — Tue, 17 Mar 2026 07:35:24 +0000

A tweet from @levelsio went viral last week. The advice was simple: lock down your VPS before someone else does.

I checked my own server settings immediately. PermitRootLogin yes. PasswordAuthentication defaulting to enabled. Port 22 open to the entire internet. No Cloudflare proxy. Nothing.

That's fully exposed root SSH access on a production server running multiple live projects. Not great.

So I fixed all of it. SSH hardening, Cloudflare DNS migration, Tailscale installed, port 22 locked. Here's exactly what I did, in the order I did it, with the real commands and the mistakes I made along the way.

Why This Stack Specifically

There are a hundred ways to "secure" a server. Most guides tell you to do one thing. The levelsio setup is three independent layers working together:

SSH: key-based auth only, no passwords, no brute-force possible
Cloudflare: your real server IP stays hidden, all web traffic proxied
Tailscale: port 22 becomes invisible to the public internet

Each layer is useful on its own. Together they make your attack surface genuinely small. An attacker would need to break all three simultaneously to get anywhere.

Here's what the setup looks like once it's done:

flowchart LR
    A[Internet / Bots] -->|HTTPS only| B[Cloudflare]
    B -->|Proxied| C[Your VPS]
    D[Your Mac] -->|SSH via Tailscale| C
    A -.->|Port 22 invisible| C
    A -.->|Real IP hidden| B

The dashed lines are failed attacks. That's the goal.

Layer 1: SSH Hardening

Do this first. It's the most urgent fix and takes five minutes.

SSH into your server and check what you're working with:

grep -E "PermitRootLogin|PasswordAuthentication" /etc/ssh/sshd_config

If you see PermitRootLogin yes or nothing at all for PasswordAuthentication (which means it defaults to yes), you need to change both. Open the config file:

nano /etc/ssh/sshd_config

Change these two lines:

PermitRootLogin prohibit-password
PasswordAuthentication no

Save and restart SSH:

systemctl restart sshd

prohibit-password means root can still log in, but only with an SSH key. Since you're already using SSH keys, nothing changes for you day-to-day. What changes is that password brute-force attacks are now completely useless. Bots can hammer the port all they want.

One thing before you make this change: confirm you know where your private key file is (~/.ssh/id_rsa or ~/.ssh/id_ed25519 on Mac). And make sure your SSH key passphrase is strong. If it isn't, a password generator can help you create something that isn't guessable. If you ever do get locked out, DigitalOcean and Hetzner both have browser-based console access in their dashboards. That's your emergency backdoor and it bypasses SSH entirely.

Test your key auth works, apply the changes, test again. Don't just assume.

Layer 2: Put Cloudflare In Front of Your Server

If your domain's A record points directly at your server IP, that IP is public. Anyone can find it, target it, and bypass whatever you set up in Cloudflare later. The proxy only works if you actually use it.

Cloudflare free tier gives you:

Your real server IP hidden behind Cloudflare's network
DDoS protection at the application layer
Free SSL certificate management (no more certbot renewals)
CDN caching for static assets
Analytics at the infrastructure level

The migration causes zero downtime. Here's how it works.

Step 1: Create your Cloudflare account and add your domain

Go to cloudflare.com, sign up, then add your domain. Choose "Import DNS records automatically". Cloudflare scans your existing DNS and pulls everything in.

Step 2: Review the imported records carefully

Cloudflare's auto-import is good but not perfect. In my case it missed two records that were in Namecheap but didn't show up in the scan: a subdomain A record and a second DKIM record for ConvertKit (cka2._domainkey). Always compare the Cloudflare list against your registrar's Advanced DNS settings manually before switching.

One rule that matters: DKIM, DMARC, and SPF records must stay as DNS only (grey cloud), not proxied (orange cloud). Proxying email-related records breaks email delivery. Your A records for the main domain and www should be proxied. Everything email-related should not be.

Step 3: Add missing records manually

If you find gaps, use "Add record" to fill them in before proceeding. Getting this right now saves you debugging email deliverability issues later.

Step 4: Change your nameservers

Cloudflare gives you two nameservers (something like anton.ns.cloudflare.com and megan.ns.cloudflare.com). Go to your registrar, find the nameservers section, switch from their default to Custom DNS, and enter the two Cloudflare nameservers.

DNS propagation takes anywhere from 5 minutes to a few hours. In my case it took under two minutes. Cloudflare emails you when the domain goes active.

On the AI crawler setting: during setup Cloudflare asks if you want to block AI training bots. If you run a content site and want visibility in AI-generated answers, choose "Do not block". If you have an llms.txt file or care about AI referencing your content, blocking crawlers contradicts that completely.

Once Cloudflare is active, your server IP is no longer the first thing that resolves for your domain. Attackers hitting your domain hit Cloudflare first. That's the point.

Layer 3: Tailscale

This is the part most people skip. It sounds complicated. It's not. It took me 15 minutes start to finish.

Tailscale creates a private mesh network between your devices. Once installed on your laptop and your VPS, both get private Tailscale IP addresses in the 100.x.x.x range. These IPs only exist within your Tailscale network. Nobody outside can see or reach them.

The goal is to lock port 22 so it only accepts connections from the Tailscale network. The public internet can't even see the port exists.

Install Tailscale on your Mac

Download from the Mac App Store, or via Homebrew:

brew install tailscale

Install Tailscale on your VPS

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

The second command outputs a URL like https://login.tailscale.com/a/xxxxxx. Open it in your browser, authenticate with the same account you used on your Mac, and the VPS joins your network.

You might see a warning during installation about the running kernel version not matching the expected version. This is Ubuntu telling you there's a pending kernel update that requires a reboot to apply. It doesn't affect Tailscale at all. Schedule a sudo reboot when it's convenient and the server will come back up with everything running automatically.

Check the Tailscale dashboard

Go to the Machines tab in your Tailscale account. You should see two devices, both showing "Connected", each with a 100.x.x.x IP address.

Test SSH through Tailscale before locking anything

This step is not optional. Open a new terminal and SSH using the VPS Tailscale IP:

ssh root@100.x.x.x   # use your VPS Tailscale IP

If you get in, you're ready to lock port 22. If you can't connect, stop and figure out why before going any further.

Lock port 22 to Tailscale only

Run these three commands on your server:

ufw allow in on tailscale0 to any port 22
ufw deny 22
ufw reload

Then open a second terminal and SSH via the Tailscale IP again. If it connects, you're done. Port 22 is now invisible to the public internet.

Update your SSH config on your Mac

So you don't have to remember the Tailscale IP:

# ~/.ssh/config
Host your-server
    HostName 100.x.x.x    # your VPS Tailscale IP
    User root
    IdentityFile ~/.ssh/id_rsa

From this point on, ssh your-server works exactly as before. Tailscale runs as a background service on your Mac and starts automatically on login. You'll never notice it's there.

What About Daily Workflow?

Nothing changes. You still SSH the same way, just to the Tailscale IP instead of the public one. Your Laravel app deploys the same way. Your deploy scripts, Nginx configs, cron jobs, Supervisor processes all keep running as normal. If you're running Docker containers on the same server, those are untouched too. Tailscale only affects how you get into the machine, not what runs inside it.

The only difference you'll notice is that if Tailscale somehow isn't running on your Mac, SSH to the Tailscale IP will time out. Your fallbacks in that case:

Start Tailscale on your Mac (it's a menu bar app, one click to reconnect)
Use DigitalOcean's browser console (always available, no SSH needed)
Install Tailscale on your iPhone as a backup device

Tailscale's reliability has been solid in my experience. It starts automatically on your Mac at login and reconnects if your internet drops. But knowing your escape routes before you need them is basic practice. I keep the DO console bookmarked. It's saved me once already.

One thing worth doing after you lock port 22: run ufw status and check what's actually open. Your output should look something like this:

Status: active

To                         Action      From
--                         ------      ----
Nginx Full                 ALLOW       Anywhere
22 on tailscale0           ALLOW       Anywhere
22                         DENY        Anywhere

If port 22 shows DENY and you can still SSH in via the Tailscale IP, the setup is working exactly as intended.

The Honest Trade-offs

This setup isn't magic. Here's what you're actually signing up for:

Cloudflare free tier proxies HTTP/HTTPS only. Non-standard ports, custom TCP protocols, game servers: none of these get proxied on the free plan. For a standard web app, you won't hit this limit. But if you're running something unusual, check the Cloudflare Spectrum pricing before assuming everything's covered.

Tailscale adds a dependency for SSH access. Any device you SSH from needs Tailscale installed. For a solo developer with one laptop, this is fine. If you ever need to SSH from a machine you don't control, you'd need to install Tailscale there first, or fall back to the DO console.

Cloudflare adds a tiny latency overhead for cache misses. Requests that hit your origin server (dynamic Laravel responses) pass through Cloudflare's network. The overhead is negligible in practice, we're talking single-digit milliseconds. For static assets, Cloudflare is actually faster because files serve from a nearby edge node.

For a solo developer running production projects on a $5-20/month VPS, these trade-offs are worth it. Both Tailscale and Cloudflare are free for this use case.

Security Doesn't Stop at the Server

Once you've hardened your VPS, the next thing worth auditing is what's running on it. If you're deploying Laravel apps, your Composer dependencies are another real attack surface. Fake packages mimicking legitimate ones have been found in the wild. This walkthrough on auditing your Composer dependencies covers how to check what's actually installed and what to look for.

Infrastructure security and application security are different layers. You need both.

FAQ

Do I need Cloudflare if I'm not worried about DDoS attacks?

The DDoS protection is a bonus, not the main reason. The real value is hiding your server IP. If attackers can't find your server's IP address, they can't target it directly. The free tier is worth setting up for any public-facing production server.

Can I use Tailscale on Windows instead of Mac?

Yes. Tailscale has native clients for Windows, macOS, Linux, iOS, and Android. The VPS setup is identical regardless of which device you connect from.

What if Tailscale goes down and I need to SSH in?

Use your VPS provider's browser-based console. DigitalOcean calls it the Droplet Console, Hetzner calls it the Console button. It gives you terminal access directly through the browser without needing SSH at all. Bookmark it before you need it.

Does this work on Hetzner, AWS, or other VPS providers?

Yes. The SSH hardening and Tailscale steps are identical on any Ubuntu/Debian server. For Cloudflare, you just need control of your domain's DNS. The server provider doesn't matter.

What's the order I should do this if my server is already live?

SSH hardening first (today, takes five minutes). Cloudflare second (takes 20 minutes, zero downtime). Tailscale third (takes 15 minutes, test before locking). Each step is independent, so you can space them out over a few days if needed. But the SSH hardening is the one to do immediately.

The Summary

The whole setup took me one afternoon. SSH hardening took five minutes. Cloudflare took twenty. Tailscale took fifteen.

Your server is running right now with bots probing it constantly. Most of the time nothing happens. But "most of the time" isn't a security strategy when you're running client projects on that machine.

Do the SSH hardening today. Add Cloudflare this week. Set up Tailscale when you have 30 minutes. Each layer is independent and each one meaningfully reduces your exposure.

If you're building something and want to talk through the setup for your specific stack, get in touch.

Laravel AI SDK Goes Stable on March 17: What Changed and What to Check Before You Ship

Hafiz — Tue, 17 Mar 2026 06:02:04 +0000

The Laravel AI SDK went stable today, March 17, alongside Laravel 13. If you've been watching from the sidelines waiting for the official green light, this is it.

But here's the thing: "stable" isn't just a label. It changes how you depend on the package, what you can expect from version updates, and whether it's safe to build production features on top of it. And if you already followed my overview post or the Part 1 and Part 2 tutorials, you're probably wondering: does my code still work? What actually changed?

That's what this post covers. No feature recaps you've read five times already. Just what changed, what "stable" means in practice, and a checklist to run through before you ship.

What "Stable" Actually Means Here

When Laravel tags a package as stable, a few concrete things happen.

First, semantic versioning kicks in properly. During the beta period, the v0.x releases could introduce breaking changes between minor versions, and they did. The API shifted. Namespace conventions got tidied up. Method signatures changed. Once the package hits 1.0, breaking changes are reserved for major version bumps only. You'll get bug fixes and new features without your code suddenly not compiling.

Second, the package becomes safe to lock in production composer.json files. During beta, the right call was "laravel/ai": "dev-main" or a loose ^0.x constraint. After March 17, you'll want ^0.3 or higher. That pins you to the stable release channel and means composer update won't pull in something that breaks your agents.

Third, first-party support is now official. Security vulnerabilities get patched. The team maintains backward compatibility. Other packages in the ecosystem (Filament, Prism, and others) can safely declare it as a dependency without worrying the ground will shift under them.

So it's not that the features change dramatically on March 17. It's that the reliability contract is now formal.

What Changed During the Beta Period

The SDK launched publicly in early February 2026 as a bold first release. The core idea was solid from day one: a unified, Laravel-native API for working with AI providers, built around the Agent class pattern.

But the beta period was genuinely used to polish things. Here's what shifted between the initial release and v0.3.0:

Provider tool configuration became cleaner. The WebSearch, WebFetch, and FileSearch provider tools are now properly namespaced under Laravel\Ai\Providers\Tools. Early beta code that referenced these directly needed updating.

Configurable timeouts for embedding requests landed in v0.3.0. If you're running large embedding jobs and hitting timeout issues, this is the fix. You can now set timeout values per provider in config/ai.php.

The RemembersConversations trait stabilised. Early implementations had some rough edges around the agent_conversations and agent_conversation_messages tables. The migration schema is now final.

Structured output via JsonSchema cleaned up its fluent API. Some method chains that worked in early beta were deprecated in favour of a more consistent interface. If you wrote structured output agents before February 2026, double-check your schema definitions.

Testing fakes became comprehensive. The ability to fake agents, images, audio, transcriptions, embeddings, reranking, and file stores is now a first-class feature. This wasn't complete in the initial launch.

The v0.3.0 release on March 12 (which Taylor tweeted about) also added a handful of fixes around tool request handling. Nothing that breaks existing code, but it's worth pulling the latest.

The Full Feature Set, Now Locked In

Since the stable release freezes the API, it's worth knowing exactly what you're working with. Here's everything that's now officially supported:

flowchart TB
    A["Your Laravel app<br/>agents · controllers · jobs"]
    A --> B["Laravel AI SDK unified interface"]
    B --> C[OpenAI]
    B --> D[Anthropic]
    B --> E[Gemini]
    B --> F["+ 8 more"]

Agents are the core primitive. You create them via php artisan make:agent and configure instructions, tools, memory, and output schema inside the class. Or you use the agent() helper for quick inline agents. Think of each agent as a focused specialist: it has one job, one set of instructions, and one output contract.

Multi-provider support covers OpenAI, Anthropic, Gemini, ElevenLabs, Groq, Cohere, DeepSeek, xAI, and OpenRouter. You swap providers by changing a single string. No client library changes, no interface refactoring. This is the part that makes the SDK genuinely different from just wrapping the OpenAI PHP client.

Provider failover is built in. Pass an array of providers and the SDK automatically tries the next one if it hits a rate limit or outage:

$response = (new SalesCoach)->prompt(
    'Analyse this transcript...',
    provider: [Lab::OpenAI, Lab::Anthropic],
);

flowchart TD
    A[Your Laravel app] --> B[SDK tries OpenAI]
    B -- success --> D[Response returned]
    B -- rate limit / outage --> C[SDK retries Anthropic]
    C --> D

Structured output uses a JsonSchema builder that generates the schema definition automatically and casts the response to your specified types. No more manually parsing JSON strings from AI responses. The agent returns a typed array you can work with directly.

Image, audio, and embedding generation all use the same fluent interface pattern. Images can be queued and stored to any filesystem disk. Audio supports both synthesis and transcription. Embeddings work with any vector store you configure.

Vector stores for RAG use cases are fully supported, with SimilaritySearch available for semantic document retrieval. If you built the support bot from my Part 2 tutorial, this is the feature you used most.

Rate limiting per user is configurable in config/ai.php. Important for any app where end users trigger AI requests directly. Without this, a single user can burn through your API quota in minutes.

Middleware for agents lets you intercept and modify requests and responses. Useful for logging every prompt and response, filtering sensitive content before it reaches the model, or injecting user context automatically so you don't repeat it in every system prompt.

Production Readiness Checklist

Before you ship anything using the stable SDK, run through this list. Some of these will seem obvious. But I've seen each one catch someone out on a real project.

1. Update your composer constraint

composer require laravel/ai:^0.3

Don't stay on dev-main or ^0.x in production. The stable tag is exactly when you tighten this.

2. Publish and review the config file

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

If you published this during beta, diff the new config against yours. Timeout settings, rate limit configuration, and the provider list may have new options you're not using yet.

3. Run the migrations fresh

php artisan migrate

If you installed the SDK during beta, confirm your agent_conversations and agent_conversation_messages tables match the final migration schema. The conversation storage schema stabilised in v0.3.0 and it's worth verifying your existing tables haven't drifted.

4. Set up provider failover for anything user-facing

Single-provider setups are fine for internal tools. For anything a real user waits on, configure a fallback:

// config/ai.php
'default_providers' => [
    Lab::OpenAI,
    Lab::Anthropic,
],

Or set it per agent class using the provider argument. Rate limits and brief outages are normal. Your users shouldn't see them.

5. Move heavy AI operations to queued jobs

Image generation, embedding indexing, audio transcription: none of these should run synchronously in a request cycle. The SDK supports queuing natively:

Image::of('A product banner for...')
    ->generate()
    ->store('products/banner.webp');

Wrap that in a queued job and your HTTP response times stay fast regardless of what the AI provider is doing. I covered Laravel queue patterns in depth here if you want the full setup.

6. Write tests using fakes, not real API calls

This is where the stable SDK really delivers. Every AI operation has a fake:

use Laravel\Ai\Testing\AgentFake;

AgentFake::fake([
    SupportAgent::class => 'Here is the answer to your question...',
]);

// Your test now runs without hitting OpenAI
$response = (new SupportAgent)->prompt('How do I reset my password?');

$this->assertStringContainsString('answer', $response->text);

Tests that hit real AI APIs are slow, expensive, and flaky. Use the fakes. They're comprehensive and they cover images, audio, embeddings, and file stores too.

7. Validate structured output schemas

If you're using JsonSchema for structured agent responses, run a quick sanity check against the final stable API. Some fluent methods changed between early beta and v0.3.0. This is especially important if you wrote agents before mid-February. When debugging structured outputs, a JSON formatter saves time when you're staring at raw API response bodies trying to figure out where the schema mismatch is.

Does Your Existing Tutorial Code Still Work?

If you built the document analyser from Part 1 or the RAG support bot from Part 2, the answer is mostly yes, with one thing to check.

The agent() helper function, agent class structure, Promptable trait, tool interface, and SimilaritySearch usage are all unchanged. Your business logic is fine.

The one thing to verify: if you referenced provider tools like WebSearch or WebFetch directly in your agents, confirm the namespace is Laravel\Ai\Providers\Tools\WebSearch. That moved during beta.

Also bump your composer constraint to ^0.3 or higher and run composer update to get any fixes from the v0.3.0 release before the stable tag lands.

When You Shouldn't Rush to Use It

The stable launch doesn't mean AI is the right call for every new feature. I want to be direct about this.

The SDK is great when you have a specific, bounded use case with clear inputs and outputs. Structured output agents for classification, document analysis, support routing, content generation with known schemas: these all work well and are genuinely production-ready.

It's harder when you need deterministic behaviour. AI responses aren't consistent the way database queries are. If your feature requires exact, reproducible outputs, you're still better off with conventional code.

And cost matters. Every AI API call has a price. For user-facing features that get hit frequently, run the numbers before shipping. The SDK's rate limiting helps control this, but it doesn't make the problem disappear.

The PHP Attributes post from March 4 is actually a good example of what goes stable alongside this SDK. Laravel 13 as a whole is taking a measured, practical approach to new capabilities. The AI SDK fits that same philosophy. It's ready for production use cases. It's not a reason to retrofit AI into things that don't need it.

Frequently Asked Questions

Does upgrading to the stable SDK require any database migration changes?

If you're already using the SDK in beta, run php artisan migrate and check that your agent_conversations table matches the final schema. For new installs, publish the migrations fresh after upgrading to ^0.3 or higher.

Can I use the stable SDK on Laravel 12 or do I need to upgrade to Laravel 13?

The SDK currently lives in the Laravel 12.x docs and has been available since February 2026 on Laravel 12. The March 17 stable tag coincides with Laravel 13's release, but you don't need to upgrade Laravel to use the stable SDK. It works on Laravel 12.

What's the difference between using the agent() helper and creating a dedicated Agent class?

The agent() helper is great for quick, inline agents: one-off operations where you don't need reusability. Dedicated Agent classes are for agents you'll prompt from multiple places in your app, or agents with complex tool configurations and middleware. Start with the helper, extract to a class when it grows.

How do I handle AI API rate limits in production without the failover feature?

If you're locked to a single provider, queue your AI operations and add retry logic via Laravel's built-in job retry mechanisms. Set public $tries = 3 and public $backoff = [30, 60, 120] on your job class. The failover feature is better, but queued retries work as a fallback.

Is the Laravel AI SDK a replacement for Prism or should they coexist?

The official SDK covers the most common use cases and is now the first-party choice for new Laravel projects. Prism has a larger provider surface and some features the official SDK doesn't have yet. For new projects, start with the official SDK. If you have existing Prism code that works, there's no urgent reason to migrate.

What to Do Right Now

Install the stable SDK today, update your composer constraint to ^0.3 or higher, and run through the checklist above. If you've been holding off on building AI features because the SDK was in beta, the wait is over.

This is genuinely the cleanest path to adding AI to a Laravel app right now. Not because it's the only option, but because it follows every Laravel convention you already know: service providers, facades, artisan commands, queue jobs, and config files. There's no mental context switch. You're writing Laravel code that happens to call an AI provider.

The full Laravel AI SDK docs are already live and cover everything with code examples. They're the authoritative reference now that the stable tag has landed.

Building an AI-powered product and want to ship it fast? I help founders and teams go from idea to working Laravel MVP. Let's talk.

Forem: Hafiz

Livewire 4 Single-File Components: Build a Live Search in One File

The Problem With the Old Two-File Pattern

What a Single-File Component Looks Like

Adding an Island for Expensive Data

Rendering the Component

When to Use Single-File vs Multi-File

Migrating a v3 Component

FAQ

Scotty vs Laravel Envoy: Spatie's New Deploy Tool Is Worth the Switch

The Problem With Laravel Envoy

What Scotty Does Differently

Installing Scotty

Migrating From Envoy

Zero-Downtime Deployments

So Is It Worth Switching?

FAQ

Livewire 4 vs Inertia.js 3: Which Laravel Frontend Stack Should You Use in 2026?

What Livewire 4 Actually Changed

What Inertia.js 3 Actually Changed

The Fundamental Difference Is Still the Same

The Real Decision in 2026

My Take

FAQ

Inertia.js v3 Is Out: The Upgrade Guide Every Laravel Developer Actually Needs

What's Actually New in v3

Can You Upgrade Right Now?

Before You Run composer update: Check Your Requirements

The Upgrade Steps

Breaking Changes to Fix

Event renames

Axios, qs, and lodash-es are gone

The inertia head attribute became data-inertia

router.cancel() became router.cancelAll()

Inertia::lazy() is removed

Progress indicator exports

The future config block is gone

Config file restructuring

ESM-only output

Two Things Worth Using Right Away

Should You Upgrade This Weekend?

Frequently Asked Questions

What's Next

Cache::funnel() in Laravel: Concurrency Limiting Without Redis

A Quick Recap of What Redis::funnel() Was Doing

The New API

limit()

releaseAfter()

block()

then()

Use Case 1: Throttling External API Calls in Queue Jobs

Use Case 2: Per-User Report Generation

Use Case 3: Testing Without Infrastructure

Using It in Job Middleware

Cache::funnel() vs Cache::withoutOverlapping()

Should You Migrate Away From Redis::funnel()?

Things to Watch Out For

FAQ

Wrapping Up

Laravel AI SDK: 3 Multi-Agent Patterns Worth Using in Production (and 2 to Skip)

What Multi-Agent Patterns Actually Are

Pattern 1: Prompt Chaining

Pattern 2: Routing

Pattern 3: Parallelization

The Two Patterns to Skip (For Now)

Orchestrator-Workers

Evaluator-Optimizer

A Simple Decision Framework

FAQ

Wrapping Up

Laravel 13 Queue::route(): One Place to Control Your Entire Queue Topology

The Two Patterns You're Probably Mixing Right Now

How Queue::route() Works

The Actually Clever Part: Interface and Trait Routing

A Visual: How Dispatch Resolution Works

A Real Before and After

Migrating an Existing App

When ->onQueue() Still Makes Sense

Trade-offs Worth Being Honest About

FAQ

The `inertia` head attribute became `data-inertia`

`router.cancel()` became `router.cancelAll()`

`Inertia::lazy()` is removed

The `future` config block is gone