DEV Community: Hafiz

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.

Laravel AI SDK Silently Kills Your Horizon Queue (And How to Fix It in 4 Config Changes)

Hafiz — Wed, 27 May 2026 09:20:13 +0000

Your Horizon was healthy. Email jobs, notifications, small processing tasks, all running fine with zero issues. You added the AI SDK, wrapped a few agent calls in background jobs, and deployed to production. Within a week you noticed failed jobs nobody reported, one user received the same AI analysis twice, and on a Tuesday morning when five report jobs queued simultaneously, your email queue froze for eight minutes.

Nothing threw an exception. No alerting fired. Horizon's dashboard showed a handful of failed jobs and then everything looked normal again. The failure mode is invisible because the worker doesn't crash. It gets killed mid-execution, Horizon records the failure silently, and there's no stack trace and no message, nothing to debug.

The problem isn't the AI SDK. It's that Horizon's default configuration was designed for jobs measured in milliseconds. AI API calls take 30 to 120 seconds. Four specific default values in your config silently conflict with that reality, and three of them aren't in config/horizon.php. They're scattered across your codebase in ways you'd only find if you knew to look.

If you're new to Laravel's queue system and want to understand the fundamentals before tuning Horizon specifically, the Laravel queue jobs guide covers job structure, retries, and failure handling from the ground up.

Why AI jobs break Horizon's defaults

Horizon's default supervisor configuration assumes jobs are fast. A worker polls the queue, picks up a job, executes it in a second or two, picks up the next one. The defaults reflect this: a 60-second timeout before the worker is killed, a retry_after value in the 90-second range before a job is considered stuck, and no backoff delay between retries.

AI SDK jobs break every one of these assumptions. A single Agent::run() call that uses tools, generates structured output, or hands off to a sub-agent can legitimately take 45 to 90 seconds before it returns. When you layer in the sub-agent patterns that chain multiple providers, job duration climbs further.

Here's what actually happens when that 90-second AI job runs on a default Horizon setup:

The SIGKILL at step four is silent. Horizon marks the job as failed with no visible error in the dashboard UI beyond the failure count incrementing. There's no stack trace, no message from the AI provider, no PHP exception in your logs. Most developers spend hours looking for an application error that doesn't exist, because the job never threw one.

The double-processing at step seven is the worst part. Laravel's official Horizon documentation warns about it explicitly: "the timeout value should always be at least a few seconds shorter than the retry_after value... otherwise, your jobs may be processed twice." But almost nobody reads that warning until after a user reports seeing duplicate results.

Four changes fix all of this cleanly.

Change 1: Set a supervisor timeout that reflects AI job duration

Horizon's default supervisor timeout is 60 seconds. That's the value in config/horizon.php under each supervisor's configuration. When a job runs longer than this, the worker process receives SIGKILL and is forcefully terminated.

// config/horizon.php: what ships by default
'supervisor-1' => [
    'connection' => 'redis',
    'queue' => ['default'],
    'balance' => 'auto',
    'processes' => 10,
    'timeout' => 60, // kills any job taking longer than 60 seconds
    'tries' => 1,
],

For AI jobs, raise this to something that reflects the realistic upper bound of your slowest agent call. 300 seconds (five minutes) is a sensible ceiling for most production AI workloads:

'supervisor-ai' => [
    'connection' => 'redis',
    'queue' => ['ai'],
    'balance' => 'auto',
    'processes' => 3,
    'timeout' => 300,
    'tries' => 2,
    'memory' => 512,
],

The Horizon docs note a critical constraint: "always ensure the Horizon timeout is greater than any job-level timeout, otherwise jobs may be terminated mid-execution." So if you define $timeout on the job class itself, the supervisor timeout must exceed it by a few seconds.

class RunAiReportJob implements ShouldQueue
{
    // Job-level timeout: must be < supervisor timeout
    public int $timeout = 270;
}

Setting the job-level timeout slightly below the supervisor timeout means clean termination happens at the job level first, which triggers the failed() method and gives you a cleanup hook. A SIGKILL from the supervisor sends a process signal that skips failed() entirely, leaving any in-progress state (partially written database rows, uncleaned temp files, open API sessions) without cleanup. For AI jobs that write intermediate results or update progress columns, this distinction matters.

Change 2: Fix retry_after to prevent double processing

This is the one that causes duplicate user output, and it lives in config/queue.php, not in config/horizon.php. That's why most developers miss it.

The retry_after value defines how many seconds Redis waits before assuming a job is stuck and re-queuing it. The default for the Redis connection is 90 seconds. After you raise your supervisor timeout to 300, that 90-second retry_after means any job running longer than 90 seconds gets re-queued while the original is still executing.

// config/queue.php: the default Redis connection
'redis' => [
    'driver' => 'redis',
    'connection' => 'default',
    'queue' => env('REDIS_QUEUE', 'default'),
    'retry_after' => 90, // danger: shorter than the AI supervisor timeout
    'block_for' => null,
],

Laravel's docs say this directly: timeout must be shorter than retry_after. So if your supervisor timeout is 300 seconds, retry_after needs to be at least 300 plus a buffer. Add 60 seconds as the minimum buffer:

'redis' => [
    'driver' => 'redis',
    'connection' => 'default',
    'queue' => env('REDIS_QUEUE', 'default'),
    'retry_after' => 360, // supervisor timeout (300) + 60s buffer
    'block_for' => null,
],

This is the change most likely to already be causing silent problems in your app. The double-processing scenario has a specific pattern: a user triggers an AI analysis, gets the result, then gets the same result again 90 seconds later with no explanation. If you've had users report duplicate outputs and assumed it was a UI bug or a double-click, it may have been this. The job ran, got killed, re-queued, and ran again from the beginning.

If you have separate Redis connections for different queues, each connection needs its own retry_after value matched to the highest supervisor timeout that uses it. A dedicated redis-ai connection with its own retry_after of 360 is cleaner than raising the value for every queue across the board.

Change 3: Add exponential backoff for rate limit failures

AI API providers rate-limit aggressively. OpenAI, Anthropic, and Gemini all have per-minute token limits. When a job hits a rate limit, it throws an exception and fails. Without backoff configuration, Horizon retries immediately. Under sustained load, a burst of AI jobs exhausting the rate limit causes every retry to also hit the rate limit, causing another retry, in a tight loop that burns through your API budget and fills the failed jobs list.

The fix is exponential backoff, which Horizon supports at both the supervisor level and the job class level.

At the supervisor level:

'supervisor-ai' => [
    'connection' => 'redis',
    'queue' => ['ai'],
    'balance' => 'auto',
    'processes' => 3,
    'timeout' => 300,
    'tries' => 3,
    'backoff' => [30, 60, 120], // wait 30s, then 60s, then 120s between retries
    'memory' => 512,
],

Or on the job class directly, which takes precedence over supervisor config:

class RunAiReportJob implements ShouldQueue
{
    public int $timeout = 270;
    public int $tries = 3;

    // Exponential backoff: 30s after first failure, 60s after second
    public array $backoff = [30, 60, 120];
}

The job class approach is more explicit and survives config changes without you needing to remember to update the supervisor. It's the pattern to prefer when different AI jobs have different retry requirements. A cheap text classification job can retry faster than an expensive multi-tool agent call.

