DEV Community: Hafiz

How Laravel Events, Listeners, and Observers Actually Work (And When to Use Each)

Hafiz — Mon, 20 Apr 2026 05:51:50 +0000

A new user registers on your SaaS. You need to send a welcome email, provision their free trial, log the signup event, and notify your Slack channel. Where does that code go?

If the answer is "the controller", your controller is doing too much. If the answer is "a listener that calls a listener that calls another listener", your event system is doing too much. Laravel gives you three distinct tools to get there: Events, Listeners, and Observers. Each one has a clear job. The distinction is worth understanding because reaching for the wrong one creates the kind of coupling you were trying to avoid in the first place.

What Problem Are We Actually Solving?

When a user registers, the naive approach stuffs everything in the controller:

public function store(RegisterRequest $request): RedirectResponse
{
    $user = User::create($request->validated());

    Mail::to($user)->send(new WelcomeEmail($user));
    Trial::provision($user);
    Slack::notify('New signup: ' . $user->email);
    Log::info('User registered', ['id' => $user->id]);

    return redirect('/dashboard');
}

This works. It's also a problem. The controller now knows about mail, trials, Slack, and logging. Add a new onboarding step and you touch the controller. Change how trials work and you touch the controller. Write a test for the controller and you mock four different things.

Events, Listeners, and Observers flip this around. The controller fires a signal ("something happened") and the rest of the application reacts. The controller doesn't know or care what reacts.

Events: The Signal

An event is a plain PHP class that represents something that happened. That's it. It carries data about the occurrence and nothing else.

<?php

namespace App\Events;

use App\Models\User;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class UserRegistered
{
    use Dispatchable, SerializesModels;

    public function __construct(
        public readonly User $user
    ) {}
}

Create one with Artisan:

php artisan make:event UserRegistered

Fire it anywhere in your application:

UserRegistered::dispatch($user);
// or
event(new UserRegistered($user));

An event class should be small. It shouldn't contain methods that do things. It's a data container, not a service. The name should describe what happened in past tense: UserRegistered, OrderShipped, PaymentFailed. If you find yourself writing logic inside an event class, that logic belongs in a listener.

Listeners: What Reacts

A listener receives an event and does something with it. One event can have many listeners. Listeners don't know about each other.

php artisan make:listener SendWelcomeEmail --event=UserRegistered

<?php

namespace App\Listeners;

use App\Events\UserRegistered;
use App\Mail\WelcomeEmail;
use Illuminate\Support\Facades\Mail;

class SendWelcomeEmail
{
    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user)->send(new WelcomeEmail($event->user));
    }
}

Each listener does one job. SendWelcomeEmail sends a welcome email. ProvisionFreeTrial provisions a trial. NotifySlack posts to Slack. Adding a new step means adding a new listener. You don't touch the existing ones.

Auto-Discovery in Laravel 11+

Before Laravel 11, you had to manually register every event and listener in EventServiceProvider::$listen. Laravel 11 removed EventServiceProvider from the default application structure and turned on auto-discovery by default.

Auto-discovery works by scanning app/Listeners/ and looking for handle() methods. If a handle() method type-hints an event class, Laravel automatically wires that listener to the event. No registration required.

// This listener is auto-discovered. No registration needed.
class SendWelcomeEmail
{
    public function handle(UserRegistered $event): void
    {
        // ...
    }
}

This matters because the old approach had a subtle maintenance problem: the $listen array in EventServiceProvider was a second source of truth. You could create a listener, forget to register it, and your code would run without errors. The listener just silently never fired. Auto-discovery eliminates that category of bug entirely.

One listener class can also handle multiple events by defining multiple methods, each type-hinting a different event:

class UserActivityListener
{
    public function handleLogin(Login $event): void
    {
        // Runs on login
    }

    public function handleLogout(Logout $event): void
    {
        // Runs on logout
    }
}

Laravel's scanner picks up both handleLogin and handleLogout automatically because they start with handle and type-hint an event class.

In production, cache the discovered listener manifest so Laravel doesn't scan on every request:

php artisan event:cache

Clear it during deployment with:

php artisan event:clear

If you're on an older Laravel version or want explicit control, you can still register listeners in AppServiceProvider::boot():

use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(
        UserRegistered::class,
        SendWelcomeEmail::class
    );
}

Both approaches work. Auto-discovery is cleaner for new applications. Explicit registration is useful when you need listeners from third-party packages or conditional registration.

Queued Listeners

Sending emails, making HTTP calls, generating reports: these don't need to block the HTTP response. Implement ShouldQueue and Laravel automatically dispatches the listener as a background queue job:

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class SendWelcomeEmail implements ShouldQueue
{
    use InteractsWithQueue;

    public string $queue = 'emails';
    public int $delay = 30; // seconds

    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user)->send(new WelcomeEmail($event->user));
    }

    public function failed(UserRegistered $event, \Throwable $exception): void
    {
        // Handle failure: log it, alert, retry logic, etc.
        Log::error('Welcome email failed', [
            'user' => $event->user->id,
            'error' => $exception->getMessage(),
        ]);
    }
}

The failed() method is important. Queued listeners can fail. Define this method to handle failures gracefully rather than silently losing the email send.

After Database Commit

One common gotcha: a listener fires before the database transaction commits. Your listener reads a user ID, queries the database, and finds nothing because the record doesn't exist yet.

The fix is ShouldHandleEventsAfterCommit:

use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;

class ProvisionFreeTrial implements ShouldQueue, ShouldHandleEventsAfterCommit
{
    public function handle(UserRegistered $event): void
    {
        // Guaranteed to run only after the database transaction commits
        Trial::createFor($event->user);
    }
}

Use this whenever your listener reads from the database and you're dispatching the event inside a transaction.

Observers: Model Lifecycle Hooks

Observers are a different tool for a different job. While events and listeners handle application-level signals, observers handle Eloquent model lifecycle events: creating, created, updating, updated, deleting, deleted, and more.

php artisan make:observer UserObserver --model=User

<?php

namespace App\Observers;

use App\Models\User;

class UserObserver
{
    public function created(User $user): void
    {
        // Runs every time any User is created anywhere in the codebase
    }

    public function updated(User $user): void
    {
        // Runs every time any User is updated
    }

    public function deleted(User $user): void
    {
        // Runs every time any User is deleted
    }
}

Register the observer on the model using the #[ObservedBy] PHP attribute, introduced in Laravel 10.44 and fully supported in Laravel 11, 12, and 13:

<?php

namespace App\Models;

use App\Observers\UserObserver;
use Illuminate\Database\Eloquent\Attributes\ObservedBy;
use Illuminate\Foundation\Auth\User as Authenticatable;

#[ObservedBy([UserObserver::class])]
class User extends Authenticatable
{
    // ...
}

Before this attribute existed, you'd register observers in a service provider:

// AppServiceProvider::boot()
User::observe(UserObserver::class);

Both still work. The #[ObservedBy] attribute is cleaner because the registration lives on the model itself. You can see at a glance that UserObserver is active without hunting through providers.

The Full List of Observer Methods

An observer class can define methods for any of the Eloquent lifecycle events:

class UserObserver
{
    public function retrieved(User $user): void {}   // After fetching from DB
    public function creating(User $user): void {}    // Before insert
    public function created(User $user): void {}     // After insert
    public function updating(User $user): void {}    // Before update
    public function updated(User $user): void {}     // After update
    public function saving(User $user): void {}      // Before create or update
    public function saved(User $user): void {}       // After create or update
    public function deleting(User $user): void {}    // Before delete
    public function deleted(User $user): void {}     // After delete
    public function restoring(User $user): void {}   // Before soft-restore
    public function restored(User $user): void {}    // After soft-restore
}

You don't need to define all of them. Define only the lifecycle hooks your use case actually needs. An observer with one method is perfectly fine.

The creating and updating hooks (before the operation) are useful for validation, transformations, or cancelling the operation by returning false. The created and updated hooks (after the operation) are better for side effects like sending notifications or clearing caches, since you know the database state is settled.

What Goes in an Observer vs a Listener

This is where most developers get confused. The distinction is simpler than it looks:

Use an observer when the behavior should trigger on every instance of a model event, everywhere in the codebase. Audit logging is the clearest example: every time any user is created, updated, or deleted, you want a log entry. An observer is the right place for that.

Use an event and listener when the behavior is specific to a particular business flow. A user registering via the web form should get a welcome email. A user created programmatically by a data import job probably shouldn't. Events give you control over when to fire the signal. Observers fire automatically no matter what.

Here's a practical SaaS breakdown:

Scenario	Tool	Why
Send welcome email on registration	Event + Listener	Only fires when you explicitly dispatch the event
Write to audit log on every User update	Observer	Should always fire, regardless of where the update originates
Provision free trial after signup	Event + Listener (queued)	Business flow specific, benefits from queueing
Clear cache when Post is deleted	Observer	Should always happen when any Post is deleted
Notify Slack on first payment	Event + Listener	Specific business milestone, not every payment creation
Update `last_updated_at` on every Order save	Observer	Always should happen, tightly coupled to model lifecycle

If you're still unsure which to reach for, this decision flow covers most cases:

A Real-World Pattern: User Registration

Here's how all three tools work together in a user registration flow. The controller fires one event. Two listeners react to that event asynchronously. The observer independently handles model-level concerns for every user creation, no matter where it originates.

