DEV Community: Hafiz

Laravel Octane in 2026: FrankenPHP vs Swoole vs RoadRunner

Hafiz — Wed, 08 Jul 2026 12:07:04 +0000

In April 2026, a carefully controlled benchmark put all three Laravel Octane servers through a real Laravel workload. RoadRunner more than doubled PHP-FPM's throughput. Swoole, the server with a decade-long reputation as PHP's performance monster, finished dead last. Below plain FPM.

A month later, a hosting company that has migrated dozens of Laravel apps to Octane published their production numbers. Their verdict on Swoole: it's their fastest option for API-heavy workloads, and they deploy it deliberately for exactly those customers.

Both sources are competent. Both published their methodology. Both are right.

That contradiction is the most useful thing you can learn about choosing an Octane server, because it tells you the question "which server is fastest?" has no universal answer. The useful question is which server matches your workload, your deployment model, and your team's appetite for operational complexity. This post covers what Octane actually changes, how the three servers differ architecturally, why the benchmarks disagree, and a decision framework you can apply to your own app. I'll also tell you when the honest answer is to not use Octane at all.

What Octane Actually Changes

A standard Laravel request on PHP-FPM boots the entire framework from zero. Service providers register, config loads, the container wires up, and then your code finally runs. For a typical app that boot costs 10 to 30ms per request, more if you're carrying Filament, Nova, or a heavy stack of packages. Then the request ends and everything is thrown away.

Octane inverts that. The application boots once per worker, stays resident in memory, and each incoming request reuses the already-built framework. The boot tax disappears from every request except the first.