One thing worth noting: tries counts total attempts, not retries. A job with $tries = 3 gets three chances total: the original execution plus two retries. Set it low enough that an actually broken job doesn't exhaust your API quota before hitting the failed jobs list. Three is usually the right number for AI jobs with rate limit risks.

Change 4: Move AI jobs to a dedicated queue and supervisor

Even with the timeout and retry_after fixed, AI jobs and fast jobs sharing the same supervisor still block each other. Here's why: if you have three workers in supervisor-1 and three 90-second AI jobs land simultaneously, all three workers are occupied for 90 seconds. Email jobs, notifications, and payment webhooks sit queued and waiting until one of those workers finishes.

The solution is a dedicated queue for AI work and a supervisor that only handles it, completely isolated from your default queue.

// In your job class
class RunAiReportJob implements ShouldQueue
{
    public string $queue = 'ai';

    public int $timeout = 270;
    public int $tries = 3;
    public array $backoff = [30, 60, 120];
}

Or when dispatching:

RunAiReportJob::dispatch($report)->onQueue('ai');

Then in config/horizon.php, run two supervisors with different constraints:

'environments' => [
    'production' => [
        // Fast jobs: tight timeout, many workers
        'supervisor-default' => [
            'connection' => 'redis',
            'queue' => ['default', 'high'],
            'balance' => 'auto',
            'processes' => 10,
            'timeout' => 60,
            'tries' => 3,
            'backoff' => 3,
            'memory' => 256,
        ],

        // AI jobs: long timeout, fewer workers, more memory
        'supervisor-ai' => [
            'connection' => 'redis',
            'queue' => ['ai'],
            'balance' => 'auto',
            'processes' => 3,
            'timeout' => 300,
            'tries' => 3,
            'backoff' => [30, 60, 120],
            'memory' => 512,
        ],
    ],
],

The result:

Three workers for AI is a starting point. The right number depends on your API rate limits and job volume. Three concurrent AI jobs consuming tokens simultaneously can hit per-minute limits quickly, so scaling the worker count upward requires monitoring your provider's rate limit headroom first.

You might also want to set balance to simple for the AI supervisor rather than auto. The auto strategy dynamically scales workers based on queue depth, but it has a side effect: Horizon considers workers "hanging" when scaling down and will force-kill them after the supervisor timeout if they're mid-execution. For long-running AI jobs, simple balance with a fixed process count is more predictable. You control the concurrency explicitly, and Horizon doesn't try to adjust it based on queue depth in a way that could interrupt active jobs.

For a deeper look at structuring queue topology across multiple job types, the Laravel queue route guide covers centralising queue assignments cleanly.

The complete production config

Here's everything together as a reference:

// config/queue.php: raise retry_after to cover the longest AI job
'redis' => [
    'driver' => 'redis',
    'connection' => 'default',
    'queue' => env('REDIS_QUEUE', 'default'),
    'retry_after' => 360, // supervisor timeout (300) + 60s buffer
    'block_for' => null,
],

// config/horizon.php: two supervisors, two concerns
'environments' => [
    'production' => [
        'supervisor-default' => [
            'connection' => 'redis',
            'queue' => ['default', 'high'],
            'balance' => 'auto',
            'processes' => 10,
            'timeout' => 60,
            'tries' => 3,
            'backoff' => 3,
            'memory' => 256,
        ],
        'supervisor-ai' => [
            'connection' => 'redis',
            'queue' => ['ai'],
            'balance' => 'auto',
            'processes' => 3,
            'timeout' => 300,
            'tries' => 3,
            'backoff' => [30, 60, 120],
            'memory' => 512,
        ],
    ],
],

// App\Jobs\RunAiReportJob.php: job-level timeouts and backoff
class RunAiReportJob implements ShouldQueue
{
    public string $queue = 'ai';
    public int $timeout = 270;  // slightly below supervisor timeout
    public int $tries = 3;
    public array $backoff = [30, 60, 120];

    public function handle(): void
    {
        // Your AI SDK call here
    }

    public function failed(Throwable $exception): void
    {
        // Log, notify, or clean up on final failure
    }
}

After deploying, run php artisan horizon:terminate to restart Horizon and pick up the new config. The queue:restart signal alone doesn't reload Horizon's supervisor configuration.

FAQ

Why does Horizon kill jobs at 60 seconds when I never set a timeout?

Horizon inherits the timeout from the queue worker defaults. If you don't explicitly set timeout in the supervisor config, it falls back to the worker default of 60 seconds. This is documented but easy to miss, because the installed config/horizon.php doesn't always include timeout in every supervisor block. Absence isn't zero, it's the default.

Can I just set a very high timeout everywhere instead of creating separate supervisors?

You can, but it's the wrong call. A 300-second timeout on your email supervisor means a stuck email job (due to a mail server timeout, for example) occupies a worker for five minutes instead of one. Separate supervisors let you apply constraints appropriate to each job type. The email jobs don't need to know about AI job timeouts, and vice versa.

Does the AI SDK dispatch jobs automatically, or do I need to wrap calls manually?

You wrap them manually. The Laravel AI SDK runs synchronously by default. Dispatching an agent call as a background job is an explicit architectural choice you make by wrapping the Agent::run() call in a ShouldQueue class. The SDK doesn't push to queues automatically.

What happens to an AI job that exceeds $timeout on the job class?

If $timeout is set on the job class and the supervisor timeout is higher, the job gets a TimeoutExceededException, which triggers the failed() method cleanly. This is the preferred failure mode: you get the cleanup hook, the exception is logged, and tries are decremented normally. A SIGKILL from the supervisor timeout skips all of that.

How do I verify the timeout and retry_after relationship is correct after deploying?

Run a test job that deliberately sleeps for a duration between your supervisor timeout and retry_after, then watch Horizon's dashboard. If the job appears twice in Recent Jobs, your retry_after is still too low. Also check the Redis key directly: redis-cli LRANGE queues:ai 0 -1 will show you if a job is sitting in both an executing state and the queue simultaneously.

One thing to remember

Most of the pain from adding AI SDK to an existing Laravel app isn't in the code. It's in configuration assumptions that were correct before and quietly broke afterward. None of these four changes are complex. They're just easy to not know about until something goes wrong in production.

The timeout and retry_after relationship is the most dangerous of the four. It's in the official docs, it's a known issue with a clear warning, and it still catches experienced developers because the two values live in different config files with no cross-reference in the UI. You'd have to know to check one when you change the other.

The queue isolation change has the biggest ongoing benefit. Once your AI jobs run in their own supervisor, you can tune that supervisor independently. You can scale the worker count up during peak AI usage without affecting the process count for your other queues. You can set different memory limits, different balancing strategies, and different alerting thresholds. Fast jobs and slow jobs just have different operational needs, and the config reflects that.

If you're running AI workloads on Horizon right now without dedicated supervisors, go check your retry_after value before anything else. If it's under 300, you may already be double-processing jobs and not seeing it in your logs.

Building something with the AI SDK and want a review of the queue architecture before it hits production? Get in touch.

6 Eloquent Patterns That Silently Break MySQL Index Usage (And How to Fix Each One)