// Controller stays clean
class RegisterController extends Controller
{
    public function store(RegisterRequest $request): RedirectResponse
    {
        $user = User::create($request->validated());

        UserRegistered::dispatch($user);

        return redirect('/dashboard');
    }
}

// Listener: sends welcome email (queued)
class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user)->send(new WelcomeEmail($event->user));
    }
}

// Listener: provisions trial (queued, after commit)
class ProvisionFreeTrial implements ShouldQueue, ShouldHandleEventsAfterCommit
{
    public function handle(UserRegistered $event): void
    {
        Trial::createFor($event->user);
    }
}

// Observer: handles model-level concerns for ALL user creation
#[ObservedBy([UserObserver::class])]
class User extends Authenticatable { /* ... */ }

class UserObserver
{
    public function created(User $user): void
    {
        AuditLog::record('user.created', $user->id);
    }

    public function updated(User $user): void
    {
        AuditLog::record('user.updated', $user->id, $user->getDirty());
    }
}

The controller fires one event. Two listeners react to that event in the background. The observer independently logs every user creation, including the one triggered by the controller. Each piece of code does one job and doesn't know about the others.

This pattern scales well in multi-tenant SaaS applications, where the same model events fire across tenants and the observer ensures audit logging is consistent regardless of which flow created the record.

Testing Events and Listeners

Laravel's Event::fake() replaces the event dispatcher with a fake that captures dispatched events without actually running listeners. This is what you want for most feature tests. You want to assert that an event was dispatched, not that a listener ran.

use App\Events\UserRegistered;
use Illuminate\Support\Facades\Event;

test('user registration dispatches UserRegistered event', function () {
    Event::fake();

    $response = $this->post('/register', [
        'name' => 'Hafiz Riaz',
        'email' => 'hafiz@example.com',
        'password' => 'password',
        'password_confirmation' => 'password',
    ]);

    Event::assertDispatched(UserRegistered::class, function ($event) {
        return $event->user->email === 'hafiz@example.com';
    });
});

Test the listener separately by instantiating it directly:

use App\Events\UserRegistered;
use App\Listeners\SendWelcomeEmail;
use App\Models\User;
use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeEmail;

test('SendWelcomeEmail listener sends welcome email', function () {
    Mail::fake();

    $user = User::factory()->create();
    $event = new UserRegistered($user);

    (new SendWelcomeEmail)->handle($event);

    Mail::assertSent(WelcomeEmail::class, fn ($mail) => $mail->hasTo($user->email));
});

For observers, Event::fake() silences them by default. Model events don't fire when the dispatcher is faked. If you need observers to run inside a fake context, use Event::fakeFor():

test('observer logs user creation', function () {
    // Events are faked, so observers don't run here
    $order = Event::fakeFor(function () {
        return Order::factory()->create();
        // Event::assertDispatched() checks happen inside fakeFor
    });

    // After fakeFor, events and observers run normally
    $order->update(['status' => 'shipped']);
    // Observer fires here
});

You can also fake only specific events, leaving others to run normally:

Event::fake([UserRegistered::class]);
// Only UserRegistered is faked; all other events fire as usual

Artisan Commands Reference

# Create
php artisan make:event UserRegistered
php artisan make:listener SendWelcomeEmail --event=UserRegistered
php artisan make:observer UserObserver --model=User

# List all registered events and listeners
php artisan event:list

# Cache discovered events (run on deployment)
php artisan event:cache

# Clear the event cache
php artisan event:clear

You can find the full list of available Artisan commands in the Laravel Artisan Commands reference.

Common Mistakes

Putting business logic in events. Events are data containers. If you have methods in your event class that query the database or send emails, move that logic to a listener. Keeping events lean also makes them serializable, which matters for queued listeners. Laravel needs to serialize the event to pass it to the queue worker.

Using observers for flow-specific behavior. Observers fire on every model event everywhere. If you want an email sent only when a user registers via the web form, use an event that you dispatch explicitly, not an observer that fires every time a User record is created (including imports, seeds, and tests). Observers are for behavior that should always fire regardless of the origin of the change.

Forgetting event:cache in production. Auto-discovery scans the filesystem on every request unless you cache the manifest. Always run php artisan event:cache during deployment. If you're using Laravel Forge, add it to your deployment script. If you're using a CI/CD pipeline, add it after the composer install step.

Not defining failed() on queued listeners. Queued listeners can fail silently. Define the failed() method to handle errors: log them, send alerts, or retry with different parameters. A queued listener that throws an exception will be retried based on your queue configuration, but without a failed() handler you have no visibility into what failed.

Dispatching events inside database transactions without ShouldHandleEventsAfterCommit. If your listener reads data that the transaction hasn't committed yet, it will fail in subtle ways. Always add ShouldHandleEventsAfterCommit when your listener queries data that the same transaction creates.

Testing with Event::fake() and expecting observers to run. When you call Event::fake(), model observers are also silenced because they rely on the event system internally. If your test needs observer behavior, either use Event::fakeFor() for the specific section that shouldn't fire observers, or don't fake events for the part of the test where observer behavior matters.

FAQ

Should I use Events or Jobs for background tasks?

Both can run code in the background, but the semantics differ. Events signal that something happened and multiple listeners can react. Jobs represent a specific unit of work with one purpose. Use events when you have multiple things that need to react to an occurrence. Use jobs when you have one specific task to run.

Can one listener handle multiple events?

Yes. Type-hint multiple event classes in separate handle* methods, or use union types in a single method. With auto-discovery, Laravel registers each handle* method as a listener for the event it type-hints.

When should I fire an event vs call a method directly?

Fire an event when you want to decouple the caller from what happens next, especially when multiple things need to react, or when the reactions might change in the future. Call a method directly when it's a single, always-present behavior that's tightly coupled to the action.

Do observer methods run inside database transactions?

By default, observer methods run inside the same transaction as the Eloquent operation. If you need the observer to run only after the transaction commits, implement ShouldHandleEventsAfterCommit on the observer class.

What happens to queued listeners if the application crashes before they run?

They stay in the queue. As long as you're using a persistent queue driver like Redis or database, queued jobs survive application restarts. This is one of the advantages of queuing over synchronous execution.

Conclusion

Events signal that something happened. Listeners react to those signals. Observers hook into the Eloquent model lifecycle automatically.

The practical rule: if you want behavior to fire only when you choose to fire it, use events. If you want behavior to fire every time a model changes no matter what, use observers. When in doubt, events with explicit dispatch give you more control.

Think about it from the perspective of a new developer joining your codebase. If they see a UserRegistered::dispatch($user) in the controller, they know exactly where to look for what happens next: the app/Listeners/ directory, or a quick php artisan event:list. If they see an observer on the User model, they know that code runs on every user lifecycle event regardless of where it originates. Both are discoverable. Both have clear intent. That's the point.

The modern Laravel 11+ setup makes this easier. Auto-discovery removes the registration boilerplate. #[ObservedBy] keeps observer registration on the model where it belongs. ShouldHandleEventsAfterCommit handles the transaction timing edge cases that have caught developers off guard for years. And Event::fake() makes the whole system testable without running real side effects.

Start with events and listeners for business flows. Add observers for model lifecycle concerns that should always fire. Keep each piece small and focused. The system scales from a single controller action to a multi-tenant SaaS without the architecture needing to change.

Building something that needs this architecture across a complex codebase? Get in touch.

How I Built a macOS Menu Bar App with NativePHP, Laravel 12 and Livewire 4

Hafiz — Thu, 16 Apr 2026 08:25:31 +0000

Every developer has ignored a break reminder. The notification pops up, you dismiss it in 0.2 seconds without thinking, and two hours later your back hurts and your eyes ache. Notifications don't work. You need something you can't mindlessly dismiss.

So I built ForcedBreak. A macOS menu bar app that shows a full-screen overlay after a configurable interval (25, 45, 60 minutes, whatever you prefer) and makes you complete a physical challenge before you can get back to work. Push-ups. A glass of water. Box breathing. It covers all your monitors. You have to consciously deal with it: complete the challenge, skip it (with a 5-minute penalty), or close it and feel bad about yourself.

The interesting part isn't the concept. It's that I built it entirely with PHP: NativePHP, Laravel 12, Livewire 4, and Tailwind. No Swift. No Objective-C. No raw Electron boilerplate. The app is open source on GitHub and the .dmg for Apple Silicon is available on the releases page.

This post covers the architecture and the four problems that gave me real trouble. If you're building anything with NativePHP, you'll hit at least two of these.

Why NativePHP and Why Laravel 12, Not 13

NativePHP wraps your Laravel app in Electron, giving you access to native macOS APIs through Laravel facades: menu bar, system notifications, window management, screen info. You write PHP and Blade. NativePHP handles the Electron layer.

If you want a proper NativePHP introduction first, I covered the setup basics in Build Your First App with Laravel and NativePHP. This post assumes you have a working NativePHP setup and focuses on the harder parts.

The stack for ForcedBreak:

Layer	Choice	Why
Desktop framework	NativePHP 1.3	Laravel-native desktop apps, no Swift needed
Backend	Laravel 12	Familiar cache, ORM, everything
UI	Livewire 4	Reactive components without writing JavaScript
Styling	Tailwind CSS v4	Dark theme, fast iteration
Database	SQLite	Fully offline, ships with the app

One critical note on the version: NativePHP 1.x requires illuminate/contracts ^10.0|^11.0|^12.0. Laravel 13 internalized illuminate/contracts as part of the framework itself, which breaks this Composer constraint. You can't use Laravel 13 with NativePHP 1.x. Pinning to Laravel 12 is the right call until NativePHP officially ships support.