That's the whole trick. Octane doesn't make your database queries faster, doesn't cache your responses, and doesn't parallelize your code (with one Swoole-shaped exception we'll get to). If your endpoint spends 200ms in MySQL, Octane saves you the 20ms boot and leaves the 200ms untouched. This is why I tell people to read their profiler before reading Octane benchmarks: if framework bootstrap isn't a meaningful slice of your response time, start with query optimization instead. It's usually the bigger win and it carries zero migration risk.

Installation is the same regardless of server:

composer require laravel/octane

php artisan octane:install --server=frankenphp
# or --server=swoole, --server=roadrunner

Octane supports four servers: FrankenPHP, Swoole, Open Swoole, and RoadRunner. Open Swoole is a community fork with the same Octane feature set as Swoole, so practically the choice is between three architectures.

Three Servers, Three Architectures

The performance and failure characteristics of each server come directly from how a request physically reaches your PHP code.

FrankenPHP is a Go binary built on the Caddy web server, with the official PHP interpreter embedded directly into the process via cgo. There's no proxy hop and no inter-process communication: Caddy accepts the request and hands it to a PHP thread inside the same process, where your booted Laravel app is waiting. Because Caddy is the web server, you get HTTP/2, HTTP/3, and automatic HTTPS without putting Nginx in front. Octane downloads the FrankenPHP binary for you when you pick it during install.

RoadRunner is also written in Go, but it takes the opposite approach to integration. It runs as a standalone server binary that manages a pool of ordinary PHP processes, forwarding requests to them over a fast RPC protocol. Your PHP workers are regular processes with real isolation: if one worker corrupts its state or dies, RoadRunner respawns it and the others never notice. It's been doing this job since 2018 and has the most mature plugin ecosystem of the three (queues, gRPC, key-value storage).

Swoole is different in kind, and the difference goes deeper than plumbing. It's a C extension installed via PECL that replaces PHP's execution model with an event loop and coroutines, closer to Node.js than to classic PHP. When your code hits blocking I/O, Swoole can suspend that coroutine and run another request on the same worker. That's a capability the other two simply don't have, and it's also why Swoole demands the most from your code.

The architectural differences cascade into everything else, so let's take each server on its own terms.

FrankenPHP: The Deployment Story

FrankenPHP is the youngest of the three, released in late 2023 and hardened through 2024 and 2025. What it changed isn't raw speed. It's how little infrastructure you need.

One binary is your web server, TLS manager, static file server, and PHP runtime. A production Dockerfile is this small:

FROM dunglas/frankenphp

COPY . /app
WORKDIR /app

RUN composer install --no-dev --optimize-autoloader

ENTRYPOINT ["php", "artisan", "octane:frankenphp"]

One container, one port, no Nginx, no supervisor config. If you deploy to Cloud Run, Kubernetes, or any autoscaling container platform, that shape maps perfectly. And on classic VPS setups, HTTPS with automatic certificate renewal comes from Caddy for free. When you need to go beyond the defaults, php artisan octane:start --server=frankenphp --caddyfile=/path/to/Caddyfile gives you full Caddy configuration.

The honest trade-offs: it's the youngest option, and youth shows. One hosting provider that runs it in production reports hitting two memory-leak regressions over 18 months, both fixed promptly upstream, but that's a different stability track record than RoadRunner's. Configuration is Caddyfile syntax rather than the Nginx configs most Laravel developers have committed to muscle memory. And in benchmarks driven by HTTP/1.0 tools, FrankenPHP looks unremarkable, for reasons we'll get to.

Swoole: The Ceiling and the Cliff

Swoole has the highest performance ceiling of the three, and the steepest cliff next to it.

The ceiling comes from coroutines. While FrankenPHP and RoadRunner workers handle one request at a time, Swoole's runtime can juggle many, suspending whichever one is waiting on the database. For endpoints that fan out to multiple upstream services, Octane exposes this directly:

use Laravel\Octane\Facades\Octane;

[$orders, $stats, $flags] = Octane::concurrently([
    fn () => Order::recent()->get(),
    fn () => Cache::get('dashboard:stats'),
    fn () => Feature::all(),
]);

Three operations, dispatched to Swoole's task workers and executed concurrently while your request waits for the results. You size that pool with --task-workers on octane:start. Octane::concurrently(), ticks, intervals, and the Swoole-backed Octane cache and tables are exclusive to Swoole and Open Swoole. Neither FrankenPHP nor RoadRunner can offer them because their workers don't have a coroutine scheduler.

The cliff: Swoole changes PHP's execution semantics, and code written for classic synchronous PHP doesn't always survive the change. Extensions can conflict, some packages misbehave inside coroutines, and Xdebug famously doesn't cooperate, so production profiling means Blackfire or Tideways. It's also an extension you compile via PECL rather than a binary Octane downloads for you, which makes your Docker images and CI more bespoke. The production shops that get the most from Swoole recycle workers aggressively (max_requests around 250 versus 500 on RoadRunner) because memory grows faster.

My blunt read: Swoole is a specialist's tool. If you're not going to use concurrently() or your workloads don't have real I/O concurrency, you're paying Swoole's complexity tax for a capability you never invoke.

RoadRunner: The Boring Choice, Compliment Intended

RoadRunner wins on exactly one axis, and it happens to be the axis that matters most for a lot of teams: predictability.

Its worker isolation model means a leak or crash in one PHP process can't poison its siblings. The Go server respawns dead workers and traffic continues. It has seven-plus years of production history, and its configuration lives in a plain YAML file that does what it says. In the April 2026 benchmark that embarrassed Swoole, RoadRunner delivered 111.6% more throughput than PHP-FPM on the same hardware with a 41% lower p99. Not because it's exotic, but because boot-once plus process isolation is a simple model that performs consistently across workload shapes.

Setup needs two extra packages alongside Octane, and the rr binary is offered for download on first start:

composer require laravel/octane spiral/roadrunner-cli spiral/roadrunner-http

php artisan octane:start --server=roadrunner

What you give up: no HTTP/3 or automatic HTTPS (you'll keep Nginx or Caddy in front), no coroutines, and a plugin ecosystem (gRPC, queues) that most Laravel apps never touch because Laravel's own queue system already covers that ground.

Why the Benchmarks Disagree

Back to the contradiction from the intro, because resolving it is what makes you dangerous in this decision.

The April 2026 benchmark that placed Swoole below PHP-FPM used ab, a load tool that speaks HTTP/1.0 with short-lived connections, against a light-I/O Laravel route. Two things follow. First, Swoole's entire advantage is concurrent I/O scheduling; on a workload with barely any I/O wait, its coroutine scheduler is pure overhead, so it loses. Second, FrankenPHP's HTTP/2 multiplexing never gets exercised over HTTP/1.0, so it benchmarks like plain FPM while its real-world strength stays invisible.

Meanwhile, the production shop reporting Swoole as their fastest option runs it on API workloads full of upstream calls and database fan-out, with concurrently() in active use. That's precisely the workload where coroutines pay. Same server, opposite conclusion, and both measurements are honest.

The lesson generalizes: every Octane benchmark measures its own workload and tooling as much as it measures the server. A hosting provider's before-and-after on a real authenticated endpoint (4 to 5x throughput moving FPM to FrankenPHP with Octane) is more predictive for a typical app than any synthetic table. And your own app benchmarked for an afternoon beats both. So treat published numbers as bounds, not rankings.

The Decision Framework

Here's how I'd actually choose in 2026.

Pick FrankenPHP if you deploy in containers or want the simplest possible stack. Cloud Run, Kubernetes, Docker-based platforms, or a VPS where you'd rather not maintain Nginx. It's also the right default if you're new to Octane: the binary auto-installs, and the single-process model has the fewest moving parts to reason about.

Pick RoadRunner if you're migrating a large existing app and stability is the priority. The process isolation gives you the softest failure modes while you shake out the state bugs every migration surfaces. It's the conservative choice, and for a revenue-carrying monolith, conservative is correct.

Pick Swoole only if you'll use what makes it Swoole. Many concurrent upstream calls per request, real fan-out, a team comfortable auditing packages for coroutine safety. Then the ceiling is real and nothing else reaches it.

Pick none of them if your profiler says boot time isn't your problem. A 300ms endpoint that spends 260ms in queries gets nothing meaningful from Octane. The cheap performance wins come first; Octane is what you reach for after them, when traffic and infrastructure cost make the boot tax worth eliminating. My own apps still run plain FPM on small droplets, and that's deliberate: at their traffic, Octane would add operational surface without moving anything a user can feel. The infrastructure cost math only tips toward Octane when you're scaling servers to handle load that's mostly boot overhead.

The Gotchas That Apply to All Three

Whichever server you pick, the migration risk is identical, because it comes from Octane's model rather than the server underneath.

Your app now lives in memory across requests. Anything static, any singleton, any memoized value persists into the next request. The classic bug is a package caching the authenticated user in a singleton, so request N+1 sees request N's user. Audit your singletons, use Octane's flush hooks for anything request-scoped, and test with two different logged-in users hitting the same worker.

Memory grows. Every long-running PHP process leaks a little, so set --max-requests and let workers recycle themselves. Deploys change too: php artisan octane:reload swaps workers with zero downtime, and it belongs in your deploy script (the full command list is in the Laravel Artisan Commands reference). And remember each worker handles one request at a time (Swoole's coroutines aside), so a slow request blocks a worker slot. Anything slow belongs on a queue, same as always.

FAQ

Is Laravel Octane faster than PHP-FPM for every application?

No. Octane eliminates the framework boot cost, roughly 10 to 30ms per request on a typical app. If your response time is dominated by database queries or external APIs, Octane changes almost nothing. Profile first: it pays off when boot time is a meaningful fraction of your responses and traffic is high enough that the saved milliseconds compound into fewer servers.

Which Octane server is easiest to set up?

FrankenPHP. Octane downloads the binary for you during octane:install, and because it bundles Caddy you don't need a separate web server for HTTPS, HTTP/2, or HTTP/3. RoadRunner is close behind (two extra Composer packages, auto-downloaded binary). Swoole requires compiling a PECL extension, which makes it the most involved.

Do I need to rewrite my code for Octane?

Rewrite, no. Audit, yes. Static properties, singletons, and anything memoized will persist between requests, which is the source of nearly all Octane bugs. Most well-structured apps need a handful of fixes, not an architectural change. Third-party packages are the bigger unknown, so test the critical paths under a single worker with --max-requests=1 to surface state leaks quickly.

What about Open Swoole?

Fully supported by Octane and functionally equivalent for Octane's purposes: you get the same concurrent tasks, ticks, and intervals as Swoole. It's a community fork, so the choice between them usually comes down to which extension your platform and PHP version support more cleanly.

Does Octane work with Laravel 13?

Yes. Octane is a first-party package and the Laravel 13 documentation covers all four servers. Install with composer require laravel/octane and pick your server during octane:install.

Wrapping Up

The 2026 Octane question isn't "which server wins the benchmark". It's a matching problem. FrankenPHP matches container-native deployments and small teams that want one binary doing everything. RoadRunner matches big migrations where boring is a feature. Swoole matches I/O-heavy APIs run by teams who'll actually use its concurrency. And plain PHP-FPM still matches every app whose profiler says boot time isn't the bottleneck, which is more apps than the benchmark posts admit.

Pick by workload, verify with an afternoon of load testing on your own endpoints, and be suspicious of any comparison (including this one) that hands you a single winner.

Planning an Octane migration for a production Laravel app and want a second pair of eyes on the state-leak audit and server choice? Let's talk.

Laravel Route Metadata: 5 Real Problems It Finally Solves

Hafiz — Mon, 06 Jul 2026 07:08:27 +0000

When route metadata got merged into Laravel 13.17, the first comment on the pull request was a long-time framework contributor asking what it's actually for. His follow-up was blunter: "IMO none of this behavior belongs on the Route, but oh well."

I get the skepticism. On paper, "attach arbitrary data to routes" sounds like a solution looking for a problem. But here's the thing: Laravel developers have been attaching arbitrary data to routes for years. We just did it badly. Config files keyed by route name. Abused ->defaults() calls that leak into controller parameters. Naming conventions like admin.reports.legacy.v1 that encode three different facts into a string and pray nobody renames the route. A GitHub discussion from 2022 asked for exactly this feature and got zero answers.

So the question isn't whether attaching data to routes is a good idea. You're already doing it. The question is whether you keep doing it through hacks or use the supported, cache-safe API that ships in every Laravel app from 13.17 onwards.

This post covers what shipped, the merge rules that make groups powerful, and five concrete problems where route metadata replaces something uglier. Working code for each.

What Laravel 13.17 Actually Shipped

Three methods. That's the whole API.

metadata() attaches an array of data to a route or a group:

use App\Http\Controllers\UserController;
use Illuminate\Support\Facades\Route;

Route::get('/users', [UserController::class, 'index'])
    ->metadata(['head' => ['title' => 'Users']]);

getMetadata() reads it back from the resolved route, with dot notation and an optional default:

$request->route()->getMetadata('head.title');           // 'Users'
$request->route()->getMetadata('head.author', 'Hafiz'); // 'Hafiz' (fallback)
$request->route()->getMetadata();                       // the full array

And setMetadata() replaces everything instead of merging, for the rare case where you want a route to opt out of whatever its group defined.

The part that makes this more than a glorified array property: metadata is stored on the route action under a dedicated metadata key. That means it flows through the existing route group logic and gets serialized by route:cache. Your metadata survives production route caching with zero extra work. Anything you'd find with php artisan route:list still resolves the same way (the full command reference is in the Laravel Artisan Commands guide if you need it).

Resources and singletons work too:

Route::resource('users', UserController::class)
    ->metadata(['head' => ['title' => 'Users']]);

Every route the resource generates carries the metadata. Before 13.17 there was no clean way to do this, because resource routes are registered in a pending state and you couldn't hook data onto them mid-registration.

The merge rules worth memorizing

Group metadata cascades down to every route inside the group. The merge follows two rules:

Associative arrays merge recursively. Nested groups layer values on top of each other.
Lists and scalar values replace what they inherit.

Here's both rules in one example:

Route::metadata(['head' => ['robots' => ['noindex'], 'author' => 'Hafiz']])
    ->group(function () {
        Route::get('/users', [UserController::class, 'index'])
            ->metadata(['head' => ['title' => 'Users']]);
    });

// $request->route()->getMetadata('head') returns:
// [
//     'robots' => ['noindex'],  // inherited from the group
//     'author' => 'Hafiz',      // inherited from the group
//     'title'  => 'Users',      // added by the route
// ]

The route added title without losing robots or author. But if the route had defined its own robots list, it would have replaced the group's list entirely, not merged with it. Lists replace. Associative keys merge. Once that clicks, the whole feature is predictable.

How We Hacked This Before

Every workaround for this problem had a real cost. Quick tour, because recognizing your own code in this list is the fastest way to see why the feature matters.

Custom keys in the action array. You could always smuggle extra keys into the route action and read them back with getAction(). It worked for single routes. It fell apart for groups, resources, and singletons, because there was no supported way to carry the data through the route-building pipeline. That's the exact gap the PR closes.

Abusing ->defaults(). Route defaults exist to provide default values for route parameters. Stuffing page titles or permission strings in there technically works, until a controller method with a matching parameter name silently receives your metadata as an argument. I've debugged that one. Not fun.

Config maps keyed by route name. A config/seo.php file with a hundred route names mapped to titles and descriptions. Now every route rename is a two-file change, nothing enforces the mapping stays in sync, and the data lives nowhere near the route it describes.

Encoding facts into route names. Names like api.v1.legacy.reports.index where "v1" and "legacy" are load-bearing. String parsing as architecture.

Route metadata replaces all four with data that lives on the route definition itself, cascades through groups, and survives caching. Now the five problems.

Problem 1: Per-Route SEO Tags Without a Config Map

The classic case, and the one the PR uses in its own examples. Marketing pages need distinct titles, meta descriptions, and robots directives. Most Laravel apps solve this with view-level variables passed from every controller method, which means every controller method has to remember to pass them.

With metadata, the route definition carries the SEO data and one middleware shares it with every view:

// routes/web.php
Route::metadata(['seo' => ['robots' => 'index,follow']])
    ->group(function () {
        Route::view('/pricing', 'pages.pricing')
            ->metadata(['seo' => ['title' => 'Pricing', 'description' => 'Plans from 9 euro a month.']]);

        Route::view('/about', 'pages.about')
            ->metadata(['seo' => ['title' => 'About us']]);
    });

// app/Http/Middleware/ShareSeoMetadata.php
public function handle(Request $request, Closure $next): Response
{
    View::share('seo', $request->route()->getMetadata('seo', []));

    return $next($request);
}

Your layout reads $seo['title'] with a sensible fallback and you're done. Controllers stop caring about SEO entirely. The /about page didn't define a description, so getMetadata() just won't return one, and your Blade fallback handles it.

The win over a config map: renaming a route can't break anything, because nothing is keyed by route name anymore.

Problem 2: Feature Flag Gating for Whole Route Groups

You're rolling out a new billing section behind a flag. The old approach is a middleware that takes the flag name as a parameter, ->middleware('feature:new-billing'), repeated on every route or group. Workable, but middleware parameters are strings, they don't cascade with any structure, and stacking more than one gets noisy.

Metadata handles the cascade for you:

// routes/web.php
Route::metadata(['feature' => 'new-billing'])
    ->prefix('billing-v2')
    ->group(function () {
        Route::get('/', [BillingController::class, 'index']);
        Route::get('/invoices', [BillingController::class, 'invoices']);
        Route::resource('payment-methods', PaymentMethodController::class);
    });

// app/Http/Middleware/EnforceFeatureFlags.php
use Laravel\Pennant\Feature;

public function handle(Request $request, Closure $next): Response
{
    $flag = $request->route()->getMetadata('feature');

    if ($flag && ! Feature::active($flag)) {
        abort(404);
    }

    return $next($request);
}

Register the middleware globally on the web group. Routes without a feature key pass straight through. The resource inside the group is covered automatically, which is exactly the pending-registration case the old action-array hack couldn't handle.

And when the rollout finishes, you delete one metadata line instead of hunting middleware strings across three files.

Problem 3: Declarative Permission Tags in Middleware

To be clear about scope first: this doesn't replace policies and gates. Model-level authorization belongs in policies. But plenty of apps also have coarse route-level access rules ("everything under /admin/reports needs the reports.view permission") that end up scattered across can: middleware strings.

Metadata gives you a single declarative layer:

Route::metadata(['permissions' => ['admin.access']])
    ->prefix('admin')
    ->group(function () {
        Route::get('/dashboard', [DashboardController::class, 'index']);

        Route::metadata(['permissions' => ['admin.access', 'reports.view']])
            ->prefix('reports')
            ->group(function () {
                Route::get('/', [ReportController::class, 'index']);
                Route::get('/export', [ReportController::class, 'export']);
            });
    });

Note the nested group repeats admin.access in its list. That's deliberate: permissions is a list, and lists replace inherited values rather than merging. If you want additive permissions, either repeat the inherited ones like I did here, or structure them as an associative array (['admin.access' => true, 'reports.view' => true]) so the recursive merge works in your favor. This is the sharpest edge in the whole feature, so it's worth internalizing early.

The enforcement middleware is five lines:

public function handle(Request $request, Closure $next): Response
{
    foreach ($request->route()->getMetadata('permissions', []) as $permission) {
        abort_unless($request->user()?->can($permission), 403);
    }

    return $next($request);
}

One place to audit route-level access. php artisan route:list shows you the routes, the metadata shows you the rules, and nothing is hidden in controller constructors.

Problem 4: Breadcrumbs That Build Themselves

This is the use case Ben Bjurstrom, the PR's author, gave when asked what the feature is for: package authors need a place to attach data to routes while group and resource registration is still pending. Breadcrumbs are the perfect example because they're hierarchical, exactly like nested route groups.

Route::metadata(['breadcrumb' => ['Admin' => '/admin']])
    ->prefix('admin')
    ->group(function () {
        Route::metadata(['breadcrumb' => ['Admin' => '/admin', 'Users' => '/admin/users']])
            ->prefix('users')
            ->group(function () {
                Route::get('/', [UserController::class, 'index']);
                Route::get('/{user}', [UserController::class, 'show'])
                    ->metadata(['breadcrumb' => ['Admin' => '/admin', 'Users' => '/admin/users', 'Detail' => null]]);
            });
    });

A Blade component reads $request->route()->getMetadata('breadcrumb', []) and renders the trail. No third-party breadcrumb package, no separate breadcrumb definition file that drifts out of sync with your routes, no reflection tricks.

Because breadcrumb maps are associative arrays, nested groups merge cleanly and you could even skip repeating the parent crumbs. I repeat them anyway for explicitness, since key order in merged arrays is something I'd rather not depend on for UI. Expect packages to build nicer APIs on top of this primitive soon; error trackers are already reading it, and Flare 3.1.0 displays route metadata next to stack traces.

Problem 5: API Deprecation Headers From One Middleware

If you version APIs, you eventually deprecate endpoints. Communicating that properly means Deprecation and Sunset headers on every affected response, and most teams either skip it or hardcode headers in a dozen controllers.

Tag the routes instead:

Route::prefix('api/v1')
    ->metadata(['api' => ['version' => 1]])
    ->group(function () {
        Route::get('/orders', [Api\V1\OrderController::class, 'index'])
            ->metadata(['api' => [
                'deprecated_at' => '2026-07-01T00:00:00Z',
                'sunset' => '2026-12-31T23:59:59Z',
                'successor' => '/api/v2/orders',
            ]]);

        Route::get('/customers', [Api\V1\CustomerController::class, 'index']);
    });

// app/Http/Middleware/AddDeprecationHeaders.php
use Illuminate\Support\Carbon;

public function handle(Request $request, Closure $next): Response
{
    $response = $next($request);

    if ($deprecatedAt = $request->route()->getMetadata('api.deprecated_at')) {
        $response->headers->set('Deprecation', '@'.Carbon::parse($deprecatedAt)->timestamp);

        if ($sunset = $request->route()->getMetadata('api.sunset')) {
            $response->headers->set('Sunset', Carbon::parse($sunset)->toRfc7231String());
        }

        if ($successor = $request->route()->getMetadata('api.successor')) {
            $response->headers->set('Link', '<'.$successor.'>; rel="successor-version"');
        }
    }

    return $response;
}

The header formats matter here. RFC 9745, published March 2025, standardized the Deprecation header as a structured field date, meaning @ followed by a unix timestamp, and the older Sunset header from RFC 8594 takes a classic HTTP-date. Storing ISO strings in metadata and converting with Carbon at the edge keeps the route file readable while the wire format stays spec-compliant. Plenty of APIs still ship Deprecation: true from the pre-RFC draft days, but new code has no excuse.

Notice the dot notation doing real work too: api.deprecated_at reaches into the merged array, and the group's version key merged with the route's keys because both live under the associative api key.

The same metadata doubles as input for documentation tooling. Iterate the route collection in a command, read getMetadata('api'), and generate a deprecation report for your changelog. The data has one home and two consumers.

Where I'd Draw the Line

The contributor who questioned this feature on the PR wasn't entirely wrong. There's a version of route metadata that makes your app worse, and it looks like this: a junk drawer of loosely related keys that grows forever because "just add it to metadata" became the answer to everything.

My rules so far:

Metadata should describe the route, not configure behavior that belongs elsewhere. "This route is deprecated" describes. "Retry this route's queue jobs three times" configures, and belongs where queue configuration lives.

Keep values serializable. Everything goes through route:cache in production, so closures and objects are out. Strings, numbers, booleans, arrays. If you're tempted to put a closure in metadata, you actually want middleware.

Prefer associative structures over lists when groups are involved. You saw why in the permissions example. Lists replace on inheritance, and that surprises people.

Test the metadata directly. Since metadata is now load-bearing (a missing feature key means an unguarded route), a cheap test that iterates the route collection and asserts every route under a prefix carries the expected keys catches drift before production does:

it('guards every billing-v2 route with a feature flag', function () {
    $routes = collect(app('router')->getRoutes())
        ->filter(fn ($route) => str_starts_with($route->uri(), 'billing-v2'));

    expect($routes)->not->toBeEmpty();

    $routes->each(fn ($route) => expect($route->getMetadata('feature'))->toBe('new-billing'));
});

Five lines of Pest, and nobody can add a route to that group that silently skips the gate. This kind of route-collection assertion was always possible, but metadata finally gives it something structured to assert against.

And know when the old tools are still right. A one-off route with one middleware doesn't need a metadata layer plus a global middleware reading it. Metadata earns its place when the same kind of data applies across many routes, especially through groups and resources. For single-route concerns, route model binding and plain middleware parameters are still the simpler answer.

If you're not on Laravel 13 yet, this feature alone won't justify the jump, but combined with everything else in the release it's another reason to schedule it. The Laravel 12 to 13 upgrade guide covers the path, and the upgrade itself is one of the smallest major-version jumps Laravel has shipped.

FAQ

Which Laravel version do I need for route metadata?

Laravel 13.17.0 or later. The PR was merged on June 19, 2026 and shipped in the 13.17.0 release. It's a minor release, so if you're on any 13.x version, composer update gets you there with no breaking changes.

Does route metadata work with route:cache?

Yes, and this is the main advantage over rolling your own. Metadata is stored on the route action under a dedicated key, so php artisan route:cache serializes it and getMetadata() reads it back identically in cached and uncached environments.

Can I use this in Laravel 12 or 11?

No. The feature landed in 13.x only and there's no official backport. On older versions you're back to config maps or action-array workarounds, which is a decent nudge toward upgrading.

How is metadata() different from defaults()?

defaults() provides default values for route parameters, which means the values can be injected into controller method arguments. metadata() is inert data that never touches parameter binding. If you've been using defaults() to store non-parameter data, metadata is the correct home for it.

What's the difference between metadata() and setMetadata()?

metadata() merges with whatever the route already has, including values inherited from groups. setMetadata() replaces the entire metadata array, which is how a route opts out of its group's metadata completely.

Wrapping Up

Route metadata is a small feature with a long tail. Nothing here was impossible before. All of it was awkward before. The difference between "possible with hacks" and "supported with clean cascade semantics and cache safety" is the difference between a pattern you avoid and a pattern you reach for.

Start with one use case. The SEO middleware is the lowest-risk entry point, and once the getMetadata() pattern is in your muscle memory, you'll spot the other four in your own codebase within a week.

Running a Laravel app that's accumulated years of route-name conventions and config maps, and want help untangling it during a 13.x upgrade? Let's talk.

Laravel Reverb vs Pusher vs Soketi: Which WebSocket Server in 2026?

Hafiz — Wed, 01 Jul 2026 05:56:05 +0000

You're adding real-time features to a Laravel app. Live notifications, a chat panel, a collaborative cursor, a dashboard that updates without a refresh. The broadcasting code is the easy part because Laravel's API is the same no matter what's underneath. The actual decision is which WebSocket server sits behind it.

Three options dominate the Laravel world: Reverb (first-party, self-hosted), Pusher (hosted, pay per connection), and Soketi (open-source, self-hosted, Pusher-compatible). They all speak the Pusher protocol, so your broadcasting and Echo code barely changes between them. What changes is cost, scaling ceiling, and how much operational work lands on you.

I'll compare all three on the things that actually decide it, then give you a clear pick for each stage. There's also one fact about Soketi that should change how you think about it in 2026, and most comparisons skip it.

The Quick Version

Pusher is the hosted option: zero servers to run, you pay per concurrent connection, and it gets expensive as you grow. Reverb is Laravel's first-party server: free software, you host it (or let Laravel Cloud host it), and it scales with Redis. Soketi is the open-source Pusher-compatible server: also free and self-hosted, historically the budget favorite, but its maintenance situation in 2026 is the catch.

All three use the Pusher protocol. That's the thing that makes this a real choice rather than a lock-in: you can move between them with config changes, not rewrites.

Pusher: Pay to Not Think About It

Pusher is the original hosted WebSocket service, and the pitch hasn't changed. You never run a server. You never tune file descriptors or restart a daemon. You create an app, get credentials, and broadcast.

The pricing is connection-based and it's the whole story:

Free Sandbox: 100 concurrent connections, 200,000 messages/day
Startup: $49/month, 500 concurrent connections
Business: $299/month, 2,000 concurrent connections
Higher tiers climb past $499 to $1,199/month for 15,000 to 30,000 connections

A message counts both ways. Publish one event to 50 subscribers and that's 51 messages against your quota. For a chatty app (presence channels, typing indicators, live cursors) the message count climbs faster than you'd expect, and the daily cap on the free tier makes it unsuitable for production testing.

Pusher's real value is the zero-ops promise and the SDK breadth. If you want real-time working in 15 minutes and you'd rather pay than provision, it delivers. The problem is purely cost at scale: 2,000 connections for $299/month is the kind of bill that makes self-hosting look attractive the moment you have the ops capacity to handle it.

Reverb: The First-Party Default

Reverb is Laravel's own WebSocket server, built on ReactPHP, shipped in 2024, and by 2026 it's the default choice for most Laravel teams. It speaks the Pusher protocol, so it's a drop-in for Laravel broadcasting and Echo. A single server handles thousands of concurrent connections, and it's free software: you only pay for the box it runs on.

That last point is the headline. A Reverb instance on a $10 DigitalOcean droplet or a cheap Hetzner VPS handles early-stage real-time features for the cost of the server, not per connection. Compared to Pusher's $49 to $299 tiers, the savings start immediately and widen as you grow.

Scaling past one server uses Redis. You set REVERB_SCALING_ENABLED=true, point your Reverb instances at a shared Redis server, and put them behind a load balancer. When a message hits one server, Redis publishes it to the others via pub/sub, so connections spread across machines stay in sync. It's the same horizontal-scaling pattern you'd use for any stateful service.

Two things make Reverb in 2026 stronger than it was at launch.

First, the database driver. You no longer need Redis for small-to-medium apps. Reverb can use your existing MySQL or Postgres database to coordinate, which means you can ship live notifications, dashboards, and collaborative features without provisioning, securing, and paying for a Redis cluster. For early-stage products that's a real infrastructure cost cut. For high-throughput apps (10,000+ concurrent connections), Redis is still the recommended backend.

Second, managed Reverb on Laravel Cloud. If you want Reverb's economics without running the server yourself, Laravel Cloud offers fully managed Reverb clusters. You pick the number of concurrent connections, and Laravel claims up to 50% less than third-party tools like Pusher. It became the single most requested Cloud feature for a reason: it's the middle ground between self-hosting and paying Pusher's per-connection rates. It's the same managed-versus-self-hosted trade I walked through for Cloud's managed queues versus Horizon, just applied to WebSockets.

The cost of Reverb shows up as operations, not dollars. A self-hosted Reverb server is a long-running process you have to keep alive with Supervisor, tune for open file limits, restart on deploy with reverb:restart, and monitor. If your site is on Forge, the Application panel has a Reverb integration that handles the server tuning for you. But it's still infrastructure you own. That's the trade against Pusher: you swap a monthly bill for operational responsibility.

Soketi: The Catch in 2026

Soketi is an open-source, Pusher-compatible WebSocket server built on uWebSockets.js (a C library ported to Node.js, which makes it very fast). For years it was the go-to budget pick: run it on a $5 to $10 instance and get effectively unlimited connections and messages, where the equivalent Pusher plan would cost $49 for just 500 connections. On raw price-per-connection, Soketi has always won.

Here's the part most comparisons won't tell you, and it's the most important fact in this whole post. As of 2026, Soketi's maintenance is a concern, and that's not speculation. The maintainers say so directly. Their own documentation describes release and maintenance frequency as based on available time that's "tight as hell," and openly notes that maintenance issues have caused infrequent updates and infrequent support.

That changes the calculation. A Pusher-compatible server that's blazing fast and free but slowly maintained is fine for a side project where you can absorb the risk. For something you're betting a business on, leaning on a server whose maintainers have flagged their own limited bandwidth is a different proposition. And the kicker: Reverb now does almost everything Soketi did (Pusher protocol, self-hosted, free, fast), but with the entire Laravel core team behind it and first-party integration. The main reason to pick Soketi over Reverb in 2026 is if you specifically want a Node-based server in a non-Laravel-centric stack. Inside a Laravel app, Reverb has quietly taken Soketi's lunch.

Head to Head

Cost at a small scale (say 500 concurrent connections): Pusher is $49/month. Reverb is the price of a $10 VPS. Soketi is the price of a $5 to $10 VPS. Self-hosting wins by a wide margin the moment you can run a server.

Cost at a larger scale (5,000+ connections): Pusher runs into the hundreds per month and keeps climbing. Reverb and Soketi cost the same VPS plus a Redis instance, a fraction of the hosted price, but now you're managing horizontal scaling yourself. Managed Reverb on Laravel Cloud sits in between: more than a raw VPS, less than Pusher, and if you're already eyeing Cloud, the $5 plan with spend caps and scale-to-zero keeps the floor low.

Operational burden: Pusher is zero. Managed Reverb (Cloud) is near zero. Self-hosted Reverb and Soketi both require you to run, tune, monitor, and scale a long-running process.

Maintenance confidence: Reverb and Pusher are actively, professionally maintained. Soketi has the open maintenance concern above.

Laravel integration: Reverb is first-party and tightest. Pusher and Soketi are Pusher-protocol compatible, which is close, but Reverb is the one the framework ships with and the docs assume.

My Recommendation

For most Laravel apps in 2026, start with Reverb. It's first-party, it's free, the database driver means you don't even need Redis early on, and a single instance handles thousands of connections on a cheap server. You'd have to have a specific reason not to use it.

If you don't want to run any infrastructure and you'd rather pay for it, you've got two clean options. Managed Reverb on Laravel Cloud keeps you in the Reverb ecosystem with no ops. Pusher makes sense if you want a battle-tested hosted service with the broadest SDK support and you're early enough that the connection count keeps you in the cheaper tiers.

Pick Pusher over managed Reverb when you need the SDK breadth for non-web clients, or you want a vendor with a long track record and enterprise SLAs. Pick managed Reverb when you're a Laravel shop that wants the lowest hosted cost and tightest framework fit.

I'd be cautious about starting a new production project on Soketi in 2026. The technology is solid and fast, but the maintainers' own note about limited upkeep, combined with Reverb now covering the same ground with first-party backing, makes it hard to recommend over Reverb for new Laravel work. If you're already running Soketi happily, there's no fire drill. But for a fresh build, Reverb is the safer version of the same idea.

FAQ

Can I switch between these later without rewriting?

Mostly yes, and that's the upside of all three speaking the Pusher protocol. Your Laravel broadcasting code and Echo config stay the same; you change connection credentials and host settings. Moving from Pusher to Reverb, or Soketi to Reverb, is a config and infrastructure task, not an application rewrite. That makes "start simple, move later" a viable strategy.

Do I need Redis for Reverb?

Not anymore, for small-to-medium apps. Reverb's database driver lets it coordinate through your existing MySQL or Postgres, so you can skip Redis entirely early on. You'll want Redis once you scale horizontally across multiple Reverb servers or push into very high connection counts (10,000+), where it's the recommended backend.

How many connections can one Reverb server handle?

A single Reverb instance handles thousands of concurrent connections, with the exact ceiling depending on your server's resources and tuning (open file limits matter a lot here). Past what one box can hold, you scale horizontally with Redis pub/sub and a load balancer. For context, Soketi reports holding 500 active high-traffic connections on a 1GB, 1-CPU machine, and Reverb is in the same class.

Is Pusher still worth paying for?

When you value zero operations and broad SDK support over cost, yes. Pusher's advantage is that you never run anything and it works across many platforms and languages. The downside is purely price: connection-based tiers get expensive fast, and a chatty app burns message quota quickly. If you have the ops capacity to run Reverb, the math usually favors self-hosting.

What about Ably or other alternatives?

Ably is another hosted option with stronger delivery guarantees (exactly-once, message history, state recovery) and is worth a look for mission-critical messaging where dropped messages aren't acceptable. But it's not Pusher-protocol native in the way these three are, so it's a bigger integration lift inside Laravel. For most Laravel real-time features, the Reverb-Pusher-Soketi triangle covers the decision.

Wrapping Up

The honest 2026 answer is that Reverb won the default-choice slot, and for good reasons: first-party, free, fast, and no longer even requiring Redis for smaller apps. Pusher remains the right call when you'll pay to never touch infrastructure, especially via managed Reverb if you want to stay in the Laravel ecosystem. And Soketi, once the obvious budget pick, now carries a maintenance question that Reverb sidesteps entirely. Start with Reverb, reach for a hosted option when ops isn't where you want to spend time, and treat the Pusher protocol compatibility as your insurance policy to change your mind later.

If you're planning real-time features for a Laravel app and want help choosing and setting up the right WebSocket layer, let's talk.

Connect a Laravel AI Agent to Any MCP Server: A Hands-On Guide

Hafiz — Mon, 29 Jun 2026 07:01:09 +0000

Most Laravel MCP tutorials teach you to build a server. You expose your app's tools, an AI client connects, and Claude or Cursor can query your orders table. Useful, and I've covered building an MCP server with Filament before.

This post goes the other direction. Your Laravel AI agent becomes the client. It connects out to any MCP server, GitHub, Notion, Laravel Nightwatch, or one you run locally, and uses that server's tools as if you'd written them by hand. If you've built an agent with the Laravel AI SDK already, this slots straight into the agent you have. Ask your agent to "look into the latest exception in my app" and it browses your Nightwatch issues, pulls the stack trace, and reports back. You wrote none of that integration code.

Laravel shipped this on June 9, 2026. It's the piece that turns an agent from something that only knows your code into something that can reach into every tool your team already uses. If you've been giving your agent context with Laravel Boost and MCP, this is the reverse: your agent reaching out instead of a tool reaching in. Here's how to wire it up, from a no-auth local server to a full OAuth flow, plus the gotchas that'll bite you in production.

What Actually Ships in the Box

The feature is two packages working together, and the split matters.

The MCP client lives in laravel/mcp. It knows how to connect to a server, negotiate the handshake, authenticate, and call tools. It works on its own, from a queued job or a console command, with no agent anywhere in sight.

The thin integration lives in laravel/ai. It lets an agent consume that client without changing how agents already work. You drop MCP tools into the same tools() array you already use, and the SDK wraps each one to fit the agent's tool contract.

Before any code, pin your versions. As of late June 2026:

laravel/mcp v0.8.1 (the 0.8 line introduced the client; earlier versions were server-only)
laravel/ai v0.8.1
Laravel 12 or 13
PHP 8.3 or higher

That PHP floor matters. laravel/mcp itself tolerates PHP 8.2, but laravel/ai requires 8.3, and you need both for this. If you're on 8.2, Composer will refuse to resolve. Check what you've got:

composer show laravel/mcp laravel/ai

The Client Surface

The whole client is three verbs: connect, list tools, call a tool. Everything else stays out of your way.

use Laravel\Mcp\Client;

// A remote server over HTTP
$client = Client::web('https://mcp.example.com');

// A local server you run as a process (STDIO)
$client = Client::local('php', ['artisan', 'mcp:start']);

Those two constructors are the two transports. web() uses streamable HTTP for remote servers you reach over the network. local() uses STDIO (standard input/output) for servers you run as a child process on the same machine. You pick by where the server lives, not by preference.

Listing and calling tools looks like this:

$tools = $client->tools();

$result = $client->callTool('search-issues', [
    'query' => 'payment failed',
]);

$result->text();             // the text content
$result->isError;            // did the tool report a failure
$result->structuredContent;  // structured payload, if the tool returned one

The connection happens lazily on the first real call, so you don't have to manage it manually. But you can if you want:

$client->connect();
$client->ping();
$client->disconnect();

During that connection, the client and server negotiate a protocol version and exchange capabilities, so both sides agree on the rules before any work happens. You don't write any of that. It's the handshake, and when it fails (more on that later) it's usually an auth or version mismatch underneath.

Step 1: A Local Server With No Auth

Start with the simplest possible case so you see the wiring before the complexity. Point an agent at a local MCP server (yours, or any STDIO server) with no authentication at all.

Inside your agent, the MCP tools go straight into the tools() method, right next to your hand-written tools:

use App\Ai\Tools\SendSlackMessage;
use Laravel\Mcp\Client;

public function tools(): iterable
{
    return [
        ...Client::local('php', ['artisan', 'mcp:start'])->tools(),
        new SendSlackMessage,
    ];
}

That's the entire integration. The spread operator drops every tool from the MCP server into the array. The SDK notices they're MCP tools and wraps each one: it translates the MCP input schema into Laravel's JSON schema, calls the remote tool when the model asks for it, and normalizes whatever comes back into a result the model can read. The model has no idea which tools came from MCP and which you wrote. They all look the same to it.

This is the mental model for the whole feature. If you can get one local server connected, every other server is just a different transport and an auth layer on top.

Step 2: Bearer Token Auth

Most useful servers want to know who you are. The simpler auth path is a bearer token, a string you already hold. A GitHub personal access token is the classic example.

use Laravel\Mcp\Client;

$client = Client::web('https://api.githubcopilot.com/mcp/')
    ->withToken($token);

You can pass a closure instead of a raw string, which is what you want when the token belongs to the currently authenticated user:

$client = Client::web('https://api.githubcopilot.com/mcp/')
    ->withToken(fn () => auth()->user()->github_token);

Drop it into the agent the same way:

public function tools(): iterable
{
    return [
        ...Client::web('https://api.githubcopilot.com/mcp/')
            ->withToken(fn () => auth()->user()->github_token)
            ->tools(),
    ];
}

Now your agent can search repositories, read CI logs, triage issues, and check Dependabot alerts. GitHub's server even supports a read-only mode through a request header if you'd rather the agent not change anything.

Step 3: Full OAuth (The Real-World Case)

Bearer tokens are fine when you already have a token. But hosted servers like Laravel Nightwatch use OAuth, where the user clicks a button, approves access on the provider's site, and comes back with a token your app stores. (If you're weighing Nightwatch against the alternatives, I compared Telescope vs Pulse vs Nightwatch separately.) This is the part the official announcement glosses over, so here's the whole flow.

use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;

Mcp::registerClient('nightwatch', fn () => Client::web('https://nightwatch.laravel.com/mcp')
    ->withOAuth(
        clientId: config('services.nightwatch_mcp.client_id'),
        clientSecret: config('services.nightwatch_mcp.client_secret'),
    ));

If the server supports dynamic client registration, you can omit the ID and secret entirely and the client registers itself. Whether you can do that depends on the server, which becomes important when things break.

Next, wire the connect and callback routes in routes/ai.php. The package gives you a helper that registers both:

use Laravel\Mcp\Client\OAuth\TokenSet;
use Laravel\Mcp\Facades\Mcp;

Mcp::oAuthRoutesFor('nightwatch', function (string $client, TokenSet $token) {
    auth()->user()->update([
        'nightwatch_mcp_token' => $token->accessToken,
    ]);

    return redirect('/dashboard');
});

This registers two named routes: mcp.oauth.nightwatch.connect and mcp.oauth.nightwatch.callback. The connect route redirects the user to the authorization server. The callback route exchanges the authorization code and runs your closure with a fresh token. You never touch the redirect URLs or the PKCE details.

Then a button in your Blade view kicks it off:

<a href="{{ route('mcp.oauth.nightwatch.connect') }}">
    Connect Nightwatch
</a>

The flow runs in order: the user clicks the button, the package redirects them to Nightwatch, they sign in and approve, Nightwatch sends them back to your callback route, your closure runs with the token, and you store it however you like. The package owns the OAuth choreography. Your app owns where the token lives.

One thing to be clear about: there's no built-in token store. You persist $token->accessToken yourself, and you read it back when you build the client. The package handles refreshing expired tokens, but storage is on you.

Once the token's stored, the agent uses the named client:

public function tools(): iterable
{
    return [
        ...Mcp::client('nightwatch')->tools(),
    ];
}

Now ask the agent: "What are the most recent exceptions in production? Help me prioritize which to fix first." It browses your issues, reads stack traces, and answers. Tell it "mark issue 123 as resolved with a comment summarizing the fix," and it does that too.

How the Agent Sees MCP Tools

Here's the flow from prompt to remote tool call and back, so you know what's happening when the model decides to use a Nightwatch tool.

The key insight is in the middle. By the time the model is choosing, native and MCP tools sit in the same list and look identical. The wrapping, the schema translation, the network call, the result normalization, all of it happens below the model's awareness.

Caching the Tool List

Listing tools is a network round trip on a remote server, and the tool list rarely changes. So cache it. Because tools come back as plain data, you wrap the call in Laravel's cache and they rehydrate cleanly:

use Illuminate\Support\Facades\Cache;

$tools = Cache::remember('mcp.nightwatch.tools', now()->addHour(), function () {
    return Mcp::client('nightwatch')->tools();
});

Worth knowing: this isn't a dedicated client feature, despite what some descriptions imply. It's standard Laravel caching wrapped around the tools() call. The win is real though: you skip a round trip on every single prompt, which matters most for OAuth-secured remote servers where each call carries auth overhead.

Testing Without a Live Server

You don't want your test suite hitting a real MCP server over the network. Laravel AI's faking layer lets you script the model's responses while the tool call still flows through the MCP layer.

MCP tool names follow a mcp_tools_<name> pattern. A server tool called search shows up to the agent as mcp_tools_search. So you can fake a model response that calls the tool, then a final answer, and assert on the result:

use Laravel\Ai\Facades\Ai;

it('investigates exceptions through the nightwatch agent', function () {
    Ai::fake([
        Ai::toolCall('mcp_tools_search-issues', ['query' => 'payment']),
        Ai::text('Found 3 payment exceptions. The most frequent is a Stripe timeout.'),
    ]);

    $response = (new SupportAgent)->prompt('Any payment errors lately?');

    expect((string) $response)->toContain('Stripe timeout');
});

You test the production path (the agent calling a tool, reading the result, responding) without a single network call.

The Gotchas That'll Actually Bite You

The happy path is clean. Here's what isn't, drawn from real issues developers have hit.

OAuth handshake failures are the big one. There's a documented case (laravel/boost issue #584) where connecting Nightwatch through certain agents threw 403 Forbidden ... when send initialize request before auth, and handshake decoding errors after. The reported cause: the client didn't detect that auth was required and never triggered the login flow. Two fixes came out of that thread. Run an explicit login for your agent if it supports one. Or route through the mcp-remote bridge instead of pointing directly at the URL, which is what Nightwatch's own docs recommend for several clients. If a direct connection fails the handshake, try the bridge before assuming your code is wrong.

Dynamic client registration isn't universal. Remember the OAuth step where you could omit the client ID and secret? That only works if the server supports dynamic client registration. Several servers require a pre-registered OAuth client, and trying to auto-register against them fails, often as a 403 that looks like an auth bug. Know which mode your target expects: if it doesn't do dynamic registration, you must supply clientId and clientSecret explicitly.

Token storage is your job, and it's easy to get wrong. The package refreshes tokens but doesn't store them. The common mistake is persisting the token somewhere your withToken() closure can't read it back, or not persisting it at all and wondering why every request re-prompts for auth.

Protocol version mismatches surface as handshake failures. Servers advertise different MCP spec versions. If a server only speaks a version the client doesn't negotiate, the connection fails at the handshake. The error won't always say "version," so keep it on your list of suspects when a connection won't establish.

Remote tool errors don't throw into your code. When a remote tool fails, the result carries isError rather than raising an exception in your agent loop. The wrapper normalizes the failure into something the model can read and react to. Check isError if you're handling results manually.

When to Use This (and When Not To)

Reach for an MCP client connection when the tool already exists as an MCP server and you'd otherwise be writing an API integration by hand. Nightwatch, GitHub, Notion, and a growing list of services expose MCP servers. Consuming one is a few lines; rebuilding its integration is a few days.

Skip it when a plain API call or a tool class you write yourself is simpler. If you only need one endpoint from a service, a small hand-written tool beats pulling in an entire MCP connection and its auth flow. MCP earns its place when you want many of a server's capabilities, or when the server is something like Nightwatch where the tools are rich enough to be worth the wiring.

And if you're building tools for your own app, remember you can reuse your laravel/mcp server tool classes directly in an agent with no client at all. Write the tool once, use it as a server tool for external clients and as a native agent tool internally. It's the same instinct behind making your whole Laravel app AI-agent friendly: build the capability once, expose it everywhere.

FAQ

Do I need to build an MCP server to use this?

No. This is the opposite direction. You're consuming external servers as a client. You don't expose anything. If you also want to expose your own app's tools to outside AI clients, that's the server side, which is a separate setup.

Which transports does the client support?

Two: STDIO for local servers you run as a process (Client::local(...)), and streamable HTTP for remote servers you reach over the network (Client::web(...)). You choose based on where the server runs, not preference.

Can I connect to multiple MCP servers in one agent?

Yes. Spread multiple clients into the same tools() array, mixing transports and auth freely. A local STDIO server and a remote OAuth server can both feed one agent, alongside your hand-written tools. The model treats them all identically.

How do I handle a server that needs OAuth but my client runs headless?

OAuth assumes a human approves access in a browser. For background or headless work, some servers support a client-credentials grant (no user in the loop), which the package handles. Others, like Notion's remote server, explicitly aren't built for headless agents, and you'd need a different auth path or a token issued ahead of time.

Does this work with Laravel 11?

The laravel/mcp client supports Laravel 11, 12, and 13, but laravel/ai requires Laravel 12 or 13 and PHP 8.3+. Since the agent integration needs both, you effectively need Laravel 12 or 13 to use an agent as an MCP client.

Wrapping Up

The agent-as-client direction is the quieter half of Laravel's MCP story, and the more useful one for most apps. Building a server exposes your app to AI tools. Consuming servers gives your agent reach into every tool your team already runs, with a few lines instead of a custom integration per service. Start with a local no-auth server to internalize the tools() pattern, graduate to a bearer token, then wire the full OAuth flow when you connect something like Nightwatch. And keep the troubleshooting section handy, because the handshake and OAuth edge cases are where the real time goes.

If you're building agent features into a Laravel app and want help getting the MCP layer right, let's talk.

PHP 8.5's Pipe Operator vs Laravel Collections: Where Piper Fits (And Where It Doesn't)

Hafiz — Wed, 24 Jun 2026 07:55:49 +0000

PHP 8.5 shipped the pipe operator in November, and most Laravel developers shrugged. Why would we care about |> when collect()->filter()->map() has read top-to-bottom for a decade? Chained transformations are a solved problem in Laravel.

Then Spatie released Piper last month: a library that ports Laravel's collection and string helpers to standalone functions built specifically for the pipe operator. When the team that maintains 300+ Laravel packages decides the pipe operator needs a Laravel-flavored toolkit, the question stops being academic. Is there an actual reason to write $array |> filter(...) |> map(...) instead of reaching for Collections?

I dug into the package, the design decisions behind it, and where each approach actually wins. Short answer: Piper isn't a Collections replacement and doesn't try to be. But there are two specific situations where it's the better tool, and one hard constraint that decides everything before style ever enters the picture.

A 60-Second Pipe Operator Refresher

The pipe operator takes the result of the left expression and passes it as the single argument to the callable on the right:

$result = '  laravel  '
    |> trim(...)
    |> strtoupper(...);

// "LARAVEL"

Each step reads in execution order, top to bottom, no nesting, no intermediate variables. The (...) syntax is PHP 8.1's first-class callable notation.

The catch: the right side must be a callable that accepts exactly one argument. And PHP's standard library was not designed for that. Argument orders are famously inconsistent (array_map($callback, $array) but array_filter($array, $callback)), so half the stdlib needs wrapping in arrow functions before it pipes. That friction is exactly the gap Piper fills.

What Piper Actually Does

Piper (v1.0, requires PHP 8.5) ports Laravel's array and string helpers to namespaced functions under Spatie\Piper\Arr and Spatie\Piper\Str. The design trick: every function is a higher-order function. Calling filter(fn ($i) => $i % 2 === 0) doesn't filter anything. It returns a closure waiting for the one value the pipe will feed it:

use function Spatie\Piper\Arr\{filter, map, join};
use function Spatie\Piper\Str\{prefix, suffix};

$summary = [1, 2, 3, 4, 5, 6]
    |> filter(fn (int $i) => $i % 2 === 0)
    |> map(fn (int $i) => $i ** 2)
    |> join(', ', ', and ')
    |> prefix('The winning numbers are ')
    |> suffix('.');

// "The winning numbers are 4, 16, and 36."

Notice what's absent: no collect() going in, no ->all() or ->toString() coming out. Plain arrays and strings flow through plain functions. That's the entire philosophy.

Where Piper Beats Collections

Native values in, native values out. Collections are a wrapper object. You pay a conversion at each boundary: collect($array) to enter, ->all() to leave, and every method returns a new Collection instance along the way. In application code you barely notice. In code that interfaces with anything expecting plain arrays (third-party SDKs, array-typed signatures, JSON boundaries), the wrapping and unwrapping is pure ceremony. Piper skips it entirely: each function takes an array, returns an array.

Mixing your own functions into the chain. This is the pipe operator's structural advantage, and it's something Collections can't do cleanly. A Collection chain can only call methods that exist on the Collection class (or macros you register globally). A pipe chain accepts any callable: Piper helpers, native functions, your own domain functions, all in one flow:

use function Spatie\Piper\Arr\{filter, map};

$total = $orders
    |> filter(fn (Order $o) => $o->isPaid())
    |> map(fn (Order $o) => $o->total)
    |> array_sum(...)
    |> $this->applyDiscount(...);

With Collections, applyDiscount() either becomes a macro, a ->pipe() call, or a break out of the chain into a variable. The pipe operator treats your functions as first-class chain citizens.

No framework dependency. Piper's functions are standalone with zero Illuminate packages required. For package authors who want Laravel-style ergonomics without pulling illuminate/collections into their dependency tree, that's a real selling point.

Where Collections Still Win

API surface. Piper v1 ports the most-used helpers. Collections have 100+ methods refined over a decade: groupBy(), pluck() with dot notation, chunk(), zip(), mapWithKeys(), higher-order messages like ->map->title, and on and on. The moment your transformation needs one of the deeper methods, you're back in collect() territory, and splitting one pipeline across both styles is worse than picking one.

Lazy evaluation. LazyCollection processes large datasets (cursor results, big files) one item at a time with constant memory. Piper has no lazy story: each function in the chain materializes a full new array. For query results you've already optimized, chaining five Piper functions over 100,000 rows allocates five intermediate arrays.

Eloquent integration. Query builders return Collections. Relations return Collections. Every Laravel API hands you a Collection already. Converting to a plain array just to pipe it through Piper means swimming upstream against the entire framework.

Discoverability. Type -> after a Collection and your IDE lists every available method. With Piper you need to know the function exists, import it, and keep your use function block tidy. It's a small tax, but it's paid on every file.

The Constraint That Decides Everything

Piper requires PHP 8.5. That's not a style consideration, it's a hard gate. PHP 8.5 shipped in November 2025, and most production fleets I see are still on 8.2 through 8.4. If your servers aren't on 8.5, this entire discussion is theoretical, and I'd guess that covers the majority of Laravel apps in production today. I wrote about this lag pattern before: PHP 8.4 features were still "new" to most codebases a full year after release.

There's a second adoption headwind worth naming: AI coding assistants. Sebastian De Deyne (who built Piper) observed that coding agents essentially never produce pipe operator code unless explicitly asked. Training data has a decade of collect() chains and almost no |>. In 2026, syntax that your tooling doesn't reach for by default spreads slower, regardless of merit.

My Take

Use Piper when you're writing framework-agnostic code (packages, shared libraries) or transformation-heavy code on native arrays and strings where pulling in Collections feels like overkill. The function-mixing capability is the one place the pipe operator is structurally better than method chaining, not just different. It's the same kind of decision-tree thinking I apply to services versus actions: pick by code context, not by what's newest.

Inside a Laravel app, keep using Collections. They're everywhere, your team knows them, Eloquent hands them to you, and the lazy variant handles scale. Piper isn't trying to dethrone them; it's filling the gap for the code that lives between Laravel projects. Spatie has a habit of shipping packages a few years before the ecosystem catches up (Scotty did this for deployment), and Piper reads like a bet on where PHP code style lands by 2028, not a tool you must adopt this sprint.

FAQ

Does Piper replace Laravel Collections?

No, and Spatie doesn't position it that way. Piper covers array and string transformations on native values. Collections remain the richer, framework-integrated tool. Think of Piper as a companion for the places Collections are awkward, not a successor.

Can I use the pipe operator with Collections directly?

Not meaningfully. Collections are objects with chained methods, and the pipe operator wants single-argument callables. You could pipe into collect(...) to enter Collection-land, but at that point just use the Collection chain.

Does the pipe operator perform better than Collection chaining?

Marginally, in theory: plain function calls skip the object method dispatch and per-step Collection instantiation. In practice the difference is noise compared to your database queries. Don't pick either approach for performance; pick for readability and context.

Can I use Piper in Laravel 13?

Yes, as long as your runtime is PHP 8.5 or higher. The package has no framework dependency, so it works in any PHP 8.5 project, Laravel or not. The version check that matters is your PHP binary, not your Laravel version.

What about Stringable for string chains?

Laravel's Str::of() fluent strings cover the same ground as Spatie\Piper\Str inside a Laravel app, with the same trade-offs as Collections: wrapper object, framework dependency, huge API. The same logic applies: Stringable in app code, Piper in framework-agnostic code.

Wrapping Up

The pipe operator is the most interesting thing to happen to PHP syntax in years, and Piper is the first serious attempt to make it ergonomic for the Laravel crowd. But interesting and necessary aren't the same thing. If your production PHP is 8.5 and you write package code or work with native arrays at framework boundaries, Piper earns a spot in your composer.json. For everything else, collect() isn't going anywhere.

If you're modernizing a Laravel codebase and weighing which PHP 8.5 features are actually worth adopting, let's talk.

Laravel Cloud Managed Queues vs Horizon: What You Give Up and What You Get

Hafiz — Mon, 22 Jun 2026 06:17:23 +0000

Laravel Cloud shipped Managed Queues on May 26, and the pitch is hard to ignore: queue workers that scale up when jobs pile up, scale to zero when there's nothing to do, and a built-in dashboard for failed jobs. No Supervisor configs, no Redis tuning, no horizon:terminate in your deploy script.

If you're running Horizon today, the obvious question is: should you care? I went through the docs, the launch post, and the pricing model to answer that properly. The short version: Managed Queues solve real problems, but Horizon users give up more than the announcement suggests. There's a 15-minute delay cap that will silently break a lot of apps, and the Redis features Horizon users lean on don't exist in the SQS world.

Here's the honest breakdown.

What Managed Queues Actually Are

First, the architecture, because it explains everything else. With Managed Queues, Laravel Cloud becomes your queue driver. Under the hood it's SQS: your app needs aws/aws-sdk-php in its composer.json, and Cloud provisions the queue, configures access, and reads queue depth directly from SQS without going through your application.

Every worker runs in its own isolated container with guaranteed memory. You pick a tier from 256 MiB up to 8 GiB, and CPU scales with it. When jobs arrive, Cloud spins up workers based on queue pressure (depth plus message age, not just depth). When the queue drains, workers scale back to zero and billing stops.

Compare that to Horizon (v5.47 as of June 2026): a free package, Redis only, running on infrastructure you provision. You define worker pools and balancing strategies in config/horizon.php, keep the master process alive with Supervisor, and remember to call horizon:terminate on every deploy. Horizon gives you enormous control. It also gives you all the operational responsibility.

That's the actual trade: control and Redis features versus zero infrastructure and pay-per-second billing.

What You Get

Scale to zero. This is the headline. A Horizon setup on a Forge-managed VPS or Hetzner box costs the same whether it processes a million jobs or none. Managed queue workers cost nothing while idle. For side projects, staging environments, and apps with bursty workloads, that's a real difference.

True worker isolation. Each worker gets its own container with guaranteed memory. One job blowing past its memory limit kills that one worker, not its neighbors. With Horizon, workers share the box: one memory-hungry job can take down everything on the same server, which is exactly the failure mode I covered when the AI SDK's default config starved a Horizon queue.

Burst absorption without capacity planning. Cloud scales from zero to your max worker cap automatically. With Horizon, maxProcesses is bounded by the RAM you bought. Dispatching 10,000 jobs at once means either provisioning headroom you pay for all month, or watching the backlog drain slowly. Processing 10,000 tasks is a sizing exercise on Horizon. On Managed Queues it's a config field.

A failed jobs dashboard your support team can use. Failed jobs surface with full payload, exception, and stack trace, and anyone with environment access can retry with one click. No php artisan queue:retry over SSH. For teams where non-developers field "my export never arrived" tickets, this matters more than it sounds.

Pause and purge from the UI. Pause terminates workers immediately and stops billing while jobs accumulate safely. Note the difference from Horizon's queue:pause: Horizon's version keeps workers alive (and on your server, still costing you), Cloud's version actually stops the meter.

What You Give Up

This is the part the launch post doesn't dwell on.

Delayed jobs are capped at 15 minutes. This is the biggest gotcha and it deserves the bold. SQS has a hard 15-minute delay limit, and Managed Queues inherit it. If your app does ->delay(now()->addHour()) for a follow-up email, or schedules a retry for tomorrow morning, that breaks. Horizon on Redis delays jobs for as long as you want. Plenty of Laravel apps use long delays without thinking about it, and nothing in your code will warn you before you migrate. Audit every delay() and release() call before considering a move.

At-least-once delivery only. No strict ordering, no exactly-once processing. If a worker hits the visibility timeout, gets terminated during a deploy, or a queue is paused mid-flight, jobs can be redelivered. Your jobs must be idempotent. Good queue code should be idempotent anyway, but with Horizon on Redis many apps quietly get away with assuming a job runs once. On Managed Queues that assumption will eventually bite you.

Horizon's Redis toolbox doesn't come along. Tags for monitoring specific models or job types. Redis::funnel() and Redis::throttle() for rate limiting third-party API calls. Balancing strategies that shift workers between queues based on load. Per-queue wait time alerts via Slack or SMS. None of this exists on Managed Queues. The dashboard shows volume, duration, memory, and worker counts per queue, which is good operational visibility, but it's not Horizon's per-tag, per-job granularity. (For deeper tracing, Laravel's answer is pairing Cloud with Nightwatch, which is another subscription.)

One queue name per managed queue. Horizon lets one supervisor drain default,emails,exports with priorities. On Cloud, each queue name is its own managed queue with its own config. The Starter plan allows exactly 1 queue and 3 max workers, Growth allows 10 queues and 25 workers each, Business is uncapped (50 workers soft cap, raisable). If your app uses queue names for priority lanes, you'll restructure.

Cold starts. A queue that scaled to zero takes several seconds to spin up its first worker (around 10 seconds per the engineering team). For background reports nobody notices. For user-facing jobs like "your download is ready," a 10-second floor on top of job runtime is noticeable. Workers can't currently be kept warm; a configurable warm minimum is planned but not shipped.

Dashboard-only management, for now. No API or CLI for creating, pausing, or configuring queues at launch. If you manage infrastructure as code, that's a regression from a horizon.php file in version control.

You're on Laravel Cloud. Obvious, but worth saying: Managed Queues only exist as a platform feature of Laravel Cloud. Horizon runs anywhere Redis does.

The Pricing Math

Managed Queues bill two meters: worker compute per second (by memory tier) and queue operations at $1 per million. An operation is any API call against the queue: every dispatch, receive, delete, and every polling check at your configured interval (default 5 seconds). Payloads are measured in 64 KB chunks, with a 1 MiB max per job.

Run the numbers on a typical small production app: say 300,000 jobs a month, averaging 2 seconds each on a 256 MiB worker. That's roughly 600,000 worker-seconds, plus around a million operations (three per job, plus polling). You're looking at single-digit dollars per month, and a dev or staging environment that sits idle most of the day costs close to nothing.

Now the Horizon side: a €4.49/month Hetzner CX22 runs Horizon comfortably for that workload, flat rate, with the rest of the box free for your app. At steady, predictable volume, a fixed server stays hard to beat, and at high sustained volume the per-second meter can climb past a beefier fixed server. The crossover isn't a single number because it depends on job duration and memory tier, but the shape is clear: spiky and idle-heavy favors Managed Queues, flat and sustained favors a fixed worker.

That's also why Cloud itself still offers worker clusters (fixed workers running queue:work continuously) and recommends them for sustained, predictable throughput. Even inside Laravel's own platform, autoscaling isn't always the answer.

So Who Should Switch?

Stay on Horizon if: you use delays longer than 15 minutes anywhere, you depend on tags, Redis::throttle(), or balancing strategies, your throughput is steady enough that a fixed server is cheaper, or you simply aren't on Laravel Cloud and have no other reason to move. Horizon is mature, free, and v5.47 shows it's still actively maintained.

Use Managed Queues if: you're already on Cloud (it should be your default there over app cluster background processes), your workload is bursty or idle-heavy, you want support staff retrying failed jobs from a UI, or you're starting a new project and would rather never write a Supervisor config. Start with a single queue at 256 MiB, watch the memory chart, and adjust.

Don't switch mid-flight without an audit. The delay cap and at-least-once semantics are silent breaking changes. Grep for delay(, release(, and WithoutOverlapping and check every result before moving a production queue.

My take: Managed Queues are the right default for new apps on Cloud, and the failed jobs dashboard alone will sell it to teams. But Horizon is not obsolete. It's the more capable tool that costs you operational attention instead of per-second billing. The 15-minute delay cap is the dealbreaker to check first, before price, before features.

FAQ

Can I run Horizon on Laravel Cloud instead of Managed Queues?

Yes. Cloud's worker clusters let you self-manage queue:work processes with your own driver, and you can run Horizon against a Redis instance there. You give up scale-to-zero and the built-in failed jobs dashboard, but you keep Redis features and long delays.

Do Managed Queues work with Laravel 10?

No. The supported minimums are Laravel 11.53.1, 12.60.2, and 13.11.2, and your app must include aws/aws-sdk-php. Deploys that create a managed queue on an unsupported version fail with a clear error.

What happens to my failed_jobs table?

Managed Queues surface failed jobs in the Cloud dashboard automatically, with no failed jobs driver to configure. Failures are visible cross-queue with payload, exception, and stack trace, and you can retry or delete from the UI.

How do scheduled jobs with long delays work if there's a 15-minute cap?

They don't, directly. The workaround is restructuring: instead of dispatching with a long delay, store the intended run time and let the scheduler dispatch the job when it's due. It's a known SQS pattern, but it's code you have to write and test.

Is Horizon being deprecated?

No sign of that. Horizon v5.47.2 shipped in early June 2026 with support through Laravel 13. Cloud's own queue clusters were deprecated in favor of Managed Queues, but Horizon is a framework package, not a Cloud feature, and it remains the standard for self-hosted Redis queues.

Wrapping Up

Managed Queues are Laravel Cloud's strongest argument yet for teams that hate running queue infrastructure: real isolation, honest pay-for-what-runs billing, and a failed jobs story Horizon never had. Horizon remains the choice when you need Redis semantics, long delays, fine-grained control, or predictable flat costs. Know which list describes your app before you touch anything, starting with that 15-minute delay cap.

If you're weighing a move to Laravel Cloud or untangling a queue setup that's outgrown its config, let's talk.

Cashier (Stripe) vs Cashier (Paddle) for a Bootstrapped Laravel SaaS: The Numbers Nobody Shows You

Hafiz — Wed, 17 Jun 2026 11:08:05 +0000

Every "Stripe vs Paddle" comparison I've read compares features. Webhook flexibility. Checkout customization. API surface area. That's useful if you're an engineer evaluating architecture, but it's useless if you're a bootstrapped founder trying to figure out how much money you'll actually keep.

So let's do the math instead. I'm going to take a $100/month subscription and trace it through both platforms, including the fees that most comparisons conveniently leave out. Then I'll tell you which one I'd pick at different stages, and why.

Both platforms have official Laravel packages: laravel/cashier (v16.5, Stripe) and laravel/cashier-paddle (v2.8, Paddle). Both support Laravel 10 through 13. The integration quality is comparable. So this really comes down to money and operational cost.

What Stripe Actually Costs

Stripe's headline rate is 2.9% + $0.30 per transaction in the US, or 1.5% + €0.25 in most of Europe. On a $100 subscription, that's $3.20 in the US. Simple enough.

But if you're running a SaaS with recurring billing, that's not the full picture. You'll probably want Stripe Tax to handle VAT and sales tax automatically. That adds 0.5% per transaction where tax is collected. On our $100 charge, that's another $0.50.

If your customers pay with international cards, add another 1.5%. Currency conversion adds 1-2% on top of that. And chargebacks cost $15 each, win or lose.

Here's the realistic breakdown for a $100 US subscription:

Base processing:        $3.20  (2.9% + $0.30)
Stripe Tax:             $0.50  (0.5%)
────────────────────────────────
Total Stripe fees:      $3.70
You keep:               $96.30
Effective rate:         3.7%

For an EU seller charging €100 to an EU customer:

Base processing:        €1.75  (1.5% + €0.25)
Stripe Tax:             €0.50  (0.5%)
────────────────────────────────
Total Stripe fees:      €2.25
You keep:               €97.75
Effective rate:         2.25%

That EU rate looks great. But there's a catch. Stripe Tax calculates and collects the tax. It doesn't file your returns everywhere automatically. You'll still need to register for OSS (One-Stop Shop) in the EU and handle filing, either yourself or through a service. Some of that is included in Stripe's Tax Complete tier, but you'll need to verify coverage for your specific countries.

And none of this includes the time you spend managing it. Configuring Stripe webhooks, handling failed payments, generating compliant invoices, dealing with chargebacks. That's your time or your developer's time, and it has a cost even if it doesn't show up on an invoice.

What Paddle Actually Costs

Paddle's rate is 5% + $0.50 per transaction. Full stop. On a $100 subscription, you pay $5.50. You keep $94.50.

All-inclusive fee:      $5.50  (5% + $0.50)
────────────────────────────────
Total Paddle fees:      $5.50
You keep:               $94.50
Effective rate:         5.5%

That 5.5% looks painful compared to Stripe's 3.7%. But here's what's included in Paddle's fee that isn't included in Stripe's:

Tax compliance in 200+ countries. Paddle registers, calculates, collects, and files sales tax, VAT, and GST everywhere. You don't touch it. You don't even think about it.

Merchant of Record status. Paddle is the legal seller. Your customer's credit card statement shows "Paddle" (or a Paddle subsidiary), not your company. This means Paddle handles refunds, chargebacks, and compliance obligations. If a customer disputes a charge, Paddle deals with it.

Chargeback protection. Included in the 5%. No $15 per dispute fee.

Invoicing. Paddle generates compliant invoices automatically for every jurisdiction.

The trade-off is clear: Paddle costs more per transaction, but it removes an entire category of operational work.

The Number That Actually Matters

The fee difference on a $100 transaction is $1.80 ($5.50 Paddle vs $3.70 Stripe). On $1,000 MRR, that's $18/month. On $5,000 MRR, it's $90/month. On $10,000 MRR, it's $180/month.

Now compare that to the cost of handling tax compliance yourself with Stripe:

If you're an EU-based solo developer (like me, based in Italy), selling to customers across the EU, you need to handle VAT via OSS. Stripe Tax helps with calculation, but the filing, the registration, the record-keeping: that takes time. Conservative estimate: 2-4 hours per month at the start. If your time is worth $50/hour, that's $100-200/month in opportunity cost.

Add in the occasional chargeback investigation ($15 each plus your time), invoice formatting issues, and the mental load of being legally responsible for tax compliance in dozens of countries. The $90/month difference at $5,000 MRR starts looking like a bargain for Paddle.

But. At $10,000+ MRR, the math shifts. By then you probably have a bookkeeper or accountant. Tax filing is systematized. The $180/month gap becomes real money over a year ($2,160). And Stripe gives you more control: more checkout customization, more webhook flexibility, deeper integration with your application.

The Laravel Integration Side

Both packages follow similar patterns. Install, configure, add the Billable trait to your User model. Both handle subscriptions, plan swapping, cancellation grace periods.

The practical differences:

Checkout flow. Stripe lets you build a fully custom checkout within your app. Paddle uses an overlay or redirect checkout hosted by Paddle. If you want the payment form embedded directly in your Blade views, Stripe gives you that control. With Paddle, the customer briefly leaves your UI.

Webhooks. Both packages register webhook routes automatically. Stripe sends more granular events (payment_intent.succeeded, invoice.payment_failed, customer.subscription.updated). Paddle sends fewer, broader events (transaction.completed, subscription.activated). For most SaaS apps, both provide everything you need. Stripe's granularity matters more if you're building complex billing flows with metered usage or prorations.

Refunds. With Stripe (via laravel/cashier), you call $user->refund($paymentId) and handle the money movement yourself. With Paddle (via laravel/cashier-paddle), you call $transaction->refund() and Paddle handles everything including the tax adjustment.

Testing. Both have sandbox/test modes. Stripe's test mode is more mature with more test card numbers and edge case simulation. Paddle's sandbox works but has fewer testing tools.

My Recommendation

Under $5,000 MRR, especially if you sell to EU customers: use Paddle.

The time you save on tax compliance, chargeback handling, and invoice generation is worth more than the fee difference. You should be building features and acquiring customers, not debugging VAT edge cases in Slovenia. Paddle lets you ship billing in an afternoon and forget about it.

Above $10,000 MRR, or if you need deep checkout customization: use Stripe.

At this scale, you can afford to systematize the tax compliance work. The per-transaction savings add up. And Stripe's flexibility lets you build billing experiences that Paddle's checkout overlay can't match.

Between $5,000 and $10,000 MRR: This is the gray zone. If you're still a solo dev or a tiny team, stay on Paddle. If you've hired help and your accountant has capacity, the Stripe migration makes sense.

One more thing to consider. Switching from Paddle to Stripe (or vice versa) mid-flight is painful. Active subscriptions can't be cleanly migrated. Customers may need to re-enter payment details. You could lose 10-20% of subscribers in the churn. So pick the one that fits your next 12-18 months, not just today.

FAQ

Can I start with Paddle and switch to Stripe later?

You can, but it's not seamless. Paddle is the Merchant of Record, so they own the customer billing relationship. When you migrate, each customer needs to set up a new subscription with Stripe. There's no automatic migration path. Plan for some churn.

Does Paddle's checkout hurt conversion rates?

Paddle's overlay checkout is polished and trusted, but it does briefly take the customer out of your UI. Some developers report no measurable difference. Others see a small drop. If your audience is technical (developers, designers), they're less likely to be spooked by a Paddle checkout. If you're selling to enterprise buyers, a branded Stripe checkout embedded in your app may convert better.

What about Lemon Squeezy as an alternative?

Lemon Squeezy is another Merchant of Record platform (now owned by Stripe). It's popular with indie developers and often compared to Paddle. However, there's no official Laravel Cashier package for Lemon Squeezy. You'd need a third-party integration or build your own. If Laravel-native billing is important to you, it's Stripe or Paddle.

Do I still need an accountant with Paddle?

Yes, but your accountant's job gets much simpler. Paddle sends you a monthly payout with a single invoice for their services. Your accountant records one line item of income instead of hundreds of individual transactions with varying tax treatments across jurisdictions. It's the difference between a 30-minute task and a multi-hour one.

Is the 5% + $0.50 negotiable with Paddle?

Paddle offers custom pricing for businesses processing over $50,000/month. If you're approaching that volume, reach out to their sales team. At scale, the negotiated rate can close much of the gap with Stripe.

Wrapping Up

The right choice depends on where you are, not where you want to be. If you're in the first year of a bootstrapped SaaS, every hour you spend on billing infrastructure is an hour you're not spending on the product. Paddle's higher fee buys you that time back. If you're past product-market fit and optimizing unit economics, Stripe's lower fees compound into real savings.

Both laravel/cashier and laravel/cashier-paddle are well-maintained, first-party packages with official Laravel documentation. The integration quality won't be your bottleneck either way. If you're building a Laravel SaaS and want help picking the right billing setup for your stage, get in touch.

Multi-Tenancy + Queues: The Three Bugs Every Laravel SaaS Hits in Its First Year

Hafiz — Mon, 15 Jun 2026 05:54:01 +0000

Your multi-tenant Laravel app works perfectly in development. Every test passes. You push to production, onboard your first ten customers, and everything looks fine. Then one morning a customer emails you a screenshot of someone else's dashboard data.

That's not a hypothetical. It's what happens when multi-tenancy and queues collide without the right safeguards. The combination is tricky because queue workers are long-running daemons. Unlike HTTP requests (which boot fresh for every visitor), a queue worker starts once and processes hundreds of jobs sequentially. Any tenant state left over from one job bleeds into the next.

I've seen three specific bugs come up again and again in multi-tenant Laravel SaaS apps. They're all silent. They don't throw exceptions in local development. They don't fail your test suite. And they can leak data between tenants in production. Here's what they are and how to fix each one.

Bug 1: Tenant Context Evaporates in Queued Jobs

This is the classic one, and it's the scariest because it fails silently.

You dispatch a job from a controller while Tenant A is active. The job gets serialized to the queue. A worker picks it up seconds later. But the worker process has no idea which tenant dispatched that job. It's running in the central (landlord) context, or worse, it's still holding stale context from the previous job it processed for Tenant B.

Here's the flow that causes the data leak:

The problem gets worse if you're using SerializesModels. Laravel's model serialization stores the model's ID and class name, then rehydrates the model when the job runs. But rehydration calls newQueryForRestoration(), which applies any global scopes, including your BelongsToTenant scope. That scope tries to filter by tenant_id, but tenant_id is null because no tenant is active yet. The query returns nothing. ModelNotFoundException. Your job fails, but the real cause is buried under a misleading error message.

The worst part? This never shows up in tests. Most test suites use Queue::fake() or the sync driver, which processes jobs inline with no serialization round-trip. The bug only appears with a real queue worker.

And it's hard to spot in production too. If your models don't use tenant-scoped global scopes, you won't even get exceptions. The job will happily query the central database, find nothing (or find the wrong tenant's data), and complete "successfully." You'll only discover the problem when a customer reports seeing data that isn't theirs. Or worse, when they don't report it because they didn't notice.

Here's how to detect it before a customer does. Add a sanity check at the start of every tenant job's handle() method during your early production phase:

public function handle(): void
{
    if (! tenant()) {
        report(new \RuntimeException(
            "Job " . static::class . " ran without tenant context. "
            . "Expected tenant: {$this->tenantId}"
        ));
        $this->fail();
        return;
    }

    // Proceed with actual job logic...
}

This gives you an early warning in your error tracker instead of a silent data leak. Remove it once you've confirmed your bootstrapper is working correctly.

The Fix

Both major tenancy packages handle this, but you have to explicitly enable it.

With stancl/tenancy (v3.10):

Enable the QueueTenancyBootstrapper in your config/tenancy.php:

'bootstrappers' => [
    Stancl\Tenancy\Bootstrappers\DatabaseTenancyBootstrapper::class,
    Stancl\Tenancy\Bootstrappers\CacheTenancyBootstrapper::class,
    Stancl\Tenancy\Bootstrappers\QueueTenancyBootstrapper::class, // Add this
],

This serializes the current tenant's ID into the job payload and restores tenant context before the job runs. But there's a catch. The bootstrapper fires after SerializesModels tries to rehydrate your models. So don't pass tenant-scoped Eloquent models directly into job constructors. Pass the ID instead:

// Bad: model rehydration runs before tenant context is restored
class ProcessInvoice implements ShouldQueue
{
    public function __construct(public Invoice $invoice) {}
}

// Good: pass the ID, query inside handle()
class ProcessInvoice implements ShouldQueue
{
    public function __construct(public int $invoiceId) {}

    public function handle(): void
    {
        // Tenant context is active by this point
        $invoice = Invoice::findOrFail($this->invoiceId);
        // Process it...
    }
}

With spatie/laravel-multitenancy (v4.1):

Set queues_are_tenant_aware_by_default to true in config/multitenancy.php. Or implement the TenantAware marker interface on individual jobs:

use Spatie\Multitenancy\Jobs\TenantAware;

class ProcessInvoice implements ShouldQueue, TenantAware
{
    // This job will automatically run in the correct tenant context
}

Jobs that should explicitly run in the central context can implement NotTenantAware instead. The same SerializesModels warning applies here: pass IDs, not models.

Bug 2: Cache Key Collisions Across Tenants

This bug is quieter than the first one. No exceptions, no failed jobs. Just wrong numbers on a dashboard that nobody notices for weeks.

Imagine you cache a dashboard stat:

Cache::put('monthly_revenue', $total, now()->addHour());

That key, monthly_revenue, is the same string for every tenant. If Tenant A's queue job processes a report and caches the result, Tenant B reads the same cache key and sees Tenant A's revenue figure.

The obvious fix is to prefix every cache key with the tenant ID manually. But that's error-prone because you'll forget it in at least one place. The better fix is to let the tenancy package handle prefixing globally.

The Fix

With stancl/tenancy:

The CacheTenancyBootstrapper (shown in the Bug 1 config above) automatically prefixes all cache keys with the tenant's identifier. Every Cache::get() and Cache::put() call is transparently scoped. You don't change your application code at all.

But watch for these edge cases that the bootstrapper doesn't catch automatically:

// These need manual tenant scoping:

// 1. Redis locks
Cache::lock("report_generation_{$tenant->id}", 30);

// 2. Rate limiting keys
RateLimiter::attempt("api_{$tenant->id}_{$user->id}", 60, fn() => true);

// 3. Laravel Scout search indexes
// Use tenant-prefixed index names or a filterable tenant_id attribute

// 4. spatie/laravel-permission cache
// Set a tenant-specific cache key in config/permission.php

With spatie/laravel-multitenancy:

Add the PrefixCacheTask to your switch tenant tasks:

// config/multitenancy.php
'switch_tenant_tasks' => [
    \Spatie\Multitenancy\Tasks\SwitchTenantDatabaseTask::class,
    \Spatie\Multitenancy\Tasks\PrefixCacheTask::class, // Add this
],

This prefixes cache keys for memory-based stores like Redis and APC. The same edge cases apply: locks, rate limiters, and third-party package caches all need manual attention.

One more thing. If you're running Laravel Octane in a multi-tenant setup, you have an additional risk. Octane reuses the same application instance across requests. A stale cache prefix from a previous request's tenant can bleed into the next request if the bootstrapper doesn't reset properly between requests.

And cache isn't the only place where unprefixed keys cause cross-tenant leaks. Session cookies on wildcard domains (*.yourapp.com) can let a session from one tenant's subdomain work on another tenant's subdomain. Validation rules like Rule::unique('users', 'email') check the full table unless you scope them with a where clause. Rate limiting keys based on IP addresses mean tenants behind the same corporate proxy share rate counters. These aren't queue-specific bugs, but they compound when a queued job reads from a session or applies a validation rule without tenant scoping.

Bug 3: Failed Job Retries Run in the Wrong Tenant

Your tenancy bootstrapper serializes the tenant ID into the job payload. Jobs dispatch and process correctly. You think you're covered. Then a job fails.

This one is particularly nasty because it takes time to appear. Bugs 1 and 2 can show up on day one if you're paying attention. But Bug 3 only triggers when a job actually fails, and then only when someone retries it. Most SaaS apps don't have a robust retry workflow in their first few months. They're focused on getting things working, not recovering from failures. So this bug sits dormant, waiting for the first time an external API times out or a database connection hiccups.

Laravel stores failed jobs in the failed_jobs table. When you run php artisan queue:retry 5 three days later, the framework pulls the serialized payload, reconstructs the job, and dispatches it again. But here's the problem: the retry mechanism doesn't fire your tenancy bootstrapper the same way the original dispatch did.

With spatie/laravel-multitenancy, this was a confirmed bug in earlier versions. The tenant ID was embedded in the payload, but the retry path didn't restore tenant context before the job started processing. The job would run in whatever tenant context the worker happened to have at that moment, which could be the central database or a completely different tenant.

The Fix

The fix depends on your package version.

With stancl/tenancy v3.10: The QueueTenancyBootstrapper handles retries correctly in recent versions. The tenant ID is stored at the top level of the job payload and restored on retry. Verify this by inspecting a failed job's payload:

$failed = DB::table('failed_jobs')->find(5);
$payload = json_decode($failed->payload, true);

// You should see a tenant_id key at the top level
dd($payload['tenant_id']); // Should not be null

If tenant_id is missing from the payload, your bootstrapper isn't configured correctly. Go back to Bug 1 and ensure QueueTenancyBootstrapper is in your bootstrappers array.

With spatie/laravel-multitenancy v4.1: The MakeQueueTenantAwareAction in v4 handles this correctly. But if you're on an older version, you can listen for the retry event manually:

// In a service provider
use Illuminate\Queue\Events\JobRetryRequested;

Event::listen(JobRetryRequested::class, function ($event) {
    $payload = $event->payload();
    $tenantId = $payload['tenant_id'] ?? null;

    if ($tenantId) {
        $tenant = Tenant::find($tenantId);
        $tenant?->makeCurrent();
    }
});

Testing retries properly:

This is the part most teams skip. You can't test retries with Queue::fake(). You need an integration test that uses a real queue driver, dispatches a job that deliberately fails, then retries it and verifies the tenant context:

it('retries failed jobs in the correct tenant context', function () {
    $tenant = Tenant::factory()->create();
    $tenant->makeCurrent();

    // Dispatch a job that will fail on first attempt
    dispatch(new FailOnceJob($tenant->id));

    // Process the queue (job fails)
    Artisan::call('queue:work', ['--once' => true]);

    // Retry the failed job
    Artisan::call('queue:retry', ['id' => 'all']);

    // Process again (should succeed in correct tenant context)
    Artisan::call('queue:work', ['--once' => true]);

    // Assert the job ran in the correct tenant
    expect(DB::connection('tenant')->table('job_results')->count())->toBe(1);
});

The Audit Checklist

If you're running a multi-tenant Laravel application, here's a quick audit you can run right now:

Tenant context in jobs: Dispatch a job from a tenant context with the database or redis driver (not sync). Check whether the job runs against the correct tenant's data. If you're passing Eloquent models to job constructors, switch to passing IDs.

Cache isolation: Open tinker as Tenant A, run Cache::put('test', 'tenant-a'). Switch to Tenant B, run Cache::get('test'). If you get tenant-a back, your cache isn't scoped. Enable the cache bootstrapper or prefix task.

Failed job retries: Deliberately fail a tenant job, wait a minute, run queue:retry all. Check which tenant's database the retried job hit. If it's wrong, check your package version and bootstrapper configuration.

Queue topology: If one tenant dispatches a massive CSV export job, does it block jobs for every other tenant? Consider dedicating separate queues for heavy operations so one tenant's workload doesn't starve the rest.

Worker restart cadence: Queue workers hold state in memory. If you deploy a tenancy config change but don't restart workers, the old configuration stays active. Always run php artisan queue:restart after deploying changes to your tenancy bootstrappers or cache prefix configuration. In production, use a process manager like Supervisor that can gracefully restart workers on deploy.

FAQ

Do I need stancl/tenancy or spatie/laravel-multitenancy for this?

Not strictly. You can build tenant-aware queues manually by storing the tenant ID in every job and restoring context in handle(). But the packages automate the serialization, context restoration, and cache scoping. If you're already using one of them for your multi-tenancy implementation, enabling queue support is a few lines of config.

Can I use the sync queue driver to avoid these bugs?

Technically yes, because the sync driver processes jobs inline in the same request, so tenant context is always present. But the sync driver blocks the request until the job finishes, which defeats the purpose of using queues. These bugs only surface with async drivers (database, Redis, SQS), and that's exactly what you'll use in production.

Does Laravel Horizon help with tenant-scoped queues?

Horizon gives you visibility into what's happening on your queues, but it doesn't handle tenant context itself. You still need the tenancy package's queue bootstrapper for context restoration. That said, Horizon's queue balancing and monitoring are useful for spotting when one tenant's jobs dominate the queue.

What about database-per-tenant setups? Is the jobs table per tenant or central?

Keep the jobs and failed_jobs tables in the central (landlord) database. If you put them in tenant databases, the queue worker won't know which tenant database to connect to before it even picks up a job. Both stancl/tenancy and spatie/laravel-multitenancy recommend central job storage with tenant context serialized into the payload.

Should I run separate queue workers per tenant?

For most apps, no. A shared worker pool with tenant context in the payload works fine. Separate workers per tenant only makes sense if you have strict resource isolation requirements or tenants with wildly different job volumes. The complexity of managing dozens of worker processes usually isn't worth it until you're well past your first year.

Wrapping Up

Multi-tenancy and queues are both solved problems individually. The bugs live at the intersection, in the gap between "tenant context exists during the HTTP request" and "tenant context needs to exist in a background worker too." All three bugs share the same root cause: queue workers are long-lived processes that don't get fresh context the way web requests do.

The good news is that both stancl/tenancy (v3.10) and spatie/laravel-multitenancy (v4.1) have solid solutions for all three. But you have to enable them, test them with a real queue driver, and audit your cache keys. If you're building a multi-tenant SaaS on Laravel and want help getting the queue layer right, let's talk.

Every Livewire Public Property Is a Form Field: The Security Audit Every Laravel App Needs

Hafiz — Thu, 11 Jun 2026 08:18:27 +0000

Every public property in your Livewire component is sent to the browser. Every single one. The snapshot that Livewire uses to maintain state between requests includes every public property value in plain JSON. Your users can see them, modify them, and send them back to your server.

Most Laravel developers don't think about this. They write public $userId the same way they'd write a protected property on any other PHP class. The difference is that a regular PHP property lives only on the server. A Livewire public property lives on both sides, and the client side isn't yours.

This post covers what can go wrong, what already went wrong in production for thousands of apps, and how to audit your own components in about 30 minutes.

How the snapshot works

When Livewire renders a component, it serializes all public properties into a JSON snapshot that gets embedded in the page. On every subsequent request (a button click, a form submission, a wire:model update), the browser sends that snapshot back to the server. Livewire hydrates the component from the snapshot, applies the update, and sends a new snapshot back.

The attack vector is simple: the snapshot travels through the browser, and the browser is controlled by the user.

Anything in that snapshot can be changed before it comes back. IDs, status flags, prices, permissions, whatever your public properties hold.

The concrete attack

Here's a component that looks normal but is vulnerable:

use Livewire\Component;

class EditProfile extends Component
{
    public $userId;
    public $name;
    public $email;

    public function mount($userId)
    {
        $this->userId = $userId;
        $user = User::find($userId);
        $this->name = $user->name;
        $this->email = $user->email;
    }

    public function save()
    {
        User::find($this->userId)->update([
            'name' => $this->name,
            'email' => $this->email,
        ]);
    }
}

The problem: $userId is public. A user loading their own profile page sees their own ID in the snapshot. They open DevTools, change the ID to another user's ID, and the next save() call updates someone else's profile. No authentication bypass needed. No SQL injection. Just modifying a JSON value the server trusts implicitly.

This pattern shows up constantly in real codebases. Any component where a public property determines whose data gets read or written is vulnerable if the property isn't locked or the action doesn't re-authorize.

CVE-2025-54068: proof this matters

In July 2025, a critical vulnerability (CVE-2025-54068) was disclosed in Livewire v3 versions 3.0.0-beta.1 through 3.6.3. The flaw was in the property hydration mechanism itself, allowing unauthenticated attackers to achieve remote code execution by crafting malicious property updates. No authentication required. No user interaction needed.

The vulnerability was patched in v3.6.4. If you're running anything older, update immediately.

The broader lesson from this CVE is that the property hydration pipeline is a real attack surface. The RCE was the most severe example, but garden-variety property manipulation (changing IDs, toggling flags, modifying amounts) is something any developer with browser DevTools can do right now against your components.

Three ways to protect your components

1. Lock properties that shouldn't change

Livewire v3 introduced the #[Locked] attribute for exactly this problem. When a property is locked, any attempt to modify it from the client throws an exception.

use Livewire\Attributes\Locked;
use Livewire\Component;

class EditProfile extends Component
{
    #[Locked]
    public $userId;

    public $name;
    public $email;

    // ...
}

Now if someone modifies $userId in the snapshot, Livewire rejects the request before your code even runs. This is the simplest fix for any property that gets set during mount() and should never change after that.

Don't forget the import: use Livewire\Attributes\Locked;. Missing it is a silent failure.

2. Use Eloquent models instead of IDs

Livewire automatically protects Eloquent model IDs when you store the full model as a property:

class EditProfile extends Component
{
    public User $user;

    public function mount(User $user)
    {
        $this->user = $user;
    }

    public function save()
    {
        $this->user->update([
            'name' => $this->name,
            'email' => $this->email,
        ]);
    }
}

Livewire ensures the model's ID can't be tampered with. No #[Locked] needed. This is the recommended pattern for most components that operate on a single model. If you're storing $postId or $userId as a plain integer, ask yourself why you're not storing the model instead.

3. Authorize in every action method

Even with locked properties, action parameters are still modifiable. The wire:click="delete({{ $post->id }})" in your Blade template sends the post ID as an argument, and that argument can be changed in the browser.

Always authorize:

public function delete($postId)
{
    $post = Post::findOrFail($postId);

    if ($post->user_id !== auth()->id()) {
        abort(403);
    }

    $post->delete();
}

Never trust that the value coming from the browser is the same value you rendered. Treat every Livewire action parameter exactly like you'd treat a POST request parameter. Validate and authorize every time.

The 30-minute audit

Run these searches against your Livewire components. Each one finds a potential vulnerability.

Find unlocked ID properties:

grep -rn 'public \$.*[Ii]d' app/Livewire/ | grep -v '#\[Locked\]'

Any result that stores an ID without #[Locked] or without being a full Eloquent model binding is a candidate for fixing.

Find action methods that trust their parameters:

grep -rn 'function delete\|function update\|function remove\|function approve' app/Livewire/

Check each result: does the method verify that the authenticated user has permission to perform the action on the specific resource? If it goes straight from parameter to database query without authorization, it's vulnerable.

Find components that use $this->someId in queries without authorization:

grep -rn 'find(\$this->' app/Livewire/

Every find($this->someId) should be followed by an authorization check, or the property should be #[Locked].

Once you've fixed the patterns, write Pest tests that attempt to tamper with locked properties and verify the exceptions fire. Automated tests catch regressions when someone removes a #[Locked] attribute without realizing what it protects.

For a broader security audit covering Composer dependencies and supply chain risks, the Composer audit guide walks through the process of checking what you've actually installed.

What Livewire does and doesn't protect

A few things Livewire handles for you that are worth knowing:

Middleware re-application. If your Livewire component is loaded via a route with authorization middleware (like can:update,post), Livewire re-applies that middleware on every subsequent request. So a user who loads the page but then loses permission will be blocked on the next interaction.

Model property IDs. As mentioned, storing a full Eloquent model as public User $user protects the model ID automatically.

Checksum validation. Livewire signs its snapshots with the application key. This prevents wholesale snapshot forgery. But it doesn't prevent modification of individual property values, the checksum covers the snapshot's structure, not the content of mutable properties.

What Livewire does NOT protect: plain public property values (integers, strings, booleans), action method parameters, and any property you don't explicitly lock.

FAQ

Should I lock every public property?

No. Properties bound to wire:model need to be mutable. Lock the properties that get set in mount() and should never change: IDs, user references, permission flags, anything that determines whose data the component operates on.

Does #[Locked] work on Livewire 4?

Yes. The attribute exists in both Livewire v3 and v4. The import is use Livewire\Attributes\Locked; in both versions.

Can I use protected properties instead?

Protected properties don't persist between Livewire requests. They're fine for static values you set once and never need again, but any runtime data that must survive between user interactions has to be a public property. That's why #[Locked] exists: it gives you the persistence of a public property with the safety of a protected one.

Is this only a problem with Livewire, or does Inertia have the same issue?

Inertia sends props to the frontend too, but Inertia props are read-only on the client. The client doesn't send them back on subsequent requests. Livewire's two-way sync is what creates the attack surface. Inertia forms use explicit POST requests with validated data, so the pattern is fundamentally different.

My app is behind authentication. Am I still at risk?

Yes. The attack doesn't require being unauthenticated. A logged-in user can modify their own component's snapshot to access or modify another user's data. Authentication proves who someone is, authorization proves what they're allowed to do. You need both.

The takeaway

Every time you write public $something in a Livewire component, ask yourself one question: what happens if the user changes this value? If the answer is "something bad," lock it with #[Locked] or store the full Eloquent model instead.

The 30-minute audit above catches the most common patterns. Run it once, fix what you find, and add #[Locked] to your mental default for any property that determines data ownership.

Security at the application layer and security at the server layer are different problems. For the infrastructure side, the VPS hardening guide covers closing ports, hiding your IP, and locking SSH. Both layers matter.

Got a Livewire app you want audited? Get in touch.

How I Refactored a 1,200-Line Filament Resource Into Something I Could Actually Maintain

Hafiz — Wed, 10 Jun 2026 07:20:19 +0000

You know the resource is in trouble when scrolling to table() takes three full page-downs past the form definition. When every pull request touches the same file because everything lives in one place. When adding a column to the table means scrolling past 400 lines of form fields to find where the table starts.

Filament resources grow faster than almost any other file in a Laravel project. The framework makes it easy to define forms, tables, actions, filters, and relations in one class, which is great for small models. But for anything complex, that single class becomes the most dangerous file in your codebase: too long to navigate, too coupled to test, too fragile to change.

I hit this with a resource that managed a multi-step onboarding flow. The form had tabs, conditional fields, repeater components, and custom validation. The table had 15 columns, 6 filters, and 4 custom actions. The resource file was 1,247 lines. Every time I opened it, I spent more time scrolling than coding.

This post walks through four levels of extraction I used to bring it back under control. Each level is independent. You can apply one, two, or all four depending on how large your resource is and how much refactoring time you have.

Level 1: Split form and table into methods

This takes five minutes and immediately makes the file navigable.

Instead of defining everything inline in form() and table(), extract logical sections into static methods within the same class:

class OrderResource extends Resource
{
    public static function form(Form $form): Form
    {
        return $form->schema([
            Tabs::make('Order')
                ->tabs([
                    Tab::make('Details')->schema(static::detailsFormSchema()),
                    Tab::make('Shipping')->schema(static::shippingFormSchema()),
                    Tab::make('Payment')->schema(static::paymentFormSchema()),
                ]),
        ]);
    }

    protected static function detailsFormSchema(): array
    {
        return [
            TextInput::make('order_number')->disabled(),
            Select::make('status')->options(OrderStatus::labels()),
            Select::make('customer_id')
                ->relationship('customer', 'name')
                ->searchable()
                ->preload(),
            // ... 15 more fields
        ];
    }

    protected static function shippingFormSchema(): array
    {
        return [
            TextInput::make('shipping_address'),
            TextInput::make('shipping_city'),
            Select::make('shipping_country')
                ->options(Country::pluck('name', 'code')),
            // ...
        ];
    }

    protected static function paymentFormSchema(): array
    {
        // ...
    }
}

Do the same for the table:

public static function table(Table $table): Table
{
    return $table
        ->columns(static::tableColumns())
        ->filters(static::tableFilters())
        ->actions(static::tableActions())
        ->bulkActions(static::tableBulkActions());
}

protected static function tableColumns(): array
{
    return [
        TextColumn::make('order_number')->sortable()->searchable(),
        TextColumn::make('customer.name')->sortable(),
        BadgeColumn::make('status')->colors(OrderStatus::colors()),
        TextColumn::make('total')->money('eur')->sortable(),
        // ...
    ];
}

This doesn't reduce line count, but it makes the file navigable. You can collapse methods in your IDE. The form() method becomes 10 lines instead of 200. You can jump directly to shippingFormSchema() when that's the section you need to edit.

When to use this: Always. Even for small resources, this is good practice. It costs nothing and pays off immediately.

Level 2: Extract form sections into separate classes

When a form section has 20+ fields or complex conditional logic, extract it into its own class. This is where the real line count reduction happens.

Create a class that extends Filament\Forms\Components\Section:

namespace App\Filament\Forms\Sections\Order;

use Filament\Forms\Components\Section;
use Filament\Forms\Components\TextInput;
use Filament\Forms\Components\Select;

class ShippingSection extends Section
{
    public static function make(string $heading = 'Shipping'): static
    {
        return parent::make($heading)
            ->schema([
                TextInput::make('shipping_address')
                    ->required()
                    ->maxLength(255),
                TextInput::make('shipping_city')
                    ->required(),
                Select::make('shipping_country')
                    ->options(Country::pluck('name', 'code'))
                    ->searchable()
                    ->required(),
                TextInput::make('shipping_postal_code'),
                TextInput::make('shipping_phone'),
            ])
            ->columns(2)
            ->collapsible();
    }
}

Now the resource references it with one line:

use App\Filament\Forms\Sections\Order\ShippingSection;

public static function form(Form $form): Form
{
    return $form->schema([
        Tabs::make('Order')->tabs([
            Tab::make('Details')->schema(static::detailsFormSchema()),
            Tab::make('Shipping')->schema([
                ShippingSection::make(),
            ]),
            Tab::make('Payment')->schema([
                PaymentSection::make(),
            ]),
        ]),
    ]);
}

Each section class owns its fields, validation, and layout. The resource file drops from 1,200 lines to maybe 200. And if the same shipping form is needed in another resource (like a CustomerResource or a ReturnResource), you reuse the section class without duplicating a thing.

Directory structure I use:

app/Filament/Forms/Sections/
    Order/
        ShippingSection.php
        PaymentSection.php
        DetailsSection.php
    Customer/
        PersonalInfoSection.php
        AddressSection.php

When to use this: When a form section has more than 15 fields, when the same fields appear in multiple resources, or when a section has complex conditional logic that makes the resource file hard to read.

Level 3: Extract table actions into Action classes

Filament table actions defined inline add up fast. A single action with a confirmation modal, form fields, and business logic can be 30-50 lines. Four actions and you're at 200 lines just for the actions array.

The solution: create dedicated Action classes. Here's a pattern adapted from Johannes Pichler's approach:

namespace App\Filament\Actions\Order;

use Filament\Tables\Actions\Action;
use Filament\Notifications\Notification;

class MarkAsShippedAction
{
    public static function make(): Action
    {
        return Action::make('mark-as-shipped')
            ->label('Mark Shipped')
            ->icon('heroicon-o-truck')
            ->requiresConfirmation()
            ->action(function ($record) {
                $record->update(['status' => 'shipped']);
                $record->customer->notify(new OrderShippedNotification($record));

                Notification::make()
                    ->title('Order marked as shipped')
                    ->success()
                    ->send();
            })
            ->visible(fn ($record) => $record->status === 'processing');
    }
}

In the resource, the action registration becomes one line:

protected static function tableActions(): array
{
    return [
        MarkAsShippedAction::make(),
        SendInvoiceAction::make(),
        RefundAction::make(),
        Tables\Actions\EditAction::make(),
    ];
}

Each action is testable independently. Each action can be reused across resources if needed. And the resource file doesn't grow every time you add a new action.

When to use this: When actions contain business logic beyond simple CRUD. If the action is just EditAction::make() or DeleteAction::make(), leave it inline. Extract when the action has custom logic, confirmations, form fields, or notifications.

For a broader framework on when to extract logic into Actions versus Services, the Service vs Action vs Job decision tree covers the general principles.

Level 4: Use page-level overrides

Filament resources delegate to page classes for Create, Edit, View, and List. Each page can override the form or table configuration from the resource. This is useful when your create and edit forms are significantly different.

namespace App\Filament\Resources\OrderResource\Pages;

use App\Filament\Resources\OrderResource;
use Filament\Resources\Pages\CreateRecord;
use Filament\Forms\Form;

class CreateOrder extends CreateRecord
{
    protected static string $resource = OrderResource::class;

    public function form(Form $form): Form
    {
        return $form->schema([
            // Simplified create form: only essential fields
            TextInput::make('customer_name')->required(),
            Select::make('product_id')->relationship('product', 'name'),
            TextInput::make('quantity')->numeric()->default(1),
        ]);
    }
}

The create form has 3 fields while the edit form (defined on the resource) has 40. Without this separation, you'd have conditional ->hidden() calls everywhere, making the form definition harder to follow.

When to use this: When create and edit forms differ significantly, when the list page needs a different table configuration than what the resource defines, or when a specific page has unique header actions.

How far to go

Not every resource needs all four levels. Here's the simple version:

Under 200 lines: Don't refactor. The resource is fine.

200-500 lines: Level 1 (method extraction). Takes five minutes. Do it.

500-1,000 lines: Levels 1 + 2 (method extraction + section classes). This handles most cases.

Over 1,000 lines: All four levels. Your resource is complex enough to justify the structure. The time spent refactoring pays back within a week of not scrolling past 400 lines of form fields to find the table definition.

The goal isn't to have the fewest lines in the resource. It's to make the resource navigable, testable, and safe to change. If you can open the file, find what you need in under 5 seconds, and change it without worrying about side effects, the refactoring worked.

For the broader architecture of a Filament-based SaaS, the full SaaS guide covers the patterns beyond individual resources. And for the design patterns that underpin these extraction techniques, Strategy and Composition are the two that matter most here.

FAQ

Does extracting form sections affect Filament's reactivity (wire:model, conditional visibility)?

No. Extracted sections are just PHP classes that return the same component arrays. Livewire's reactivity is based on the rendered component tree, not on which PHP class defined the components. ->visible(fn (Get $get) => $get('status') === 'active') works identically whether it's defined in the resource or in a section class.

Should I use Traits instead of separate classes?

Traits work for small extractions (a shared set of filters, a common set of bulk actions). For form sections and table configurations, separate classes are better because they're independently testable and don't pollute the resource's namespace. A resource with 6 traits is just as hard to navigate as a resource with 1,200 lines.

What about the rmitesh/filament-action package?

It provides an artisan command to generate Filament action classes: php artisan make:filament-action CommentAction --resource=UserResource. If you're extracting many actions across multiple resources, it saves boilerplate. For a few extractions, the manual approach in Level 3 is lighter.

How do I test extracted section classes?

Instantiate the section, call the static make() method, and assert the schema contains the expected components. You can also use Filament's testing utilities to render a full form with the section and assert field values. The key benefit: you test the section without loading the entire resource.

Can I use this approach with Filament v4/v5?

Yes. The section and action extraction patterns work across Filament v3, v4, and v5. The component API is stable. The only thing that changes between versions is import paths and some method names, which are easy to update.

The result

After applying all four levels to that 1,247-line resource, the resource file itself dropped to 187 lines. The form is a list of section references. The table is a list of column and action references. Each section and action lives in its own file, testable and reusable.

The total line count across all files is actually higher than the original single file. That's the right trade-off. Code organization isn't about fewer lines. It's about each file doing one thing, being easy to find, and being safe to change without side effects.

Working with Filament on a project that's outgrowing its current structure? Get in touch.

I Stopped Putting Everything in Service Classes. Here's the Decision Tree I Use Now

Hafiz — Wed, 03 Jun 2026 14:39:11 +0000

A few years ago I had a UserService that had grown to 28 methods. It handled registration, email verification, password resets, subscription upgrades, profile updates, and account deletion. It was the most-imported class in the codebase and the most dangerous to touch. One change to the registration flow meant scrolling past 400 lines of code that had nothing to do with it.

At some point I stopped and asked myself what a Service class actually is in Laravel. There's no php artisan make:service command. No interface requirement. No convention in the framework documentation telling you what belongs there. We just started putting things in Services because someone told us to move logic out of controllers, and Services were the first pattern we learned.

The result is predictable. The controller gets thin. The Service gets fat. The problem moved, it didn't get solved.

This post is the decision tree I wish I'd had at the start.

The three patterns, briefly

Before the tree, a quick grounding on what each pattern actually does, because the language is inconsistent in the community.

A Service class groups related operations on the same domain object. A SubscriptionService knows how to subscribe a user, upgrade them, cancel them, and check their current plan. It holds methods, not just one. Think of it as the "everything about subscriptions" class. It can be stateful or stateless.

An Action class handles a single, atomic operation. CreateUser, SendPasswordResetEmail, ChargePaymentMethod. One class, one job, one public method. It can't be a Job because you need the result immediately. It can be reused from a controller, an Artisan command, another class, and a test. The key word is reuse across contexts.

A Job runs asynchronously on the queue. Full stop. That's the definition. If your code doesn't need to run in the background, it's not a Job, no matter how tempting it is to make it one. Jobs are for fire-and-forget work where you don't need the result before the HTTP response returns.

There's some overlap. But the overlap is a signal that you need to choose, not that both options are equivalent.

The decision tree

Walk through it with any piece of logic and you'll get an answer.

What goes wrong when you ignore the tree

The bloated Service. You create a UserService for user registration. Six months later someone adds password reset to it because, well, it's user-related. Then profile updates. Then account deletion. Then a method that checks if the user is eligible for a discount. Your Service is now a 600-line class with no coherent identity. Every test for registration pulls in the entire class including all the subscription logic you never wanted to touch.

The fix: split by responsibility, not by model. RegistrationService handles registration. PasswordResetService handles password resets. Or, if those operations are simple and atomic, make them Actions instead.

The Action folder explosion. The opposite problem. You adopt the Action pattern and start creating an Action for every single thing. GetUserByEmailAction. FormatDateAction. ValidatePostcodeAction. After 200 files, navigating app/Actions is slower than just looking in the controller.

Actions should answer a clear question: "Would I want to call this from a controller and from an Artisan command and from a queue job?" If the answer is no, keep it inline.

Jobs used as glorified Actions. The most common mistake. You've got some logic that feels heavy, so you make it a Job. But you dispatch it synchronously with dispatch()->now(), or you realise you need the return value, so you jump through hoops. A Job that you always dispatch synchronously and need a result from is just an Action wearing the wrong costume. Make it an Action.

Real examples from production

A few scenarios I've hit that show how the tree plays out.

Charging a subscription. Is it async? No. You need the result to know whether to give the user access. Single operation? Yes. Used in multiple places (web checkout, API checkout, CLI seeder)? Yes. This is an Action: ChargeSubscription::handle($user, $plan).

Sending a weekly digest email to 50,000 users. Async? Yes. Job. You chunk the users, dispatch one Job per batch, move on. The Job calls a Mailable. You don't need the result in the HTTP response.

Everything related to how a subscription works. Subscribe, cancel, check status, apply promo code, handle webhook from Stripe. These are multiple operations on the same domain concept, with shared logic (checking existing state before changing it). This is a Service: SubscriptionService. Each method handles one transition, but they all need to know about each other.

Sending a single transactional email. Async? Yes, probably. But Mail::queue() handles that. You don't need a Job class wrapping a Mailable. The Mailable itself handles queueing when sent via Mail::queue(). This is one of those cases where the extra class adds ceremony without adding value.

The part people argue about

The honest version of this debate is that Service vs Action is often a team preference more than a technical requirement. Both work. The real risk isn't choosing the wrong one. It's applying one pattern to everything regardless of fit.

I use Services when I'm working on a domain area with multiple operations that share state or context. I use Actions when I have a single operation I know I'll call from multiple places. I use neither when the logic is simple enough to live in the controller and I don't expect to reuse it.

The rule I enforce on my own projects: if a class has more than five methods or more than 150 lines, it needs to be split or reconsidered. That ceiling forces the question "what does this class actually do?" before it becomes a dumping ground.

For a deeper look at async patterns and how Jobs fit into a larger queue architecture, the queue jobs guide covers sizing workers, retries, and the production setup worth knowing before you start dispatching at scale.

FAQ

Should I always use an Action over a Service for new code?

Not always. Actions work best for atomic, stateless operations with a single entry point. If you're building a domain area (subscriptions, invoicing, notifications) where multiple operations share context, a Service is cleaner. The question to ask is: does this class do one thing, or does it know everything about a concept?

Where should Actions live in the directory structure?

app/Actions/. For larger projects, namespace further by domain: app/Actions/Billing/ChargeSubscription.php. Keep the name as a verb-noun pair: CreateUser, SendPasswordReset. Avoid names like UserAction. That's just a Service with a different suffix.

What about the lorisleiva/laravel-actions package?

It's a solid package. It lets a single Action class run as a controller, a Job, a listener, and a command depending on context. Worth considering if your team commits to the pattern across the codebase. For testing Actions and Services, the Pest 4 testing guide covers the isolation patterns. It adds real value when you have Actions that need to run in multiple contexts. For simpler projects it's additional overhead.

Can a Job call an Action?

Yes, and this is often the right pattern. The Job handles the queue mechanics (retries, delays, backoff). The Action handles the actual logic. ProcessSubscriptionRenewal::handle() dispatches work, calls ChargeSubscription::handle(), and handles the queue-specific failure cases. Clean separation.

What about Events and Listeners?

Events and Listeners are for decoupled side effects after something happens. The Events, Listeners, and Observers guide covers the patterns in depth. A user registered, fire UserRegistered, let the listeners handle the welcome email, the onboarding sequence, the analytics event. Don't use Actions or Services for this. That's the Events system doing its job. The relationship is: Actions and Services cause things to happen, Events communicate that they happened.

The actual takeaway

The pattern you choose matters less than applying it consistently and knowing when to break from it. Service classes aren't wrong. Actions aren't always better. Jobs aren't for synchronous logic dressed up with a queue.

The moment a class starts doing too many things, it's a signal to reach for the tree.

Got a codebase you're trying to untangle? Get in touch.

Laravel Cloud vs Forge vs Hetzner: What I'd Actually Pick at Each Stage

Hafiz — Mon, 01 Jun 2026 04:45:13 +0000

Most developers make the infrastructure decision based on what they know, not what fits the project. They pick Laravel Cloud because it's new, or Forge because a senior dev on their team uses it, or a bare VPS because it looks cheap. None of those are reasons. They're starting points.

The right choice at 500 users is often the wrong one at 50,000. And the cost difference between these options isn't what most people expect. The invoice number is only part of it.

Here's what each option actually costs at three stages, using current May 2026 pricing. The goal isn't to declare a winner. It's to give you the real numbers so you can make the call that fits where you are right now.

What you're comparing

A quick clarification before the numbers, because people mix these up:

Laravel Cloud is a managed PaaS built by the Laravel team. You push your code and it handles servers, autoscaling, databases, SSL, queue workers, and deployments. You never SSH anywhere.

Laravel Forge is a server management layer. You still own the VPS and pay for it separately. Forge handles provisioning, Nginx config, deployments, SSL, and queue workers. You keep server-level control without doing the tedious parts manually.

A bare Hetzner VPS is just a server. You install PHP, configure Nginx, manage SSL renewals, set up queue workers, write deploy scripts. Everything is yours.

The numbers at each stage

Under 1,000 users

Side projects, early MVPs, apps you're not sure will stick.

Option	Monthly base	Typical all-in
Laravel Cloud Starter	$0	$4-8/month
Forge Hobby + Hetzner CX22	$12 + €4.49	~$17/month
Bare Hetzner CX22	none	€4.49 (~$5/month)

At this stage the differences are real but small in absolute terms. Cloud's Starter tier is pay-as-you-go with no base fee. A small app with modest traffic runs $4-8/month. The Forge Hobby + Hetzner CX22 combo costs more upfront but gives you direct server access. A bare Hetzner CX22 at €4.49/month after the April 2026 price increase is still excellent value for 2 vCPUs and 4GB RAM.

Worth noting: Hetzner CX22 is roughly 3x cheaper than a comparable DigitalOcean droplet for equivalent specs. If you're choosing the VPS path, Hetzner is the obvious pick in Europe and increasingly popular for US projects too.

1,000 to 10,000 users

You've found traction. Deployment and uptime start mattering.

Option	Monthly base	Typical all-in
Laravel Cloud Growth	$20	$25-45/month
Forge Growth + Hetzner CX32	$19 + ~€9	~$30/month
Bare Hetzner CX32	none	~€9 (~$10/month)

Cloud Growth at $20/month plus usage lands around $25-45/month depending on traffic patterns. Forge Growth at $19/month plus a mid-range Hetzner server is competitive at roughly $30/month total. The bare VPS is still cheapest in cash at $10/month, but the operational work starts adding up.

For a developer shipping features, the real question isn't "which is cheapest," it's this: how many hours a month am I spending on server maintenance versus building product? At 5,000 users, a misconfigured Nginx config or a failed deployment script starts costing you real time.

10,000 to 100,000 users

Infrastructure decisions affect your margins and your incident response.

Option	Typical monthly cost	Notes
Laravel Cloud Growth	$60-200+	Usage scales with traffic
Forge Business + multiple Hetzner	$39 + $40-80	More DevOps work
Bare VPS (load balanced)	$25-60	Cheapest, most complex

At this scale, Cloud's autoscaling is the right call if your traffic is unpredictable. Traffic spikes that would take down a single Hetzner server get absorbed automatically. But that scaling costs money. Usage-based billing at this volume can push your monthly bill well above the base fee. Spend caps are announced for Cloud but not yet live as of this writing. The Laravel Cloud post covers what's coming on that front.

Forge at this scale means managing multiple servers, a load balancer, and probably a separate Redis instance. The Business plan at $39/month includes monitoring and automated database backups, which you need at 100k users. The Hetzner bill grows with your server count. Total lands at $80-120/month depending on architecture.

A bare VPS setup at this scale requires real infrastructure work, load balancers, Redis clusters, backup scripts, monitoring. It's the cheapest option but it's a part-time job.

What doesn't show up on the invoice

Your time. A bare VPS is cheap in cash but expensive in hours. Initial setup for someone who knows what they're doing is 3-5 hours. Ongoing maintenance is roughly 2 hours a month: security patches, PHP updates, debugging a failed deployment on a Friday evening. Multiply your hourly rate by that and the VPS isn't cheap anymore.

Forge cuts ongoing maintenance to near zero and initial setup to under an hour. Cloud cuts it entirely.

The deployment pipeline. Forge gives you zero-downtime deployments out of the box. On a bare VPS you configure that yourself. It's learnable. The CI/CD with GitHub Actions guide covers the setup, but it takes time you could spend shipping. Cloud handles it without any configuration.

Autoscaling anxiety vs bill anxiety. These are the two risks you're trading off. On a bare VPS or Forge, a traffic spike can take you down. On Cloud, a traffic spike drives up your bill. Neither is "safe," they're just different failure modes. Cloud's spend caps will help when they ship.

What I'd actually pick at each stage

Side project or early MVP: Bare Hetzner CX22 at €4.49/month. It's cheap enough to be disposable and the constraint forces you to understand what you actually need. When server maintenance starts interrupting feature work, that's the signal to move up.

Solo developer with a growing SaaS: Forge Growth + Hetzner CX32 at roughly $30/month total. You get the deployment automation, SSL, queue workers, and server monitoring without giving up control. It's where the best price-to-control ratio lives. Pair it with the VPS hardening guide to get the security layer sorted once and forget about it.

Small team building a product: Laravel Cloud Growth. When multiple developers are deploying, having one person own the servers creates a bottleneck. Cloud removes that entirely. Preview environments per PR are a real productivity win at this stage.

Agency managing client sites: Forge Business at $39/month. Unlimited servers, automated database backups, and server monitoring across all client projects. The per-client cost when split across 10 sites is negligible.

App with unpredictable traffic: Laravel Cloud. Product Hunt launches, viral moments, seasonal spikes. If your traffic can 10x overnight, you want autoscaling and you don't want to be the one managing it at midnight. The full SaaS architecture guide covers how to structure the app layer to take full advantage of Cloud's scaling.

FAQ

Can I switch from Forge or a bare VPS to Laravel Cloud later?

Yes. It's a deployment change, not a code change. Your Laravel app runs identically on both. The migration is mainly about moving your database and updating your deployment pipeline. Most teams do it in a day.

What's the real total cost of Forge?

Forge Growth is $19/month plus your VPS. A Hetzner CX22 at €4.49/month brings the total to roughly $24-25/month. That's competitive with Cloud's Starter tier but with unlimited servers and flat-rate billing, so no usage surprises.

Does Laravel Cloud handle queue workers and cron jobs?

Yes. Queue workers and cron jobs are first-class features on Growth and above. It's one of the things that makes Cloud well-suited for SaaS, where background processing is usually essential.

What about Laravel Vapor?

Vapor runs on AWS Lambda at $39/month plus AWS usage. It's the right choice for workloads with extreme traffic variability or teams deep in the AWS ecosystem. For most Laravel developers, Cloud or Forge fits better.

Is the $5/month plan for Laravel Cloud available yet?

Not as of this writing. The Laravel team announced it as coming soon in May 2026. The current entry point is the Starter tier with no base fee and pay-as-you-go usage, which runs $4-8/month for a small app.

The honest version

The developers who regret their infrastructure choice usually overbuilt early or held on to a cheap setup for too long. A €4.49 Hetzner server handles your first 10,000 users fine if it's set up correctly. Cloud makes sense when your traffic becomes unpredictable or when server maintenance is competing with feature work. Forge sits in the middle and is the right answer for more situations than it gets credit for.

Start with the cheapest option that doesn't slow you down. Upgrade when the friction becomes real, not before.

Got a side project or SaaS and want a second opinion on the infrastructure setup? Get in touch.