Hafiz — Mon, 25 May 2026 05:21:18 +0000

You added the index. You confirmed it's there with SHOW INDEX FROM orders. The query is still timing out in production, against the same created_at column you've had indexed for months.

This happens more than it should. MySQL's B-tree index is sitting right next to your query, completely ignored, and Eloquent handed it a condition the optimizer can't act on. No error. No warning. No hint in the logs. Just a full table scan against 4 million rows while your dashboard waits.

The reason almost always traces to one concept: sargability.

A predicate is sargable (Search ARGument ABLE) when MySQL can use an index to resolve it directly. The moment a function wraps the indexed column, sargability breaks. MySQL has to compute that function for every single row, then filter the results. That means reading the entire table regardless of what indexes exist.

Six Eloquent patterns trigger this silently. You'll recognize at least two of them in your current codebase.

Before going through them, set up EXPLAIN as your verification tool. Wrap any suspicious query like this:

$query = Order::whereDate('created_at', today());
dd($query->toSql(), DB::select('EXPLAIN ' . $query->toSql(), $query->getBindings()));

In the EXPLAIN output, the fields that matter most are type and rows. A type: ALL result means a full table scan. A type: range or type: ref means an index is in use. The rows column tells you how many rows MySQL examined. On a table with 4 million rows, rows: 4000000 next to type: ALL is the confirmation you're looking for.