The Core Architecture: Two Timers, Not One

This is the most important thing to understand before building any NativePHP app that needs background behavior.

The obvious approach is Livewire's wire:poll. Set it to tick every second, decrement a counter, show the result in the menu bar. Simple enough.

It doesn't work. Livewire polling only runs when a browser window is open. A menu bar app lives in the menu bar. The popover window is closed 99% of the time. When the user isn't looking at the popover, wire:poll isn't running. The timer would only tick when the user clicked to open it.

The solution is two separate systems:

Layer 1: The background ticker (authoritative). A dedicated Artisan command runs in an infinite loop as a persistent ChildProcess. It ticks every second, decrements the cache, updates the menu bar label, and triggers the overlay when the timer hits zero. This runs whether the popover is open or not.

Layer 2: Livewire polling (UI only). When the user opens the popover, wire:poll.1000ms reads from the same cache keys and displays the countdown. It never writes to cache. It's a pure reader.

// app/Console/Commands/TickMenuBarLabel.php
public function handle(): void
{
    $lastLabel = '';

    while (true) {
        $start = microtime(true);

        if (!cache()->get('on_break', false)) {
            $secondsLeft = max(0, cache()->get('break_seconds_left', 0) - 1);
            cache()->put('break_seconds_left', $secondsLeft, now()->addHours(2));

            // Only call MenuBar::label() when the value actually changes
            $label = sprintf('%02d:%02d', intdiv($secondsLeft, 60), $secondsLeft % 60);
            if ($label !== $lastLabel) {
                MenuBar::label($label);
                $lastLabel = $label;
            }

            if ($secondsLeft <= 0) {
                $this->openOverlayOnAllScreens();
            }
        }

        $this->sleepUntilNextSecond($start);
    }
}

protected function sleepUntilNextSecond(float $start): void
{
    $elapsed = microtime(true) - $start;
    $remaining = max(0.1, 1.0 - $elapsed);
    usleep((int) ($remaining * 1_000_000));
}

This is registered in NativeAppServiceProvider:

ChildProcess::artisan('app:tick-menubar-label', 'ticker', persistent: true);

The sleepUntilNextSecond() method deserves a mention because the naive version of this loop (just calling sleep(1)) causes 100% CPU usage. sleep(1) blocks for exactly one second but ignores the time the tick itself took. Over time the loop drifts, and under some system conditions it spins. The fix is to measure how long the tick took with microtime(true) and sleep only the remaining microseconds to the next second boundary. It also skips calling MenuBar::label() when the value hasn't changed, which avoids unnecessary HTTP calls to Electron's bridge on every tick.

The persistent: true flag tells NativePHP to restart the process if it crashes. Without it, the ticker dies and the menu bar freezes.

If you've worked with Laravel queue workers running as background daemons, this pattern will feel familiar. The mental model is the same: one authoritative process manages state, and the UI reads from it. The difference here is that the "worker" is an infinite loop command rather than a Horizon worker, because NativePHP's scheduler runs every minute by default and a one-minute resolution isn't good enough for a visible countdown timer.

The reason persistent: true matters is that an infinite loop command can crash. SQLite can throw an exception, a cache operation can fail, or the process can be killed by macOS under memory pressure. Without persistent: true, your menu bar label freezes at whatever time it was showing when the crash happened, and nothing ever triggers the overlay. The user just sits there wondering why the app stopped working. With persistent: true, NativePHP restarts the child process automatically within a few seconds and the timer continues.

This two-layer pattern applies to anything that needs to run when no window is open: timers, background polling, file watchers, scheduled sync tasks. Once you have it working for one thing, you understand the whole model.

Problem 1: The Dual-Database Trap

This one cost me two hours. After I renamed the app, the timer stopped working entirely. No countdown. No overlay. No errors in the logs. Everything appeared fine when I opened the popover.

Here's what was happening.

NativePHP stores its database at:

~/Library/Application Support/{NATIVEPHP_APP_ID}-dev/database/database.sqlite

When I changed NATIVEPHP_APP_ID in .env, NativePHP created a new storage directory with a fresh database file. The old migrations stayed in the old directory. The new database existed at 0 bytes. All cache()->get() and cache()->put() calls silently returned null. The ticker decremented nothing. Nothing happened.

There's a second layer to this: NativePHP doesn't auto-run migrations in dev mode. The file exists but has no tables.

The fix: auto-migrate on every boot in NativeAppServiceProvider:

public function boot(): void
{
    // Auto-migrate ensures the NativePHP database always has tables.
    // Without this, a fresh storage directory silently breaks everything.
    Artisan::call('migrate', ['--force' => true]);
    Artisan::call('db:seed', [
        '--class' => 'ChallengesSeeder',
        '--force' => true,
    ]);

    // ... rest of boot
}

The seeder uses firstOrCreate, so re-running it on every boot is safe.

The broader rule: never change NATIVEPHP_APP_ID without understanding what it does. Your display name is controlled by NATIVEPHP_APP_NAME and can change freely. The app ID determines the storage directory path. Change it and you lose all settings and user data.

To debug this yourself:

sqlite3 ~/Library/Application\ Support/{your-app-id}-dev/database/database.sqlite ".tables"

If you get no output, the database is empty. Copy your local one across and restart.

Problem 2: Not All NativePHP Facades Work From Child Processes

When I added pre-break warning notifications, the code ran without errors. No notification ever appeared.

NativePHP facades communicate with Electron's main process via an HTTP bridge. Some of them work fine from child processes. Others silently fail.

Here's what I found through testing:

Facade	Works from ChildProcess?
`MenuBar::label()`	Yes
`Window::open()`	Yes (with a URL caveat, see next section)
`Screen::displays()`	Yes
`Notification::show()`	No, silently fails

The Notification facade doesn't work from child processes. I tried routing it through a web endpoint as a workaround, where the child process calls an internal HTTP endpoint and that endpoint sends the notification. That also didn't work reliably in my testing.

The pattern I'd suggest before building anything complex with a NativePHP facade: write a quick web route that calls it directly and test in the browser first. If it works there, it will probably work from a child process. If it doesn't work in the browser context, you have a different problem. And if it works in the browser but not in a child process, you've hit this limitation and you'll need to find an alternative approach.

Pre-break notifications are on the v2 list. Once I have more time to investigate the bridge behavior for Notification, I'll add it back in.

Problem 3: URL Resolution in Artisan Context

Window::open() works from child processes, but you have to build the URL yourself.

The default APP_URL in Laravel's .env is http://localhost. NativePHP's PHP server runs on http://127.0.0.1:{dynamic_port}. When the ticker calls Window::open()->route('break.overlay'), it generates http://localhost/break-overlay. Electron tries to load it and gets "Not Found."

The fix: write the actual server URL to a file during boot, then read it in child processes.

// NativeAppServiceProvider::boot()
if (!is_dir(storage_path('app'))) {
    mkdir(storage_path('app'), 0755, true);
}
$port = $_SERVER['SERVER_PORT'] ?? 8100;
file_put_contents(
    storage_path('app/server_url.txt'),
    "http://127.0.0.1:{$port}"
);

Then in the ticker command:

$baseUrl = trim(file_get_contents(storage_path('app/server_url.txt')));
Window::open('break-overlay')->url($baseUrl . '/break-overlay');

Not the most elegant solution, but it works reliably. Since NativeAppServiceProvider::boot() runs before any child process starts, the file is always there when the ticker needs it.

Problem 4: Multi-Screen Overlay

A single Window::open() call opens one window on your primary display. If you have a second monitor, the user can just look over there and keep working.

Screen::displays() returns all connected displays with their bounds. Open one window per display:

$displays = Screen::displays();

foreach ($displays as $i => $display) {
    $bounds = $display['bounds'];
    $windowId = $i === 0 ? 'break-overlay' : "break-overlay-{$i}";

    Window::open($windowId)
        ->url($baseUrl . '/break-overlay')
        ->alwaysOnTop()
        ->titleBarHidden()
        ->position($bounds['x'], $bounds['y'])
        ->width($bounds['width'])
        ->height($bounds['height']);
}

One important gotcha: don't use ->closable(false) on overlay windows. It looks like the right way to prevent accidental dismissal, but it makes Window::close() a no-op. NativePHP calls window.close() under the hood, and when closable is false, Electron ignores it. You'd never be able to close the overlay programmatically.

alwaysOnTop() with titleBarHidden() is enough. The macOS close button is still technically visible, but the user has to make a deliberate choice to click it. That's a different thing from mindlessly swiping away a notification. When the user clicks "I Did It!", the component iterates the same window IDs and closes each one.

Distributing the App

Distributing a NativePHP app outside the Mac App Store is simpler than it sounds. No developer certificate required for direct distribution.

php artisan native:build mac

That produces a .dmg in the dist/ folder. I wrapped this in a build.sh script that handles switching .env to production settings, clearing caches, building assets with npm, running the NativePHP build command, and restoring the dev environment afterward. The whole process takes about 3 minutes on an M2 Mac.

The only thing users have to do after dragging the app to /Applications is run:

xattr -cr /Applications/ForcedBreak.app

This removes the macOS quarantine flag that blocks unsigned apps. It's a standard step for indie Mac apps distributed outside the App Store, safe to run, and you only need to do it once.

Desktop deployment is a different mental model from web apps. There's no server, no zero-downtime concern, no rollback mechanism. You build the .dmg, upload it to GitHub Releases, and users download the new version manually. Much simpler than the deploy pipeline I covered with Scotty and Laravel Envoy, at least for v1.