Two more fields worth checking: key shows which index MySQL actually used (it'll be NULL on a full scan), and Extra shows Using filesort or Using temporary when MySQL had to do extra work outside the index. Any of those three signals in a single EXPLAIN row means you have a query worth fixing.

Laravel Telescope is the easiest way to surface slow query candidates without configuring MySQL's slow query log. It logs every query with execution time. Sort by duration to find the biggest problems first.

If you want to understand how to build the right indexes in the first place, the Laravel database indexing guide covers composite indexes, covering indexes, and when index cardinality matters.

Pattern 1: whereDate() and its siblings

This is the most documented one, and still the least-fixed. The whereDate() method generates DATE(created_at) = '2026-05-22'. That DATE() wraps your column, sargability is gone, and the index on created_at does nothing.

// Bypasses index on created_at
Order::whereDate('created_at', today())->get();

// What MySQL actually runs:
// WHERE DATE(created_at) = '2026-05-22'
// EXPLAIN type: ALL, rows: 4,893,201

The same is true for whereMonth(), whereYear(), whereDay(), and whereTime(). Every one of them wraps the column in a MySQL function before comparing.

A common place this compounds: reporting queries that filter by year and month separately.

// Two function wraps, both non-sargable
Order::whereYear('created_at', 2026)
     ->whereMonth('created_at', 5)
     ->get();

// MySQL runs: WHERE YEAR(created_at) = 2026 AND MONTH(created_at) = 5
// EXPLAIN type: ALL, rows: 4,893,201

Both conditions examine every row. The fix is still a range:

// Uses index on created_at
Order::whereBetween('created_at', [
    today()->startOfDay(),
    today()->endOfDay(),
])->get();

// What MySQL actually runs:
// WHERE created_at >= '2026-05-22 00:00:00' AND created_at <= '2026-05-22 23:59:59'
// EXPLAIN type: range, rows: 183

If you're ranging across multiple days, prefer tomorrow()->startOfDay() as the exclusive upper bound instead of endOfDay(). The endOfDay() helper returns 23:59:59, which can miss rows with microsecond timestamps right at midnight.

One note about PostgreSQL: it supports functional indexes, so you can create an index directly on DATE(created_at) and whereDate() will use it. MySQL has no real equivalent. For MySQL apps, the range approach is the correct fix regardless of database.

Pattern 2: LIKE with a leading wildcard

Every developer knows LIKE '%value%' is slow. What's less obvious is exactly why.

MySQL's B-tree index stores values in lexicographical order, like a phone book. A leading % tells MySQL "I don't know how this string starts," so the index is useless. MySQL has to read every row and apply the pattern match manually, front to back.

A trailing wildcard without a leading one is fine: LIKE 'value%' can use a B-tree index because the starting characters are known. The problem is specifically a % at the start.

// Can't use index on email
User::where('email', 'LIKE', '%@company.com')->get();

// EXPLAIN type: ALL, rows: 2,100,000

You have three practical options depending on what you're actually doing:

Option A: Add a separate indexed column for the thing you're filtering on. If you're always filtering by email domain, store it explicitly:

// Migration: $table->string('email_domain')->index();
User::where('email_domain', 'company.com')->get();
// EXPLAIN type: ref, rows: 14

Option B: Use a FULLTEXT index for text search within a column:

// Requires: $table->fullText('bio');
User::whereFullText('bio', 'laravel developer')->get();

FULLTEXT search is handled by MySQL's inverted index, which is built specifically for text matching. It doesn't do exact substring matches but it handles word-based search well.

Option C: Move to a search engine like Meilisearch or Algolia for any real search feature. Laravel Scout wraps the integration cleanly and the performance difference is not comparable to anything MySQL can do natively.

Pattern 3: Functions in orderByRaw()

This one catches developers because it doesn't cause a slow WHERE filter. It causes a slow sort. When you apply a function to a column in ORDER BY, MySQL falls back to a filesort on the full result set rather than using the index for sorting.

// Triggers filesort
User::orderByRaw('LOWER(name) ASC')->get();

// EXPLAIN Extra: Using filesort

A filesort uses memory for smaller result sets and disk for larger ones. On a table with millions of rows, it's consistently slow.

For case-insensitive sorting, the cleanest fix is using the right collation on the column. Most Laravel apps default to utf8mb4_unicode_ci, which is already case-insensitive for comparisons and sorting. That means a plain orderBy('name') is already case-insensitive if your column uses that collation. No LOWER() needed at all.

If you're on MySQL 8.0.13+ and actually need a functional index for a custom sort expression, you can create one:

-- Functional index on MySQL 8.0.13+
ALTER TABLE users ADD INDEX idx_name_lower ((LOWER(name)));

Then your orderByRaw('LOWER(name)') query will use it. The extra parentheses around LOWER(name) in the DDL are required syntax for functional indexes in MySQL 8.

Pattern 4: Type mismatch on string columns

This is the sneakiest one, and Laravel's query builder documentation explicitly warns about it.

MySQL and MariaDB automatically typecast values during string-to-integer comparisons. Non-numeric strings convert to 0. So when you write:

// status is a varchar column: 'pending', 'processing', 'failed'
Order::where('status', 0)->get();

MySQL casts every status value to an integer before comparing. 'pending' becomes 0. 'processing' becomes 0. 'failed' becomes 0. Every non-numeric string matches, the result is wrong, and because the implicit conversion breaks sargability, you get a full table scan on top of it.

You get bad data silently along with bad performance. That's the double hit.

// Correct: compare string to string
Order::where('status', 'pending')->get();

If you're accepting filter values from a request, cast before querying:

Order::where('status', (string) $request->input('status'))->get();

This also matters inside local scopes. A scope that accepts a $value parameter and passes it directly to where() without type-checking produces this problem invisibly every time it's called with an integer.

// Dangerous scope: no type check
public function scopeWithStatus(Builder $query, $status): Builder
{
    return $query->where('status', $status);
}

// Caller passes an int from a form request: implicit cast happens silently
Order::withStatus($request->input('status_id'))->get();

Add an explicit cast inside the scope so the problem can't sneak through regardless of what the caller passes:

public function scopeWithStatus(Builder $query, mixed $status): Builder
{
    return $query->where('status', (string) $status);
}

Pattern 5: whereRaw() with function wraps

Developers who've heard about whereDate() sometimes switch to whereRaw() thinking they're writing safer SQL. They're not. You can reproduce the exact same non-sargable query yourself.

// Still bypasses index on created_at
Order::whereRaw('YEAR(created_at) = ?', [2026])->get();

// Still bypasses index on shipped_at
Order::whereRaw('DATE(shipped_at) >= ?', ['2026-01-01'])->get();

// Still bypasses index on id
User::whereRaw('CAST(id AS CHAR) = ?', [$stringId])->get();

Any function that wraps an indexed column in a WHERE clause breaks sargability, whether Eloquent generates it or you write it manually. The optimizer sees the function and can't use the B-tree index. That's the rule.

The year-based filtering fix uses a Carbon range:

use Carbon\Carbon;

// Full year range: sargable
Order::whereBetween('created_at', [
    Carbon::create(2026)->startOfYear(),
    Carbon::create(2026)->endOfYear(),
])->get();

For the CAST(id AS CHAR) case, the right fix is not to cast the column. Fix the type upstream. Cast the incoming string to an integer before passing it to the query. The database column should never need to change types mid-query just because the application passed the wrong type.

Pattern 6: orWhere() on a composite index without grouping

This one is less about function wrapping and more about how MySQL resolves OR conditions against composite indexes.

Say you have a composite index on (user_id, status) and you write:

Order::where('user_id', $userId)
     ->orWhere('status', 'urgent')
     ->get();

MySQL generates WHERE user_id = X OR status = 'urgent'. The first condition can use the composite index because user_id is the leftmost prefix. But the second condition needs to find all rows where status = 'urgent' regardless of user_id, which points to a completely different part of the index. MySQL often decides a full table scan is cheaper than doing two separate index lookups and merging the results.

// On a table with 2M rows
// EXPLAIN type: ALL, rows: 1,987,432

MySQL's Index Merge optimization can sometimes handle OR conditions, but it's unreliable. Merging two result sets adds CPU overhead, and the optimizer frequently skips it.

Group your OR conditions explicitly using closures so the query intent is clear:

Order::where(function ($query) use ($userId) {
    $query->where('user_id', $userId)
          ->where('status', '!=', 'closed');
})->orWhere(function ($query) {
    $query->where('priority', 'high')
          ->whereNotNull('escalated_at');
})->get();

For cases where both branches are hitting large portions of the table, two separate queries with a union often outperform a single OR query. Each query can use its own index cleanly, and there's no merge overhead:

$myOrders = Order::where('user_id', $userId)->select('id', 'status', 'created_at');
$urgentOrders = Order::where('status', 'urgent')->select('id', 'status', 'created_at');

$results = $myOrders->union($urgentOrders)->orderBy('created_at', 'desc')->get();

The union approach works best when the two sets don't overlap much. If they do overlap heavily, add unionAll() to skip the deduplication cost, since UNION by default removes duplicate rows through a sort pass.

One thing to watch: union queries return results in an undefined order unless you explicitly call orderBy() on the outer query. Add it when the result order matters to the caller.

Quick reference

Pattern	What MySQL runs	Index?	Fix
`whereDate('col', $date)`	`DATE(col) = ?`	No	Half-open range with `whereBetween()`
`LIKE '%value'` or `'%value%'`	Full wildcard scan	No	Separate column, FULLTEXT, or Scout
`orderByRaw('LOWER(col)')`	Filesort	No	Column collation or functional index
`where('varchar_col', 0)`	Implicit cast	No	Compare with correct string type
`whereRaw('YEAR(col) = ?')`	Same as whereDate	No	Carbon range with `whereBetween()`
`->where()->orWhere()` on composite	OR breaks range scan	Partial	Grouped closures or union queries

FAQ

How do I find these patterns in an existing app?

Enable MySQL's slow query log and set long_query_time to something low like 0.1 seconds. Then run EXPLAIN on anything that shows up. Look for type: ALL in the output. Laravel Telescope surfaces the generated SQL for every query, which makes it easy to copy into a MySQL client and run EXPLAIN manually. The Laravel query optimization guide walks through the debugging workflow in more detail.

Does this apply to local scopes?

Yes, completely. A local scope that calls whereDate() or uses a leading wildcard LIKE generates the exact same SQL. The ORM layer doesn't change what MySQL executes. Always check the generated SQL with ->toSql() before assuming a scope is index-friendly.

Is whereDate() ever acceptable?

On small tables, under roughly 50,000 rows, the performance difference is imperceptible. The problems start when the table crosses a few hundred thousand rows. The range fix costs nothing extra, so there's no good reason not to use it regardless of table size.

What about PostgreSQL?

PostgreSQL supports functional indexes, so you can create an index on DATE(created_at) directly and whereDate() will use it. MySQL has no equivalent without generated columns, which add schema overhead. For MySQL apps, the range approach is always the cleaner fix.

Why doesn't Eloquent warn you about these patterns?

Because Eloquent doesn't know your schema. It doesn't know which columns are indexed, what types they are, or how many rows your table has. The ORM's job is to generate valid SQL. Understanding query plans is yours, and EXPLAIN is the tool for it.

Closing thoughts

Most of these patterns look completely reasonable when you write them. That's what makes them dangerous. The fix isn't complicated in any of the six cases. It's usually a two-line change, but you have to know to look for it.

The underlying rule is always the same: if a function wraps your indexed column in the WHERE or ORDER BY clause, MySQL can't use the index. Once you've internalized that, you'll spot non-sargable queries anywhere, not just in the six patterns above. It changes how you read Eloquent code, how you review PRs, and how you respond when someone reports a slow page. Instead of reaching for a new server or a caching layer first, you run EXPLAIN.

A lot of Laravel performance problems that get blamed on infrastructure are actually query problems. The query optimizer doesn't care that you're using Eloquent. It doesn't know you expected the index to be used. It just follows the rules of the SQL it receives. Writing sargable queries is how you work with the optimizer rather than around it.

Building something and want a second set of eyes on the query layer before it becomes a problem at scale? Get in touch.

Code PHP From Your Phone: The VPS + Tmux + Termius Setup That Actually Works

Hafiz — Sat, 23 May 2026 11:57:16 +0000

I've been running this setup on a Hetzner server for a while. This post documents exactly how I set it up, including the mistakes I made along the way that most tutorials skip over. I went through the full setup live while writing this, so the gotchas are real.

If you haven't secured the VPS itself yet, start with how I hardened mine with SSH, Cloudflare, and Tailscale first. That post covers locking down SSH, hiding your server IP, and routing access through Tailscale. This post covers what comes after: the PHP stack, Tmux sessions, Claude Code, and connecting from your phone.

Why a remote dev environment

Local dev has one fatal flaw. The moment your laptop closes, everything dies. Queue workers, running scripts, anything you left going. You come back and reconstruct context from scratch.

A VPS with Tmux flips this. Sessions persist indefinitely. You detach when you're done, reattach from any device and your work is exactly where you left it. The server never sleeps.

There's a practical benefit for anyone traveling or away from their desk. Your full dev environment runs on the server. Your local device is just a terminal window. An iPad, a phone, a borrowed laptop: they all get identical access to the same running environment.

For Laravel specifically: queue workers run continuously on the VPS. No need to restart them every session.

What this post covers

PHP 8.x + Composer already installed on the VPS? Skip Step 1.
Tmux already installed? Skip Step 2.
Just want the phone connection? Jump to Step 3.

Step 1: Check and install the PHP stack

First, see what's already on the server:

php -v 2>/dev/null || echo 'PHP: not installed'
composer -V 2>/dev/null || echo 'Composer: not installed'
tmux -V 2>/dev/null || echo 'Tmux: not installed'
which claude 2>/dev/null || echo 'Claude Code: not installed'

If PHP is missing, install PHP 8.4 with the extensions a Laravel app needs:

sudo apt update && sudo apt upgrade -y
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install -y php8.4 php8.4-cli php8.4-fpm php8.4-mbstring \
  php8.4-xml php8.4-curl php8.4-zip php8.4-mysql \
  php8.4-redis php8.4-bcmath php8.4-intl

Install Composer if it's missing:

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
chmod +x /usr/local/bin/composer

Install the Laravel installer globally:

composer global require laravel/installer
echo 'export PATH="$HOME/.config/composer/vendor/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Set up Git with your details:

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Step 2: Tmux for sessions that survive disconnects

Tmux is what makes this whole setup usable. Without it, every SSH disconnect kills your running processes. With it, sessions sit on the server indefinitely.

Install if needed:

sudo apt install tmux -y

Add a session helper function to your .bashrc. This is the tm command you'll use every time you connect:

cat >> ~/.bashrc << 'EOF'

# Tmux session helper: creates or reattaches to a named session
tm() {
  local name="${1:-$(basename "$PWD")}"
  name="${name//\./-}"
  name="${name//\//-}"
  if [ -n "$TMUX" ]; then
    tmux has-session -t "$name" 2>/dev/null || tmux new-session -d -s "$name" -c "$PWD"
    tmux switch-client -t "$name"
  else
    tmux attach -t "$name" 2>/dev/null || tmux new -s "$name" -c "$PWD"
  fi
}
EOF
source ~/.bashrc

Start a session:

tm dev

You should see the Tmux status bar appear at the bottom of the terminal, showing the session name and timestamp. That bar is the confirmation that you're inside a persistent session.

For a Laravel project, I keep four windows in a single session:

The Tmux commands you'll use daily:

Ctrl+B, D         # detach: leaves session running on server
Ctrl+B, C         # new window in current session
Ctrl+B, [number]  # switch to window 0, 1, 2...
Ctrl+B, ,         # rename current window
tmux ls           # list all sessions
tmux attach -t name  # reattach to a named session

Critical gotcha: Always detach with Ctrl+B, D. Never close the terminal window or press Ctrl+C on the shell. That kills the session. Detach keeps it running on the server. This distinction is the entire point of Tmux.

For more on Laravel queue workers and why running them continuously matters, the queue jobs guide covers the production setup.

Step 3: Claude Code on the VPS

Install with the native installer (no Node.js required, and this is the recommended method as of 2026):

curl -fsSL https://claude.ai/install.sh | bash

Gotcha: The installer will warn you that ~/.local/bin is not in your PATH. It won't fix this for you. Run the fix manually:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Verify it worked:

claude --version
# 2.1.150 (Claude Code)

On first run, claude opens a browser authentication link. You need a Claude Pro ($20/month), Max, Team, Enterprise, or Console API account. The free tier doesn't include Claude Code access.

Start Claude Code in a dedicated Tmux window:

Ctrl+B, C         # new window
Ctrl+B, ,         # rename it "claude"
cd ~/my-laravel-app && claude

Claude Code runs inside your project directory. It can read files, run artisan commands, write code, and manage git from the terminal. When you detach and reattach from any device, it's in the same state.

Step 4: Termius for phone access

Termius is the best SSH client for iOS and Android. It has a custom keyboard row with Ctrl, Esc, Tab, and pipe. The keys you actually need in a terminal. Plus a keep-alive setting that prevents the connection dropping when you switch apps.

Download from the App Store or Google Play.

Gotcha: create your account before adding anything. The free tier includes sync. If you add hosts and keys without logging in first, your local data may not transfer to your account when you sign up later. Open Termius, tap Profile, create the account, then proceed.

Add your SSH key:

Tap Vaults → Keychain → +
Choose Paste Key
On your Mac, run cat ~/.ssh/id_rsa (or id_ed25519) and copy the entire output including the header and footer lines
Paste into the Private Key field, give it a label like hetzner-key, save

Add the host:

Tap Vaults → Hosts → +
Label: Hetzner Dev
IP: your server's IPv4 address (get it with curl -4 ifconfig.me on the server)
Username: root
Tap Key, Certificate, FIDO2 → select hetzner-key
Save, then tap the host to connect

Once connected, reattach to your session:

tmux attach -t dev

The status bar reappears. Your queue worker, Claude Code session, and anything else you left running are all exactly where you left them.

Add a Startup Snippet to auto-attach on every connection:

In Edit Host, tap Startup Snippet and add:

tmux attach -t dev 2>/dev/null || tmux new -s dev

Now every time you open Termius and tap the host, you land directly in your Tmux session. No typing required. On a phone keyboard that matters.

Bonus: the Termius AI Agent feature

When adding a host, Termius shows an "AI Agent" section suggesting setup for Claude Code, Gemini, and OpenCode. This is a Termius Pro feature that integrates AI assistants directly into the mobile terminal. If you're on Termius Pro, it connects to the Claude Code session running in your Tmux window. On the free tier, you don't need it; Claude Code works fine via regular SSH.

Proving it works

The test: create a session from your phone, start a long-running command, detach, reconnect, see it still running.

# From your phone, inside Tmux
echo "Connected from phone at $(date)" && sleep 9999

Detach with Ctrl+B, D. Run tmux ls and the session shows as running. Reattach with tmux attach -t dev and your sleep is still going. Open the same session from your Mac and you'll see the exact same state: the same session name, the same running command.

Viewing the app from your phone browser

If you want to actually preview the Laravel app in a browser from your phone, php artisan serve alone won't work. It binds to 127.0.0.1:8000 on the VPS. Your phone's browser can't reach that address.

The clean solution: configure Caddy to serve the app on the server's Tailscale IP. Accessible from your phone's browser as long as Tailscale is running on both devices, invisible to the public internet.

# /etc/caddy/Caddyfile
http://100.x.x.x {
    root * /var/www/my-laravel-app/public
    php_fastcgi unix//run/php/php8.4-fpm.sock
    file_server
}

For a coding and deployment workflow without browser preview, you don't need this. Claude Code on the VPS handles edits without a visual browser.

FAQ

Does this survive a VPS reboot?

Tmux sessions don't survive reboots. If the server restarts (for security updates, for example), your sessions are gone. Add a Supervisor config to restart queue workers and other persistent processes automatically on boot. Claude Code you restart manually when you reconnect.

What if I need to SSH from a machine without my key?

Use your VPS provider's browser console. Hetzner calls it the Console button in the server dashboard. It gives you terminal access without SSH. Bookmark it before you need it.

My phone keyboard can't send Ctrl+B properly. What do I do?

Use the Termius keyboard row above the standard keyboard. Tap ctrl, then tap b, then release. The modifier keys in Termius are designed for this. If you see ^B^B^B appearing as text, you're pressing ctrl and b simultaneously on the standard keyboard instead of using the Termius row.

Is a Hetzner VPS specifically required?

Any Ubuntu VPS works. DigitalOcean, Vultr, Linode: same commands, same setup. Hetzner is the one I use. The CX23 runs at €4/month with solid specs.

Do I need Tailscale for this to work?

Not for the basic setup. If port 22 is open on your server, Termius connects via the public IP. Tailscale is the right next step if you want to close port 22 and keep SSH off the public internet, which the VPS hardening guide covers.