What I Shipped vs What I Cut

Six features were planned and cut before v1:

Cut feature	Reason
Pre-break notifications	`Notification` facade fails from child processes
Auto-updater	Adds complexity, manual download is fine for now
Onboarding flow	App is self-explanatory
Stats and history charts	Nice to have, not essential for the core concept
Break snooze	Undermines the "forced" nature of the app
iCloud sync	Contradicts the fully offline goal

Every cut made the app ship faster and the core experience sharper. ForcedBreak does one thing: it covers your screens and makes you do a push-up. Everything else is noise until the core concept is proven.

This is the same thing I try to apply when building MVPs for clients. You can read more about how to validate an idea before spending thousands on development, but the short version is: ship the smallest version that tests the assumption. Features can always be added once someone is using it.

What's Next

ForcedBreak v1.0.0 is live now. If you're on an Apple Silicon Mac and want to try it:

Download ForcedBreak v1.0.0 for Apple Silicon →

The source code is on GitHub under MIT. If you find it useful, a star helps others discover it.

For v2, the list is short: get Notification working before breaks (still investigating the child process bridge), add a streak history chart, and build an Intel (x64) version for older Macs.

If you're debugging a stuck NativePHP app, this is the workflow that solved most of my problems:

Check the NativePHP database has tables: sqlite3 ~/Library/Application\ Support/{app-id}-dev/database/database.sqlite ".tables"
Test any NativePHP facade from a web route before using it in a child process
Use curl http://127.0.0.1:8100/dev/force-break to trigger events in the live app, never php artisan tinker
Confirm storage/app/server_url.txt exists and has the correct port

FAQ

Does ForcedBreak work on Intel Macs?

Not yet. The current .dmg is arm64 only (Apple Silicon). An x64 build is on the v2 roadmap.

Can NativePHP build Windows apps?

NativePHP 1.x supports macOS and Linux via Electron. Windows support exists but is less tested in the community. The facades and APIs work the same way in theory.

Why not just build this in Swift?

If you already know Swift, that's valid. NativePHP's advantage is zero context switching. You stay in Laravel, use Eloquent, use the cache, write Blade. For a PHP developer who wants to ship a real desktop app without learning a new language and toolchain, it's the right call.

How large is the final .dmg?

136 MB. That's almost entirely Electron. The actual Laravel app is small, around 500 lines of PHP across models, commands, and Livewire components.

What happens if a user disables all challenges?

The app falls back to the full built-in challenge list. You can disable individual challenges, but the overlay always has something to show. No empty state.

Conclusion

NativePHP is production-ready for focused desktop apps. You don't need Swift. You don't need Objective-C. If you know Laravel, you can ship something real.

The hard part isn't the UI. It's understanding the web context versus the child process context, and what that means for which APIs are available to you. Once that distinction is clear, everything else is just Laravel.

ForcedBreak is available to download on GitHub. If you're building something with NativePHP and hit a wall, get in touch.

Laravel Policies vs Gates: The Complete Authorization Guide

Hafiz — Wed, 15 Apr 2026 05:26:28 +0000

Authentication tells Laravel who you are. Authorization tells Laravel what you're allowed to do. Most developers get authentication right from day one. Laravel's starter kits handle it. Authorization is the part that quietly goes wrong. Rules end up scattered across controllers, Blade files, and middleware, duplicated in three places, and inconsistently applied. One controller checks a Gate. Another skips the check entirely. A third checks directly against a column value inline. After a year of that, nobody knows for certain whether a given action is actually protected.

Laravel solves this with two tools: Gates and Policies. They look similar, they work differently, and knowing which to reach for saves you from that maintenance mess. This guide covers both: what they do, when to use each, how to wire them up correctly, and the specific mistakes worth avoiding.

Gates vs Policies: The One-Sentence Version

Gates are closures for authorization checks that don't belong to a model. Policies are classes that organize authorization logic around a specific model. That's the whole distinction. The rest is just details.

The Laravel docs use a good analogy: Gates are to routes as Policies are to controllers. A Gate is a quick closure you define in AppServiceProvider. A Policy is a dedicated class with methods for every action a user might take against a resource. When your app is small, Gates feel faster. When your app grows, Policies scale much better because the logic is organized, testable in isolation, and easy to find when something needs to change.

You don't have to pick one. Most real applications use both. Gates for cross-cutting concerns like "can this user access the admin panel", Policies for resource-specific logic like "can this user edit this post". The decision tree is simple: if the check involves an Eloquent model, use a Policy. If it doesn't, a Gate is probably fine.

Gates: Quick Authorization Without a Model

Define Gates in the boot() method of App\Providers\AppServiceProvider:

use App\Models\User;
use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::define('view-admin-dashboard', function (User $user): bool {
        return $user->is_admin;
    });

    Gate::define('manage-settings', function (User $user): bool {
        return $user->hasRole('super-admin');
    });
}

Laravel automatically injects the authenticated user as the first argument. You never pass it manually. Then anywhere in your application you check it with Gate::allows() or Gate::denies():

use Illuminate\Support\Facades\Gate;

// In a controller
if (Gate::denies('view-admin-dashboard')) {
    abort(403);
}

// Throw automatically if denied
Gate::authorize('manage-settings');

In Blade templates, @can and @cannot do the same job without touching PHP:

@can('view-admin-dashboard')
    <a href="/admin">Admin Panel</a>
@endcan

When to use Gates:

Authorization checks that aren't tied to a specific Eloquent model
Global permissions like admin access, beta feature toggles, or subscription tier checks
Simple one-off checks that would be over-engineered as a full Policy class
Cross-cutting checks that apply across multiple models or resources

When not to use Gates: The moment you find yourself passing a model instance to a Gate definition, stop. That's a Policy.

Policies: Authorization Organized Around a Model

A Policy is a class with one method per action a user can take on a resource. Generate one with:

php artisan make:policy PostPolicy --model=Post

The --model flag populates the class with the standard methods: viewAny, view, create, update, delete, restore, and forceDelete. You fill in the logic:

<?php

namespace App\Policies;

use App\Models\Post;
use App\Models\User;
use Illuminate\Auth\Access\Response;

class PostPolicy
{
    public function viewAny(User $user): bool
    {
        return true; // any authenticated user can list posts
    }

    public function view(User $user, Post $post): bool
    {
        return $post->published || $user->id === $post->user_id;
    }

    public function create(User $user): bool
    {
        return $user->email_verified_at !== null;
    }

    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->user_id;
    }

    public function delete(User $user, Post $post): bool
    {
        return $user->id === $post->user_id || $user->is_admin;
    }
}

Notice viewAny and create don't take a Post instance. There's no specific post to check against yet. view, update, and delete do, because they operate on a specific model.

Registering Policies: Three Ways in Laravel 13

Auto-discovery (Laravel 13 default): If your PostPolicy lives in app/Policies/ and your Post model is in app/Models/, Laravel finds the connection automatically through naming conventions. You don't register anything. This is the default for new Laravel 13 projects and works for the vast majority of cases.

Manual registration in AppServiceProvider:

use App\Models\Post;
use App\Policies\PostPolicy;
use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::policy(Post::class, PostPolicy::class);
}

Use this when the naming convention doesn't match, for example if your policy is named ArticlePolicy but the model is Post.

The #[UsePolicy] attribute (Laravel 13): You can declare the policy directly on the model class using a PHP attribute:

<?php

namespace App\Models;

use App\Policies\PostPolicy;
use Illuminate\Database\Eloquent\Attributes\UsePolicy;
use Illuminate\Database\Eloquent\Model;

#[UsePolicy(PostPolicy::class)]
class Post extends Model
{
    //
}

This is the most explicit option. The relationship between the model and its policy is visible right where the model is defined, without jumping to AppServiceProvider. It's worth using if your codebase has a lot of non-standard naming, or if you simply value that explicitness. You can find this and all the other make:policy and related Artisan commands in the Laravel Artisan Commands reference.

How to Call a Policy

There are four places where you can trigger a policy check. Each has the right use case.

1. In the controller with Gate::authorize(): This is the most common pattern in Laravel 13. It throws a 403 exception automatically if the check fails:

use Illuminate\Support\Facades\Gate;

public function update(Request $request, Post $post): RedirectResponse
{
    Gate::authorize('update', $post);

    // Only runs if the user passed the policy check
    $post->update($request->validated());

    return redirect()->route('posts.index');
}

2. On the route with ->can() middleware: Good for protecting an entire route before it even reaches the controller. Works especially well with implicit model binding:

Route::put('/posts/{post}', [PostController::class, 'update'])
    ->can('update', 'post');

Route::post('/posts', [PostController::class, 'store'])
    ->can('create', Post::class);

3. Via the #[Authorize] attribute on controller methods (Laravel 13): Clean and declarative if you're already using PHP attributes on your controllers:

use Illuminate\Routing\Attributes\Controllers\Authorize;

#[Authorize('update', 'post')]
public function update(Post $post): RedirectResponse
{
    // ...
}

4. The authorizeResource() shortcut for resource controllers: One call in the constructor wires up authorization for all seven resource methods automatically. This is the most efficient option when you have a full resource controller paired with a matching Policy:

public function __construct()
{
    $this->authorizeResource(Post::class, 'post');
}

This maps index → viewAny, show → view, create/store → create, edit/update → update, destroy → delete. The second argument ('post') tells Laravel which route parameter to resolve for model binding. If you have a full resource controller with a corresponding Policy, this is the cleanest option and removes a lot of repeated Gate::authorize() calls from individual methods.

One setup step required in Laravel 11+: The slim base controller in Laravel 11, 12, and 13 no longer includes authorizeResource() by default. To use it, add the AuthorizesRequests trait to your base controller at app/Http/Controllers/Controller.php:

<?php

namespace App\Http\Controllers;

use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Routing\Controller as BaseController;

abstract class Controller extends BaseController
{
    use AuthorizesRequests;
}

Once the trait is in place, authorizeResource() works as expected in any controller that extends Controller. If you'd rather not touch the base controller, the ->can() route middleware is the cleanest alternative and requires no trait at all.

The Policy `before()` Method: Super-Admin Shortcut

The before() method runs before every other method in a Policy. Use it to grant blanket access without touching every individual method:

public function before(User $user, string $ability): bool|null
{
    if ($user->is_super_admin) {
        return true;
    }

    return null; // null means "proceed to the normal method"
}

Returning true grants access immediately. Returning false denies it immediately. Returning null (or not returning anything) falls through to the individual policy method. This pattern keeps admin bypass logic in one place instead of scattered across every method.

Important: before() is on the Policy, not the Gate. A similar Gate::before() exists at the Gate level and intercepts all Gate and Policy checks globally. Use Gate::before() sparingly. It applies everywhere, which can create confusing behaviour if a check somewhere expects a denial but a global before() keeps returning true.

Returning Rich Responses Instead of Booleans

Policy methods don't have to return bare booleans. You can return a Response object that includes a denial message. This is useful for APIs where the client needs to know why a request was rejected:

use Illuminate\Auth\Access\Response;

public function update(User $user, Post $post): Response
{
    return $user->id === $post->user_id
        ? Response::allow()
        : Response::deny('You do not own this post.');
}

When using Gate::inspect() instead of Gate::authorize(), you can retrieve the full response including the message:

$response = Gate::inspect('update', $post);

if ($response->denied()) {
    return response()->json(['message' => $response->message()], 403);
}

This pairs well with Laravel REST API patterns where the client needs to display the reason for rejection, not just a generic 403.

Authorization in Blade

The @can and @cannot directives work with both Gates and Policies. For Policies, pass the model instance:

{{-- Gate check --}}
@can('view-admin-dashboard')
    <a href="/admin">Admin</a>
@endcan

{{-- Policy check with model --}}
@can('update', $post)
    <a href="{{ route('posts.edit', $post) }}">Edit</a>
@endcan

@cannot('delete', $post)
    <span class="text-muted">You can't delete this post</span>
@endcannot

One thing to remember: Blade directives only hide UI. They don't secure the underlying routes. Always check authorization server-side too. A user could navigate directly to /posts/1/edit and bypass the hidden button completely.

Authorization and Inertia: Sharing Policy Data with the Frontend

If you're building with Inertia.js, your Vue or React components often need to know what the current user can do in order to show or hide UI elements. The cleanest pattern is sharing authorization data through Inertia's shared props in HandleInertiaRequests middleware:

public function share(Request $request): array
{
    return [
        ...parent::share($request),
        'can' => [
            'create_post' => $request->user()?->can('create', Post::class),
            'manage_settings' => $request->user()?->can('manage-settings'),
        ],
    ];
}

Your frontend then reads $page.props.can.create_post without making a separate API request. This approach is covered in the Inertia.js v3 upgrade guide for teams migrating their frontend setup, and it pairs well with the route-level ->can() middleware handling the actual enforcement server-side.

Keep the can object lean. Only share what the current page's UI actually needs. Sharing every possible permission for every resource is wasteful and leaks your authorization surface to the client.

The Mistakes Worth Knowing

Checking authorization only in Blade. The most common mistake. Hiding a button doesn't protect the endpoint. Always pair Blade @can checks with server-side Gate::authorize() or the can middleware. A determined user can navigate directly to any URL regardless of what your Blade template shows them.

Authorizing inside Eloquent models. Authorization logic doesn't belong in a model's events or observers. It belongs at the request layer: controller, middleware, or route. By the time a model method runs, the authorization window has passed and you've lost the request context you need to make the check meaningful.

One giant Gate definition file. If you have 40 Gate::define() calls in AppServiceProvider, that's a sign you should be using Policies. Gates are for the handful of non-model checks. Anything model-specific belongs in a Policy class.

Forgetting viewAny vs view. viewAny authorizes the index action: listing all records. view authorizes reading a specific instance. Developers often only write view and then wonder why their index route isn't protected. With authorizeResource(), both get wired up automatically.

Calling $this->authorize() in Laravel 13 controllers. In older Laravel versions, controllers extended a base class that provided a $this->authorize() helper method. In Laravel 13's leaner controller structure, the recommended approach is Gate::authorize() directly. Both work, but Gate::authorize() doesn't depend on inheriting from the base controller class.

Returning false from before() when you mean to skip. The before() method returns null to "pass through" to the normal policy method, not false. Returning false explicitly denies the action. This trips developers up because the instinct is to return false when you don't want before() to take effect.

When Spatie Permission Fits In

Spatie's spatie/laravel-permission package gives you database-driven roles and permissions rather than hardcoded authorization logic. It's the right addition when your application needs admins to assign and revoke permissions without a code deploy. The package stores roles and permissions in the database, so a super-admin can grant edit-any-post to the editor role through a UI without touching any PHP.

It integrates directly with Policies via the can() check:

public function update(User $user, Post $post): bool
{
    // owner can always edit their own post
    if ($user->id === $post->user_id) {
        return true;
    }

    // editors with the right permission can edit anything
    return $user->can('edit-any-post');
}

The rule of thumb: use Gates and Policies for logic that's structural and fixed (owners can edit their own posts, admins can see the dashboard). Add Spatie Permission when the business rules themselves need to be configurable at runtime. The combination of both is covered in depth in the complete Laravel + Filament SaaS guide, which uses role-based access in a real admin panel context.

Frequently Asked Questions

Do I need to register a Policy manually in Laravel 13?

No, not for standard naming conventions. If your PostPolicy is in app/Policies/ and your Post model is in app/Models/, auto-discovery handles it. Only register manually via Gate::policy() or #[UsePolicy] when naming diverges from the convention.

What's the difference between Gate::allows() and Gate::authorize()?

Gate::allows() returns a boolean, useful when you want to branch logic. Gate::authorize() throws an AuthorizationException (HTTP 403) if denied, which stops execution immediately. Use allows() for conditional logic, authorize() for enforcement.

Can a Policy method allow unauthenticated users?

By default, all policy and gate checks return false for unauthenticated requests. To allow guest access on a specific policy method, make the $user argument nullable:

public function view(?User $user, Post $post): bool
{
    return $post->published || optional($user)->id === $post->user_id;
}

Can I authorize multiple models in one Policy method?

Yes. Pass them as an array to the second argument:

Gate::authorize('update', [$post, $category]);

Then accept both in the policy method:

public function update(User $user, Post $post, Category $category): bool
{
    return $user->id === $post->user_id
        && $user->managedCategories->contains($category);
}

Where should I put authorization logic for API routes?

Same place as web routes: controller-level Gate::authorize() or route-level ->can() middleware. The can middleware works identically on API routes. The difference is in the response: a 403 JSON response rather than a redirect, which Laravel handles automatically for requests that accept JSON.

Authorization done right is invisible. Users can only see and do what they're supposed to, and you never have to think about it again. The mistake is deferring it, scattering checks across controllers, duplicating logic, and ending up with authorization that's inconsistently applied. Starting with Policies from day one, even on a project that feels small, costs almost nothing and pays back every time you add a feature or onboard a developer who needs to understand what the app allows.

Gates for the non-model checks. Policies for everything tied to an Eloquent model. authorizeResource() when you have a full resource controller. That's the mental model that keeps a Laravel app secure and maintainable at any scale.

Building something and not sure how to structure the authorization layer? Get in touch and I'm happy to take a look.

Laravel Telescope vs Pulse vs Nightwatch: Which Monitoring Tool Do You Actually Need?

Hafiz — Mon, 13 Apr 2026 05:27:38 +0000

Three official monitoring tools. Same team. Zero clear explanation of when to use which one. If you've ever stared at the Laravel docs and thought "okay but which one do I actually need?" You're not alone. This is the post that should have existed when Nightwatch launched.

The short version: Telescope is for local development debugging, Pulse is for high-level production metrics, and Nightwatch is for full production observability. But that framing alone doesn't help you make a decision. So let's go deeper.

What Each Tool Is Actually Solving

These three tools exist because monitoring is not a single problem. It's three separate problems that happen to sit next to each other:

During local development, you need to know what your app is doing right now as you build it. You want to see every query, every job, every mail, every notification fired by that last request, in full detail.

In production, you need two very different things depending on what's going wrong. When you want a health check ("is anything trending badly?"), you need aggregated metrics. When something has already gone wrong and a user is affected, you need the full story of exactly what happened, in what order, and to whom.

That's three different needs. Telescope solves the first. Pulse solves the second. Nightwatch solves the third.

Laravel Telescope: Your Local Debugging Companion

Telescope is the most mature of the three. It's been in the Laravel ecosystem since 2018 and is free open source. Install it as a dev dependency, visit /telescope in your browser, and you get a detailed log of everything happening in your app.