The actual workflow

Once everything is running, the daily flow from your phone looks like this: open Termius, tap the host, land directly inside your Tmux session via the Startup Snippet. Queue worker is running. Claude Code is open in window 3. Your last git commit message is visible in window 0. Nothing to reconstruct.

The whole setup took about an hour to get right, including the debugging. The Hetzner server costs less than a coffee per month. And the next time your laptop battery dies mid-flight, your dev environment is fine.

If you build something with this setup and want to talk through the architecture, get in touch.

What's Coming to Laravel Cloud: $5/month Plan, Spend Caps, and Instant Scale-to-Zero

Hafiz — Wed, 20 May 2026 05:41:15 +0000

The two things that kept most Laravel developers off Laravel Cloud were cost and the fear of a surprise bill. The Laravel team just announced both are being fixed, along with three other significant changes coming over the next few weeks.

Here's what was announced and what it actually means.

The Five Announcements

The announcement laid them out clearly:

1. A new $5/month plan. Previously, your options were Starter (free tier, pay-as-you-go, limited features) or Growth ($20/month). The new $5/month tier sits between them. The stated goal: "We want Cloud to be accessible to every Laravel developer."

2. Spend caps. Set a spending limit on your account. When you hit it, Cloud will either alert you or shut off compute entirely. No more anxiety about waking up to an unexpected $300 bill.

3. True scale-to-zero with 10x faster wake-up. Hibernation has existed for a while, but wake-up previously took 5-20 seconds. App, database, and cache wake-up is now measured in milliseconds. Users won't notice it.

4. Bot protection rules. Keeps hibernated apps dormant longer by filtering bot traffic before it wakes your environment. This directly reduces compute spend. Bots won't trigger unnecessary wake-ups that eat into your budget.

5. Managed queues. Queue clusters are being rebuilt into a new "managed queues" product. Set a maximum worker count and Cloud handles everything else. It scales on queue depth (not just CPU) and scales to zero when idle. No more guessing at worker sizing.

These changes aren't live yet. The announcement said "coming over the next few weeks," so treat this as a planning-ahead post rather than a same-day implementation guide.

The Spend Cap Is the Real News

The $5/month price point gets the headline, but spend caps are what actually unlocks Cloud for cautious teams.

Usage-based pricing always carries anxiety. Even with hibernation enabled, one unexpected traffic spike, a crawling bot hammering your endpoints, or a runaway job queue could turn a $10 month into an $80 one. That unpredictability kept teams on fixed-cost Forge servers where the bill was predictable even if the compute was oversized.

Spend caps change the risk profile completely. You can enable hibernation, deploy a small instance, and know that the maximum you'll pay in a worst-case month is whatever cap you set. That's a fundamentally different product than "usage-based with no ceiling."

Combine spend caps with the new bot protection rules and the hibernation economics get significantly better. Bots are the silent killers of scale-to-zero apps. They wake your environment constantly without generating real revenue. Filtering them before they trigger a wake-up means your app actually stays dormant during off-peak hours instead of yo-yoing on and off.

What Millisecond Wake-Up Changes

The previous 5-20 second cold start was the biggest practical barrier to using hibernation on anything user-facing. You could use it for staging environments and dev instances without issue, but putting a hibernating app in front of real users meant the first request after idle time got a slow response. Users noticed. Support tickets followed.

Millisecond wake-up removes that constraint. If the wake-up is imperceptible, hibernation becomes a pure cost optimization with no UX downside. You can run a production app with a low-cost Flex instance, hibernate between traffic windows, and pay only for active time, without needing a "warm-up" strategy or a cron job to keep things alive.

One question worth watching: the tweet mentions milliseconds for app, database, and cache wake-up. The database wake-up is the historically slow part. If serverless Postgres wakes in milliseconds consistently, that's a genuine infrastructure achievement. The community will stress-test this quickly once it ships.

Managed Queues as a Quiet Win

The managed queues announcement is being slightly overshadowed by the pricing news, but it's significant for teams running serious background processing.

Queue workers have always required manual tuning. How many workers does this job type need? What happens if the queue backs up? How do you prevent workers from sitting idle at 3am burning compute? The standard answer was either Horizon with careful configuration or accepting occasional over-provisioning, patterns covered in the Laravel queue jobs guide.

Managed queues take that decision away. Cloud monitors queue depth and adjusts worker count automatically. When the queue drains, workers scale to zero. When it fills, they spin up. You set a maximum and stop thinking about it.

For applications with variable job loads (processing payments, sending email campaigns, handling webhooks), this is cleaner than anything available on Forge or Vapor today. It ties directly into the monitoring and observability improvements that make Cloud worth the higher base cost.

The New Math: Cloud vs Forge vs Vapor

With the new plan, the comparison looks different for small projects.

Indie developer with multiple side projects:

Cloud (new $5 tier + usage with hibernation): $5 + ~$2-5/month per app
Forge: $17/month base (you can add cheap VPS servers, but Forge itself is $17)
VPS direct: $5-10/month per server (you manage everything)

One developer in the announcement thread shared they're running seven apps with decent traffic for $6/month total using scale-to-zero. That number will improve further with bot protection and millisecond cold starts. For anyone currently running multiple low-traffic side projects on separate servers, the Cloud math starts looking favorable.

Pre-scale startup on Growth ($20/month):

Cloud Growth: $20/month + ~$16-25 usage = ~$36-45/month
Forge: $17/month + $20-40/month DigitalOcean/Hetzner VPS = ~$37-57/month

At this tier, the total cost is similar, but Cloud includes autoscaling, managed databases, preview environments, and zero DevOps overhead. Forge requires you to configure servers, manage Nginx, handle SSL renewal, and tune your own scaling. The value comparison has always favoured Cloud for teams without a dedicated DevOps person. The new pricing makes it viable to reach that tier sooner.

Vapor ($39/month):
Vapor runs on AWS Lambda, which gives you true serverless with different performance characteristics. It's still the right choice for teams deeply invested in the AWS ecosystem. But for most Laravel developers who just want their app deployed and scaled without thinking about infrastructure, Cloud's model is more Laravel-native and increasingly competitive on price. The CI/CD and deployment guide from last week covers how to automate your Cloud deployments via GitHub Actions.

Who Should Be Paying Attention

Indie developers and side project builders. The $5/month plan plus spend caps makes Cloud viable for projects that previously couldn't justify $20/month. Multiple side projects on a single Cloud account with hibernation enabled could cost less than one Forge server.

Small agencies running client sites. Preview environments per pull request plus managed databases at $5-20/month per project is a clearly compelling agency workflow. The managed queues addition makes it viable for client projects with background job requirements.

Teams on Forge who don't enjoy server management. If you're paying someone to manage Forge servers (patching, monitoring, scaling), Cloud is worth a fresh look. The total cost might be similar, but the management overhead disappears. For teams building SaaS products on Laravel, the complete SaaS guide covers the broader architecture decisions where Cloud fits naturally.

Anyone who previously tried Cloud and left because of cost or cold start anxiety. Both objections are being addressed directly. Worth revisiting once the features ship.

Who Should Stay Where They Are

Developers who want full server control. Forge gives you root access and complete flexibility. Cloud abstracts that away by design. If you need custom Nginx configs, non-standard PHP extensions, or specific OS-level tooling, Forge is still the better choice.

Teams on Vapor with existing AWS infrastructure. The Lambda model suits certain workloads well and migrating away from a working setup for incremental cost savings rarely makes sense.

High-traffic, always-on applications. Hibernation economics only work when your app has genuine idle periods. If you're running a busy production app that never sleeps, the cost advantage disappears and a dedicated server (Forge or otherwise) may still be cheaper.

The Bigger Picture

The Scotty vs Envoy post from April made the case that the Laravel deployment tooling ecosystem is maturing fast. This announcement reinforces that. A $5/month managed hosting tier with spend caps and millisecond cold starts is a product that didn't exist anywhere in the PHP ecosystem six months ago.

The spend caps and bot protection show the team is listening to actual adoption blockers rather than just adding features. Those two additions together fix the core reason cautious developers stayed away.

The managed queues rebuild is the kind of unsexy infrastructure improvement that saves teams real operational hours once you're running it in production.

Once these ship, the "why not just use Forge" argument gets harder to make for most new Laravel projects.

FAQ

When are these features available?

The announcement said "coming over the next few weeks." No specific release date was given. Follow the official Laravel Cloud blog for the rollout timeline.

Will the $5/month plan include custom domains?

Not confirmed in the announcement. The current Starter (free) plan includes custom domains, so it's likely the $5 tier does too. Check the official pricing page once it's updated.

Does the spend cap pause the app or just alert you?

The announcement confirmed it will either alert you or shut off compute. The configuration details (which trigger, per-environment vs per-account) will be in the documentation once it ships.

Should I migrate existing apps before these features land?

Wait until they're live and documented before making migration decisions. The announcements are forward-looking; current Cloud behavior still applies today.

How does bot protection work with legitimate crawlers?

Specific configuration details weren't shared in the announcement. Presumably you'll be able to allowlist crawlers like Googlebot. More detail will come in the docs.

Worth Watching

These announcements move Laravel Cloud from "interesting but expensive" to "worth serious consideration for almost any new Laravel project." The spend caps alone change the risk calculation. The millisecond wake-up makes hibernation viable for production. The $5 plan removes the cost objection for small projects.

Whether this changes your deployment setup depends on where you are now. But if you wrote off Cloud six months ago, the next few weeks are worth another look.

If you're evaluating Laravel Cloud for a specific project and want to think through the numbers, get in touch.

Using Ollama with the Laravel AI SDK: Run Local LLMs for Free

Hafiz — Mon, 18 May 2026 05:11:59 +0000

API costs add up fast during AI development. You prompt an agent 50 times debugging a tool, that's 50 API calls. You run your test suite, that's another batch. Multiply that across a team and you're spending real money before shipping anything.

Ollama solves this cleanly. It runs open-source models locally on your machine (Llama 3, Qwen, Mistral, and dozens more) and the Laravel AI SDK treats it as a first-party provider, exactly like OpenAI or Anthropic. Switch between them with a single environment variable. No code changes, no new packages, no API keys.

This post covers the full setup: installing Ollama, configuring it in the Laravel AI SDK, building agents that run locally, and the dev/production workflow that lets you use Ollama locally while shipping with a cloud provider.

What Ollama Does

Ollama is a lightweight tool that downloads and serves open-source language models locally. Once it's running, it exposes an HTTP API on localhost:11434 that the Laravel AI SDK connects to directly.

There's no internet connection required after the initial model download. No rate limits. No costs per token. If you've built your app with the Laravel AI SDK smart assistant tutorial, your existing agents work with Ollama with a one-line change.

The tradeoff is hardware. Larger models need more RAM and a capable GPU to run at acceptable speeds. But for development, smaller models like Llama 3.2:3B run well on any modern developer machine.

Installing Ollama

macOS:

brew install ollama

Or download the macOS app from ollama.com which installs as a menu bar app and starts automatically.

Linux:

curl -fsSL https://ollama.com/install.sh | sh

Windows:
Download the installer from ollama.com. Ollama runs as a background service after installation.

Once installed, verify it's running:

curl http://localhost:11434
# Should return: Ollama is running

Pulling Models

Download a model with ollama pull:

# General purpose, runs on any machine with 4GB+ RAM
ollama pull llama3.2

# Smaller version, 2GB, good for constrained machines
ollama pull llama3.2:1b

# Strong at code-related tasks, good for Laravel AI agents
ollama pull qwen2.5-coder:7b

# Mistral, fast and capable general model
ollama pull mistral

You can list all downloaded models:

ollama list

And test a model from the terminal before wiring it into Laravel:

ollama run llama3.2 "Explain Laravel service containers in one sentence"

For the artisan commands used in this guide, having at least one model pulled before starting saves debugging time.

Configuring the Laravel AI SDK

The SDK ships with Ollama support out of the box. The only .env addition is:

OLLAMA_API_KEY=

Leave the value blank. Ollama doesn't require authentication for local use, but the SDK expects the variable to exist. Add it to your .env and .env.example.

If Ollama is running on the default port, that's all you need. If you've changed the port or are running Ollama on a remote machine, configure the URL in config/ai.php:

'providers' => [
    // ... other providers

    'ollama' => [
        'driver' => 'ollama',
        'key'    => env('OLLAMA_API_KEY', ''),
        'url'    => env('OLLAMA_URL', 'http://localhost:11434/api'),
    ],
],

And in .env:

OLLAMA_URL=http://localhost:11434/api

The default URL is http://localhost:11434/api so for standard setups you don't need to add this. It works without it.

Using Ollama in Your Agents

Two ways to route an agent to Ollama: set it as the default provider for a specific agent class, or override it per-prompt at runtime.

Per-Agent with PHP Attributes

Add #[Provider] and #[Model] attributes to your agent class:

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

#[Provider(Lab::Ollama)]
#[Model('llama3.2')]
class SupportAgent implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a helpful support agent. Answer questions about our product concisely.';
    }
}