Install it with composer require laravel/telescope --dev, then run php artisan telescope:install and php artisan migrate. Every request, Eloquent query, job dispatch, mail, notification, event, cache operation, and exception shows up in a clean dashboard with the exact SQL, the stack trace, and the timing.

The thing Telescope does that nothing else does: it shows you the full context of a single request. You can see that GET /dashboard fired 47 queries, took 340ms, dispatched 2 jobs, and fired 6 events, all in one view, with every detail drillable.

The hard rule on Telescope: never run it in production. It stores every request to your database, which creates serious performance overhead and a potential privacy liability. The official recommendation is to gate it behind an environment check. In AppServiceProvider, check App::isLocal() before registering Telescope. Or simply require it with --dev and it won't be available in production at all.

Telescope is free. It's the right tool for local development, staging debugging, and CI troubleshooting. It's the wrong tool for production.

Laravel Pulse: The Production Health Dashboard

Pulse is newer (it shipped with Laravel 11) and sits at the opposite end of the spectrum from Telescope. Where Telescope is granular and detailed, Pulse is aggregated and high-level. It's built for the "is my app healthy right now?" question.

Install it with composer require laravel/pulse, then run php artisan pulse:install and php artisan migrate. Visit /pulse and you'll see a dashboard showing CPU usage, memory, slow queries, slow routes, failed jobs, queue depth, and cache hit rates, all as aggregated metrics over a configurable time window.

Pulse is free open source and runs inside your own infrastructure with zero external dependencies. Everything is stored in your own database. There's no external service, no SaaS account, no event quota. You own all the data.

The limitation is what "aggregated" means in practice. Pulse will tell you that /api/orders has a P95 response time of 800ms over the last hour. It won't tell you which specific request hit 2,400ms, which user triggered it, what queries ran during that request, or how those queries relate to each other. It gives you the trend. It doesn't give you the incident.

Pulse also requires php artisan pulse:work running as a daemon to process its queue. This is a lightweight process, but it's something to account for in your Supervisor configuration. Alternatively you can use the inline driver for lower-traffic applications that don't need the separate daemon.

Pulse is the right tool for a free production health dashboard when you want to spot trends and anomalies at a glance. It's the wrong tool when you need to investigate a specific incident.

Laravel Nightwatch: Full Production Observability

Nightwatch launched in June 2025 and fills the gap that Telescope and Pulse don't cover: you know something is wrong in production, and you need to understand exactly what happened.

Where Pulse shows you aggregates, Nightwatch keeps every individual event. Where Telescope only works locally, Nightwatch is designed specifically for production. It connects the dots between the request, the user, the queries, the jobs, the exceptions, and the timeline, all in one view.

Install the package with composer require laravel/nightwatch. Add your NIGHTWATCH_TOKEN to .env. Then start the agent:

php artisan nightwatch:agent

The agent runs as a sidecar process, buffering events locally and sending them to Nightwatch's servers roughly every 10 seconds. The overhead is minimal, under 3ms per request per the official documentation. On Forge, the agent setup is a one-click daemon. On Cloud, it runs automatically.

What Nightwatch tracks out of the box, with no configuration: HTTP requests with full timing and user context, exceptions with stack traces and affected user counts, Eloquent queries with their source, queue jobs with execution time and retry history, outgoing HTTP requests, mail, notifications, scheduled tasks, cache operations, and Artisan commands.

The pricing structure: the free plan covers 200,000 events per month, no limits on apps or environments, with 14-day reporting. The Pro plan starts at $20/month for 5M events, 30-day reporting, and unlimited seats. There are Team and Business tiers for higher volumes.

The key difference from Pulse in practice: when a user reports that their checkout timed out at 11:47pm last Tuesday, Nightwatch can show you exactly that request. The route, the user, the 14 queries it ran, which one took 1,800ms, the job it dispatched, whether that job succeeded. Pulse can show you that Tuesday night had elevated P95 response times. That's the difference between a metric and an answer.

One architectural note: Nightwatch requires the sidecar agent to be running continuously. On serverless deployments like Laravel Vapor, you'll need a separate VM to run the agent. This isn't a dealbreaker, but it's something to plan for.

How to Pick the Right Tool

The decision tree is simpler than it looks:

A few real-world scenarios to make this concrete:

Solo developer, side project, no budget: Install Telescope for local development. Add Pulse to production. You get free debugging locally and a free health dashboard in production. You'll be flying blind during incidents, but for a low-traffic side project that's an acceptable trade-off.

Small team, SaaS product with paying customers: Add Nightwatch on the free plan. 200k events per month is enough for most early-stage SaaS applications, especially with sampling enabled. The moment a customer reports an issue, you'll have the data to investigate it. This is where "free but I'll get it wrong" becomes "I found the bug before the customer gave up."

Established product with meaningful traffic: Run all three. Telescope locally, Pulse for the quick health dashboard, Nightwatch for incident investigation and production debugging. They're complementary, not competing. The Nightwatch free plan covers a surprisingly large amount of traffic if you set sampling to 10-20% on high-volume endpoints.

Can You Use All Three Together?

Yes, and the official guidance confirms it. Laravel will continue supporting Telescope and Pulse regardless of Nightwatch's growth. The tools overlap only superficially. Their actual use cases are distinct enough that running all three makes sense for any production application you care about.

The practical setup for a team running all three:

Telescope is a dev dependency, so it only exists locally and in staging. Pulse and Nightwatch both live in production. Pulse runs php artisan pulse:work as a supervised daemon for metric aggregation. Nightwatch runs php artisan nightwatch:agent as a supervised daemon for event collection. The two agents don't interfere with each other.

One thing to do immediately if you add Nightwatch: disable it in your test environment. Add NIGHTWATCH_ENABLED=false to your phpunit.xml or test .env. You don't want test runs burning through your event quota.

	Telescope	Pulse	Nightwatch
Cost	Free (open source)	Free (open source)	Free plan + from $20/mo (Pro)
Environment	Local / staging only	Production-safe	Production-safe
Installation	Composer package	Composer package	Composer package + cloud account
What it tracks	Every request, query, job, mail, notification, dump	Aggregated metrics: slow queries, CPU, queue depth, cache	Individual requests, exceptions, jobs, queries, outgoing HTTP, scheduler
Data granularity	Individual request-level detail	Sampled aggregates over time windows	Every individual event with full context
Alerting	None	None	Yes: Slack, Linear, webhooks
Self-hosted vs cloud	Self-hosted	Self-hosted	Cloud (SaaS)
Best for	Debugging during development	Production health dashboard	Investigating production incidents

Setting Up Nightwatch on Laravel Forge (The Quickest Path)

If you're on Forge, Nightwatch has a one-click integration. In your Forge site settings, find the Nightwatch section, enter your environment token, and Forge automatically creates the supervisor daemon, restarts it if it crashes, and wires up the environment variables. The whole thing takes about 90 seconds.

For a non-Forge server, add the Supervisor config manually. Create /etc/supervisor/conf.d/nightwatch.conf:

[program:nightwatch]
process_name=%(program_name)s
command=php /var/www/your-app/artisan nightwatch:agent
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/your-app/storage/logs/nightwatch.log

Then run sudo supervisorctl reread && sudo supervisorctl update && sudo supervisorctl start nightwatch.

This is the same pattern you'd use for Horizon or any other long-running Laravel process. If you're already running Horizon for your queues, adding Nightwatch follows the exact same playbook. The Laravel queue jobs guide covers this Supervisor setup in detail if you need a full walkthrough.

Frequently Asked Questions

Is Nightwatch worth it if I'm already using Sentry?

Sentry is excellent at exception tracking specifically. It won't give you slow query data, queue depth, cache miss rates, or scheduler health. Nightwatch gives you the full picture including exceptions. They can run side by side if you want Sentry's issue tracking workflow, but Nightwatch alone covers more ground.

Does Pulse replace Telescope?

No. Pulse is for production metrics. Telescope is for local debugging. They serve completely different purposes and run in different environments.

Can Nightwatch run on shared hosting?

The Nightwatch agent requires a long-running process, which most shared hosts don't support. You need a VPS, a Forge-managed server, Laravel Cloud, or a container environment. If you're on shared hosting, Pulse is your only production monitoring option.

What counts as an "event" in Nightwatch's quota?

Each of these counts as one event: an HTTP request, an outgoing HTTP request, a queue job execution, an Eloquent query, a mail send, a notification dispatch, a scheduled task run, a cache operation, an Artisan command run, and an exception. On a typical request that fires 12 queries, that's 13 events (1 request + 12 queries). Use the sampling configuration to manage quota on high-traffic endpoints.

Should I disable Nightwatch in local development?

You can run it locally with a dedicated development environment in your Nightwatch account, but it will burn through your free quota unnecessarily. Set NIGHTWATCH_ENABLED=false in your local .env and use Telescope locally instead. That's what it's built for.

Nightwatch in Practice: Where It Earns Its Keep

The tools that benefit most from Nightwatch in production are the ones with the most moving parts. If you're running a Laravel REST API with multiple consumers, Nightwatch shows you which endpoints are slow for which users, and which outgoing HTTP calls to third-party services are dragging response times down.

If you're building admin-heavy SaaS applications with Filament, Nightwatch is especially useful. Admin panels tend to run complex Eloquent queries against large datasets, and the N+1 issues that are invisible in development with a handful of records become obvious with real production data. The complete Laravel + Filament SaaS guide covers the kind of query complexity that benefits most from production observability. When you can see in Nightwatch that your Filament resource list is firing 60 queries per page load on a table with 10,000 rows, you know exactly where to add eager loading and which relationship to optimise first.