Now every time you prompt this agent, it uses Ollama locally:

$response = SupportAgent::make()->prompt('How do I reset my password?');

return (string) $response;

This is the cleanest pattern for development. You write your agent once with Ollama attributes, build and test locally with no API costs, then change the attributes (or override them via .env) when deploying to production.

Overriding Per-Prompt

For one-off local testing without modifying the agent class:

use Laravel\Ai\Enums\Lab;

$response = SupportAgent::make()
    ->prompt('How do I reset my password?', provider: Lab::Ollama, model: 'llama3.2');

This is useful when you want to quickly compare responses between Ollama and a cloud provider without changing the agent configuration.

The Dev/Production Workflow

The cleanest approach is to set a default provider at the application level in config/ai.php, driven by environment variables:

'default' => [
    'text' => [
        'provider' => env('AI_PROVIDER', 'openai'),
        'model'    => env('AI_MODEL', 'gpt-4o'),
    ],
],

Then in your local .env:

AI_PROVIDER=ollama
AI_MODEL=llama3.2

And in production .env (or your Forge/Vapor environment):

AI_PROVIDER=anthropic
AI_MODEL=claude-sonnet-4-5

Zero code changes between environments. Your agents, tools, and structured output stay identical. Only the provider changes. This works well for any agent that doesn't use PHP attribute overrides; those take precedence over the default config.

For agents with explicit #[Provider] attributes, you'd need to either remove the attributes or use a different approach for environment-based switching. The attribute approach is better for agents that should always use a specific provider (a code review agent that truly needs a smart model in all environments). The default config approach is better for general-purpose agents where Ollama in dev and a cloud model in prod makes sense.

Which Models to Use

Not all models are equal, and the right choice depends on what your agent is doing. Here's a practical guide based on common Laravel AI SDK use cases.

Llama 3.2 (3B or 8B) is the safe default for most use cases. The 3B version runs comfortably on any developer machine with 4GB RAM. The 8B version is noticeably better at following complex instructions but needs 8GB. Good for support agents, document summarisation, and general Q&A. Start here if you're not sure.

Qwen 2.5 Coder (7B) is the right choice for agents that work with code. It outperforms Llama on code generation and review tasks despite similar size. If you're building an agent that analyzes PHP files, generates migrations, or reviews code quality, use this one instead.

Mistral (7B) is fast and reliable for instruction-following tasks. If you need quick responses and the task isn't code-heavy, Mistral is worth trying. It tends to be faster than Llama 3.2 at the same quality level.

Avoid very large models (30B+) for development. They're slow on typical developer machines and the speed penalty makes iteration painful. The quality gap between 7B and 30B matters less in development where you're primarily testing tool calls and output format, not production response quality. Save the big models for your production cloud provider.

A practical setup for a Laravel SaaS would be: use llama3.2:8b for general agents and qwen2.5-coder:7b for any agent touching code. Both run on a 16GB machine without issues. If you're on a 8GB machine, use llama3.2:3b for everything and accept slightly weaker instruction following in exchange for speed.

If you've already built a multi-agent system with the SDK, you can route different sub-agents to different Ollama models the same way you'd assign different cloud models, and the AI SDK overview covers the broader SDK capabilities worth knowing before diving into local model optimization.

Embeddings with Ollama

Ollama also works for local embeddings, which means you can do RAG development with zero API costs:

use Laravel\Ai\Facades\Ai;
use Laravel\Ai\Enums\Lab;

$embedding = Ai::embed(
    'How do I cancel my subscription?',
    provider: Lab::Ollama,
    model: 'nomic-embed-text'
);

Pull the embedding model first:

ollama pull nomic-embed-text

nomic-embed-text is a solid local embedding model that produces 768-dimension vectors. For production RAG you'd swap to OpenAI's text-embedding-3-small or a similar cloud model, but for building and testing your vector search logic, Ollama keeps costs at zero.

What Ollama Doesn't Support

The Laravel AI SDK's Ollama integration covers text generation and embeddings. It does not support image generation, text-to-speech, speech-to-text, or file uploads. If your agents use those capabilities, you'll need a cloud provider for those specific features.

This is usually fine for a dev/production split. Most agent logic (tools, structured output, conversation flow) doesn't depend on images or audio. You can run the core agent logic against Ollama locally, and the multimedia features only come into play in staging or production against cloud providers.

Testing Agents That Use Ollama

One thing to be aware of: when running your test suite, you probably don't want tests making real Ollama calls any more than you'd want real OpenAI calls. The SDK's fake testing utilities work regardless of which provider is configured:

it('responds to password reset questions', function () {
    SupportAgent::fake([
        'To reset your password, visit the login page and click "Forgot password".',
    ]);

    $response = SupportAgent::make()->prompt('How do I reset my password?');

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

Faking the agent response means your tests are fast, deterministic, and don't depend on Ollama being installed or running. The agent safety post covers more on keeping agent behavior predictable in tests.

The development workflow then becomes: build and iterate against real Ollama locally, run the test suite with faked responses, deploy with cloud providers in production.

Ollama on a Shared Dev Server

If your team uses a shared development server, you can run Ollama there and point everyone's local Laravel instances at it. Just update OLLAMA_URL in each developer's .env:

OLLAMA_URL=http://your-dev-server:11434/api

Make sure Ollama is configured to accept connections from outside localhost on the server:

OLLAMA_HOST=0.0.0.0 ollama serve

This means one machine does the model serving and your team shares it, without everyone needing to pull and run models locally. Useful if some team members are on constrained hardware.

FAQ

Does Ollama work with Laravel AI SDK agents that use tools?

Yes, but model quality matters more for tool use. Some smaller models handle tool calls inconsistently. Llama 3.2 8B is reliable for tool use. If you're seeing missed or malformed tool calls, try a larger or more capable model.

Can I use Ollama in production?

You can if you have dedicated server hardware with enough RAM and ideally a GPU. Most teams use Ollama for local development and testing, then cloud providers in production. The cost and maintenance overhead of running Ollama in production usually outweighs the savings unless you have high volume and a specific privacy requirement.

What's the difference between Ollama and running models via API?

With Ollama, the model runs on your machine. No data leaves your network. With cloud APIs (OpenAI, Anthropic), your prompts are sent to the provider's servers. For development involving sensitive or proprietary data, Ollama is the better choice.

Do I need a GPU?

No. Most models run on CPU, just more slowly. For development iteration a CPU is fine. Responses take 5-15 seconds depending on model size and your hardware. A GPU drops that to under 2 seconds for 7B models.

Can I use Ollama with the sub-agents pattern?

Yes. Each sub-agent can have its own #[Provider(Lab::Ollama)] and #[Model] attributes. The sub-agents guide covers the full pattern; the Ollama attributes drop in without any other changes.

Start Locally

The setup comes down to four steps: install Ollama, pull a model, add OLLAMA_API_KEY= to your .env, and add #[Provider(Lab::Ollama)] to your agent class. After that, you're running AI locally with no API costs and no rate limits while you build.

In production, switch back to OpenAI or Anthropic by changing the provider attribute or your default config. The rest of your code stays exactly the same.

If you're setting this up for a team or have questions about the dev/production split, get in touch.