The most common mistake Laravel developers make with monitoring is treating it as binary: either you have it or you don't. The reality is that Telescope, Pulse, and Nightwatch solve three different problems at three different points in the development lifecycle. Start with Telescope locally. Add Pulse to production for free. Add Nightwatch when you have users who will notice when something breaks.

Building a Laravel app and not sure which of these fits where you are right now? Get in touch and I'm happy to talk through your setup.

Laravel Pest 4 Testing: The Complete Guide for Laravel 13 Developers

Hafiz — Fri, 10 Apr 2026 06:28:47 +0000

If you've shipped 10, 20, even 50 Laravel projects and never written a single test, you're not alone. Testing in PHP has a reputation for being verbose and a bit joyless. Then Pest came along and made it something developers actually reach for. With Pest 4 and Laravel 13, there's no good reason to keep putting it off.

This guide builds a real tested feature from scratch: an authenticated REST API for blog posts. By the end you'll have feature tests, validation tests using datasets, and arch tests running in parallel. No toy examples. Just the exact setup I'd use in a production Laravel 13 app.

Why Pest Instead of PHPUnit

PHPUnit is the standard. It works. But look at what a basic PHPUnit test actually looks like:

class PostTest extends TestCase
{
    public function test_unauthenticated_user_cannot_access_posts(): void
    {
        $response = $this->getJson('/api/posts');
        $response->assertStatus(401);
    }
}

Now look at the Pest equivalent:

it('blocks unauthenticated users from the posts endpoint', function () {
    getJson('/api/posts')->assertUnauthorized();
});

Same result. Half the code. It reads like a sentence, which matters more than you'd think when you're scanning a failing test suite at 11pm trying to figure out what broke.

But syntax isn't the only reason to switch. The expectation API is where Pest really stands out. Instead of scattered assertEquals calls with arguments in the wrong order (expected or actual first? nobody ever remembers), you write assertions that chain left to right:

expect($user->name)->toBe('Hafiz');
expect($post->published_at)->not->toBeNull();
expect($response->json('data'))->toHaveCount(5);

This reads the way you think about the assertion. The value comes first, the expectation follows. It's a small change that compounds across hundreds of tests and makes the suite much easier to scan at a glance.

Pest 4 runs on PHPUnit 12 under the hood. It's not a different framework. It's a better interface to the same machinery. You can mix Pest and PHPUnit test classes in the same project, so there's no big bang migration. You start using it today on new tests, convert old files when you touch them, and the existing ones keep working.

Pest was created by Nuno Maduro, a Laravel core team member, so the Laravel integration is first-class from the start. actingAs(), RefreshDatabase, HTTP assertions, Livewire testing, Filament testing. Everything works exactly as you'd expect, with no adapter layer in the way.

Installing Pest 4 in a Laravel 13 Project

Requirements: PHP 8.3+ and any of Laravel 11, 12, or 13. The pest-plugin-laravel package supports all three versions.

Start by swapping out PHPUnit. The --with-all-dependencies flag handles any shared dependency resolution:

composer remove phpunit/phpunit
composer require pestphp/pest --dev --with-all-dependencies
composer require pestphp/pest-plugin-laravel --dev

Then initialise Pest in your project:

./vendor/bin/pest --init

This creates tests/Pest.php, the central configuration file for your entire test suite. You can find a full list of Pest-related Artisan commands alongside all the other generator commands in the Laravel Artisan Commands reference.

Run ./vendor/bin/pest and you'll see the two example tests that come with a fresh Laravel install passing immediately under Pest syntax. That's it for setup.

Configure Pest.php Before Writing Anything

The tests/Pest.php file is where global configuration lives. Set it up before writing your first test and you'll avoid repeating boilerplate across every file.

<?php

use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

uses(TestCase::class, RefreshDatabase::class)->in('Feature');
uses(TestCase::class)->in('Unit');

RefreshDatabase wraps each test in a database transaction and rolls it back when the test finishes. Your database starts clean for every test. Because it's configured in Pest.php, you never have to declare it in individual test files.

You can also define reusable helper functions here that any test can use:

function authenticatedUser(array $attributes = []): User
{
    return User::factory()->create($attributes);
}

Then anywhere in your feature tests: actingAs(authenticatedUser()). One line, no repetition.

The Feature We're Testing

For this tutorial we're building a simple posts API. Two endpoints: list posts, create a post. Both require Sanctum authentication.

The controller:

// app/Http/Controllers/Api/PostController.php

public function index(): JsonResponse
{
    $posts = Post::latest()->get();
    return response()->json($posts);
}

public function store(StorePostRequest $request): JsonResponse
{
    $post = Post::create($request->validated());
    return response()->json($post, 201);
}

Routes:

Route::middleware('auth:sanctum')->group(function () {
    Route::get('/posts', [PostController::class, 'index']);
    Route::post('/posts', [PostController::class, 'store']);
});

The form request validates incoming data:

// app/Http/Requests/StorePostRequest.php

public function rules(): array
{
    return [
        'title' => ['required', 'string', 'max:255'],
        'body'  => ['required', 'string'],
    ];
}

This is the kind of setup you'll find in almost any Laravel REST API. Simple enough to follow clearly, realistic enough to cover the patterns that actually come up in production work.

Writing Your First Feature Tests

Create the test file:

php artisan make:test Api/PostTest

Because Pest.php already applies the test case and RefreshDatabase, your test file stays completely focused:

<?php

use App\Models\Post;
use App\Models\User;

it('blocks unauthenticated users from listing posts', function () {
    getJson('/api/posts')->assertUnauthorized();
});

it('blocks unauthenticated users from creating posts', function () {
    postJson('/api/posts', [])->assertUnauthorized();
});

it('returns all posts for an authenticated user', function () {
    $user = User::factory()->create();
    Post::factory()->count(3)->create();

    actingAs($user)
        ->getJson('/api/posts')
        ->assertOk()
        ->assertJsonCount(3);
});

it('creates a post with valid data', function () {
    $user = User::factory()->create();

    $payload = [
        'title' => 'How I Finally Shipped My SaaS',
        'body'  => 'It took three rewrites and one epiphany.',
    ];

    actingAs($user)
        ->postJson('/api/posts', $payload)
        ->assertCreated()
        ->assertJsonFragment(['title' => 'How I Finally Shipped My SaaS']);

    expect(Post::count())->toBe(1);
});

A few things worth highlighting here. No class, no public function, no $this for assertions. The HTTP helpers (actingAs(), getJson(), postJson()) come in globally through the Pest Laravel plugin.

Use named assertions over status codes. assertUnauthorized() tells you what the test expects. assertStatus(401) tells you a number. Both pass on a 401 response, but only one communicates intent to the developer reading it six months later. The same logic applies to assertOk(), assertCreated(), and assertUnprocessable().

The expect(Post::count())->toBe(1) line at the end is important. It verifies the database was actually written to, not just that the response body looked right. HTTP assertions alone don't prove persistence happened.

What Actually Deserves a Test

New developers often freeze on this question. The answer isn't about percentages. It's about behaviour.

Test the things users would notice if they broke. Authentication, authorisation, validation, business logic, queue jobs. If a bug in that code would cause a user to see wrong data, access something they shouldn't, or submit something they shouldn't be able to, it needs a test. That's a reliable filter.

Three categories always worth covering:

Authentication and authorisation. Write tests that prove unauthenticated requests get rejected and that authorised users only access what they're allowed to. This is the most common source of security issues in web apps, and the easiest thing to accidentally break during a refactor.

Validation rules. Form requests with rules need tests, especially for edge cases: empty strings, strings that are one character over the limit, missing required fields. Datasets make this practical without multiplying boilerplate, as you'll see shortly.

Business logic in service classes or actions. If you've extracted logic out of a controller into a dedicated class because it's complex, that class deserves unit tests. The complexity is exactly what makes it risky to change without coverage.

What you can skip: Laravel itself, which is tested thoroughly by its own team. Simple Eloquent accessors that just return a property. One-line controller methods that delegate entirely to a service.

The highest-value tests in a Laravel app are feature-level HTTP tests. One test that calls actingAs($user)->postJson(...) simultaneously exercises the route, middleware, controller, form request, model, and database layer. That's significant coverage for one test function. Start there before reaching for unit tests on individual methods.

Shared Setup with beforeEach

When multiple tests in the same file need the same starting state, use beforeEach() rather than repeating setup code in every test:

<?php

use App\Models\Post;
use App\Models\User;

beforeEach(function () {
    $this->user = User::factory()->create();
});

it('returns posts for the authenticated user', function () {
    Post::factory()->count(5)->create();

    actingAs($this->user)
        ->getJson('/api/posts')
        ->assertOk()
        ->assertJsonCount(5);
});

it('creates a post', function () {
    actingAs($this->user)
        ->postJson('/api/posts', [
            'title' => 'Test Post',
            'body'  => 'Test body.',
        ])
        ->assertCreated();

    expect(Post::count())->toBe(1);
});

beforeEach() runs before every test in the file. State set inside it is available on $this. This keeps tests short and focused: each one only shows what's unique about that particular assertion. The shared setup disappears into the background where it belongs.

Datasets for Validation Testing

This is the feature that makes validation testing actually maintainable at scale. PHPUnit has data providers that do the same thing, but Pest's syntax is significantly cleaner and the test output is far more readable.

Instead of writing a separate test function for every invalid input combination:

it('rejects invalid post data', function (array $payload, string $field) {
    $user = User::factory()->create();

    actingAs($user)
        ->postJson('/api/posts', $payload)
        ->assertUnprocessable()
        ->assertJsonValidationErrors([$field]);
})->with([
    'missing title'  => [['body' => 'Some body text'], 'title'],
    'missing body'   => [['title' => 'Some title'], 'body'],
    'empty title'    => [['title' => '', 'body' => 'Some body text'], 'title'],
    'title too long' => [['title' => str_repeat('a', 256), 'body' => 'Some body text'], 'title'],
]);

Pest runs this four times, once per dataset entry. The named keys ('missing title', 'missing body', and so on) appear directly in the test output, so failures are immediately obvious without digging through a stack trace. You wrote one function. You got four test cases.

For datasets you'll reuse across multiple files, extract them into tests/Datasets/Posts.php:

<?php

dataset('invalid_post_payloads', [
    'missing title' => [['body' => 'Some body text'], 'title'],
    'missing body'  => [['title' => 'Some title'], 'body'],
    'empty title'   => [['title' => '', 'body' => 'Some body text'], 'title'],
]);

Then reference by name from any test file:

it('rejects invalid post data', function (array $payload, string $field) {
    // ...
})->with('invalid_post_payloads');

This pattern works well in larger SaaS applications where the same validation rules appear across multiple endpoints. If you're building something with significant admin-side data management, this kind of test organisation pays off fast. The complete Laravel + Filament SaaS guide shows the kind of app complexity where shared datasets start to matter.

Architecture Testing: The Feature Nobody Covers

Most Pest tutorials skip this section entirely. That's a shame because it's one of the most valuable things in the whole framework.

Arch tests don't test your application's behaviour. They test its structure. Think of them as automated code review that runs on every commit. You define the rules once and Pest enforces them permanently, without anyone needing to remember to check.

Create tests/Arch/AppTest.php:

<?php

arch('no debug statements left in the codebase')
    ->expect('App')
    ->not->toUse(['dd', 'dump', 'var_dump', 'ray']);

arch('models extend Eloquent')
    ->expect('App\Models')
    ->toExtend('Illuminate\Database\Eloquent\Model')
    ->toBeClasses();

arch('jobs implement ShouldQueue')
    ->expect('App\Jobs')
    ->toImplement('Illuminate\Contracts\Queue\ShouldQueue');

arch('controllers stay in the HTTP layer')
    ->expect('App\Http\Controllers')
    ->toOnlyBeUsedIn('App\Http');

arch('strict types declared everywhere')
    ->expect('App')
    ->toUseStrictTypes();

The dd/dump rule catches more than you'd expect. There's always one lurking in a big codebase. Pest finds it instantly and names the exact file and line number. The toUseStrictTypes() rule is the unforgiving one: any file in App missing declare(strict_types=1) breaks the build immediately.

The jobs rule pairs naturally with proper queue architecture. If you're processing background jobs at scale, like the patterns covered in the Laravel queue jobs guide, this arch test makes sure nothing enters the Jobs folder without implementing ShouldQueue.

You can also reach for Pest's built-in presets that bundle sensible defaults into a single call:

arch()->preset()->php();
arch()->preset()->security()->ignoring('md5');
arch()->preset()->laravel();

The security preset catches eval(), system(), shell_exec(), and other calls you never want in production code. The laravel preset enforces framework conventions like keeping Facades out of domain classes. The php preset handles strict_types, suspicious characters in strings, and other language-level concerns.

The ->ignoring() modifier lets you exclude specific namespaces when a rule doesn't apply to your context:

arch()->preset()->security()->ignoring('App\Services\LegacyBridge');

None of the presets are all-or-nothing. Use what fits, skip what doesn't.

Running Tests in Parallel

One flag changes the runtime dramatically:

./vendor/bin/pest --parallel

Pest distributes the suite across multiple processes and runs them simultaneously. On a typical Laravel app with 50-100 tests, this cuts runtime roughly in half. The savings compound as the suite grows.

For CI with GitHub Actions, combine parallel with sharding to split across multiple machines:

./vendor/bin/pest --parallel --shard=1/4

Workflow configuration:

strategy:
  matrix:
    shard: [1, 2, 3, 4]

steps:
  - name: Run tests
    run: ./vendor/bin/pest --parallel --shard=${{ matrix.shard }}/4

Four machines, four shards. A 4-minute test suite becomes a 60-second one. The setup takes about 10 minutes and pays back on the first push.

One thing to check before enabling parallel: your tests need to be database-isolated. RefreshDatabase handles this correctly and is the right choice for parallel runs. If you're managing database state in other ways, verify that tests can't bleed into each other first.

Type Coverage

Install the plugin:

composer require pestphp/pest-plugin-type-coverage --dev

Run it with a minimum threshold:

./vendor/bin/pest --type-coverage --min=90

Pest 4 made the type coverage engine 2x faster on first run and instant on subsequent runs. It also added sharding support, so large codebases don't see a significant CI overhead.

This isn't a replacement for PHPStan or Psalm, but it's a fast sanity check with zero configuration overhead. If you're not running any static analysis yet, this is a practical first step toward it.

Frequently Asked Questions

Does Pest 4 work with my existing PHPUnit tests?

Yes. Pest runs on PHPUnit 12 under the hood, so existing test classes keep working without any changes. Run ./vendor/bin/pest and it picks up both. You can migrate files gradually or leave old ones as-is.

Can I use Pest with Livewire and Filament?

Absolutely. Livewire::test(), Filament's test helpers, actingAs(), and the full Laravel testing API all work exactly as they do in PHPUnit. No adapter, no wrapper. It just works.

What's the difference between it() and test()?

Nothing functional. it('creates a post') reads as a behaviour description. test('post creation') is more PHPUnit-style. I use it() for behaviour tests and test() for unit-level tests, but that's personal preference, not a rule.

Is arch testing worth adding to a small project?

Yes, often more so than on large ones. On a small project the rules act as a forcing function, keeping structure clean from the start instead of creating expensive cleanup work later. The debug statement rule alone has saved me from at least three embarrassing incidents.

How do I run just one test or one file?

Run a specific file:

./vendor/bin/pest tests/Feature/Api/PostTest.php

Filter by test description: ""

./vendor/bin/pest --filter "creates a post"

Run a specific group:

./vendor/bin/pest --group api

The --filter flag accepts partial strings, so --filter "creates" matches any test whose description contains the word.

Testing isn't about achieving 100% coverage. It's about having enough confidence to deploy on a Friday without holding your breath. Pest 4 makes that bar significantly lower to clear, and Laravel 13 gives you a clean enough test setup to actually maintain long term.

If you're building a Laravel SaaS and want a second opinion on your testing strategy before things get complicated, reach out. Happy to take a look at what you've got.

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.

DEV Community: Hafiz

How Laravel Events, Listeners, and Observers Actually Work (And When to Use Each)

What Problem Are We Actually Solving?

Events: The Signal

Listeners: What Reacts

Auto-Discovery in Laravel 11+

Queued Listeners

After Database Commit

Observers: Model Lifecycle Hooks

The Full List of Observer Methods

What Goes in an Observer vs a Listener

A Real-World Pattern: User Registration

Testing Events and Listeners

Artisan Commands Reference

Common Mistakes

FAQ

Conclusion

How I Built a macOS Menu Bar App with NativePHP, Laravel 12 and Livewire 4

Why NativePHP and Why Laravel 12, Not 13

The Core Architecture: Two Timers, Not One

Problem 1: The Dual-Database Trap

Problem 2: Not All NativePHP Facades Work From Child Processes

Problem 3: URL Resolution in Artisan Context

Problem 4: Multi-Screen Overlay

Distributing the App

What I Shipped vs What I Cut

What's Next

FAQ

Conclusion

Laravel Policies vs Gates: The Complete Authorization Guide

Gates vs Policies: The One-Sentence Version

Gates: Quick Authorization Without a Model

Policies: Authorization Organized Around a Model

Registering Policies: Three Ways in Laravel 13

How to Call a Policy

The Policy before() Method: Super-Admin Shortcut

Returning Rich Responses Instead of Booleans

Authorization in Blade

Authorization and Inertia: Sharing Policy Data with the Frontend

The Mistakes Worth Knowing

When Spatie Permission Fits In

Frequently Asked Questions

Laravel Telescope vs Pulse vs Nightwatch: Which Monitoring Tool Do You Actually Need?

What Each Tool Is Actually Solving

Laravel Telescope: Your Local Debugging Companion

Laravel Pulse: The Production Health Dashboard

Laravel Nightwatch: Full Production Observability

How to Pick the Right Tool

Can You Use All Three Together?

Setting Up Nightwatch on Laravel Forge (The Quickest Path)

Frequently Asked Questions

Nightwatch in Practice: Where It Earns Its Keep

Laravel Pest 4 Testing: The Complete Guide for Laravel 13 Developers

Why Pest Instead of PHPUnit

Installing Pest 4 in a Laravel 13 Project

Configure Pest.php Before Writing Anything

The Feature We're Testing

Writing Your First Feature Tests

What Actually Deserves a Test

Shared Setup with beforeEach

Datasets for Validation Testing

Architecture Testing: The Feature Nobody Covers

Running Tests in Parallel

Type Coverage

Frequently Asked Questions

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?

The Policy `before()` Method: Super-Admin Shortcut

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

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

`Inertia::lazy()` is removed

The `future` config block is gone