DEV Community: Hafiz

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.

Laravel CI/CD with GitHub Actions: Tests, Code Quality, and Deployment

Hafiz — Thu, 14 May 2026 05:08:36 +0000

If you're still deploying Laravel by running git pull on the server and crossing your fingers, this post is for you. And if you've got tests but they only run when you remember to run them locally, this post is for you too.

GitHub Actions gives you a free CI/CD pipeline that runs on every push. For Laravel, a complete pipeline means: style checks, static analysis, your test suite, asset builds, and an automated deploy when everything passes. Set it up once and you never think about it again.

This post builds the complete pipeline from scratch. Every step is explained, the full workflow file appears at the end as a copy-paste block, and the deployment section covers three different approaches depending on how you host.

What the Pipeline Does

Before writing any YAML, here's the full flow:

Code quality checks run first. No point running 400 tests if the formatting is broken. Tests run after. Deployment only triggers on the main branch after everything else passes.

Setting Up the Workflow File

GitHub Actions workflows live in .github/workflows/. Create:

.github/
  workflows/
    ci.yml

Start with the trigger and environment:

name: Laravel CI/CD

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  PHP_VERSION: '8.4'
  NODE_VERSION: '20'

This runs on every push to main or develop, and on every pull request targeting main. Adjust the branches to match your workflow.

Step 1: Checkout and PHP Setup

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ env.PHP_VERSION }}
          extensions: mbstring, xml, ctype, json, bcmath, pdo_sqlite
          coverage: none

shivammathur/setup-php is the community standard for PHP in GitHub Actions. Setting coverage: none is important: it skips loading Xdebug, which meaningfully speeds up the setup step. Only enable coverage if you need coverage reports.

pdo_sqlite is in the extensions list because we'll run tests against an in-memory SQLite database, which is faster and simpler than spinning up a MySQL service container.

Step 2: Install Dependencies with Caching

Composer downloads can take a while. Caching the vendor directory means subsequent runs skip the download if composer.lock hasn't changed:

      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
          path: vendor
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-composer-

      - name: Install Composer dependencies
        run: composer install --no-interaction --prefer-dist --optimize-autoloader --no-progress

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install NPM dependencies
        run: npm ci

actions/setup-node@v4 handles npm caching natively when you pass cache: 'npm'. No separate cache step needed.

composer install flags:

--no-interaction: prevents prompts that would hang the CI runner
--prefer-dist: downloads zip archives instead of git clones, faster
--optimize-autoloader: generates an optimized classmap
--no-progress: cleaner output in CI logs

Step 3: Prepare the Laravel Environment

      - name: Copy environment file
        run: cp .env.example .env.ci

      - name: Generate application key
        run: php artisan key:generate --env=ci

      - name: Set directory permissions
        run: chmod -R 755 storage bootstrap/cache

Create a .env.ci file in your repo with CI-specific settings. The critical part is pointing the database at SQLite:

APP_ENV=testing
APP_KEY=
DB_CONNECTION=sqlite
DB_DATABASE=:memory:
CACHE_DRIVER=array
SESSION_DRIVER=array
QUEUE_CONNECTION=sync
MAIL_MAILER=array

Using DB_DATABASE=:memory: means no file gets created, no cleanup needed, and tests run significantly faster. For the artisan commands that reference the database during testing, this just works.

Step 4: Code Style with Laravel Pint

      - name: Check code style with Pint
        run: vendor/bin/pint --test

The --test flag is essential here. Without it, Pint would fix style issues and commit them. You don't want your CI runner making commits. With --test, it exits with code 1 if issues are found, failing the build.

Pint runs first because it's the cheapest check. If someone pushes without running pint locally, CI catches it immediately without burning time on tests.

Step 5: Static Analysis with Larastan

Larastan is PHPStan configured for Laravel. It understands facades, magic methods, relationships, and request properties that vanilla PHPStan would flag as errors:

composer require nunomaduro/larastan --dev

Create phpstan.neon in your project root:

includes:
    - vendor/nunomaduro/larastan/extension.neon

parameters:
    paths:
        - app
    level: 5
    ignoreErrors:
        - '#Call to an undefined method Illuminate\\Database\\Eloquent\\Builder#'

Level 5 is a solid starting point. It catches undefined method calls and type mismatches without being so strict that you spend more time on type annotations than features. In the workflow:

      - name: Run static analysis
        run: vendor/bin/phpstan analyse --memory-limit=512M --no-progress

--memory-limit=512M prevents PHPStan from hitting PHP's memory limit on large codebases.

Step 6: Run the Test Suite

      - name: Run tests
        env:
          DB_CONNECTION: sqlite
          DB_DATABASE: ':memory:'
        run: vendor/bin/pest --parallel

Passing DB_CONNECTION and DB_DATABASE as env vars here ensures they override whatever's in your .env.ci. The --parallel flag runs test files concurrently across available CPU cores. On a 4-core GitHub Actions runner, parallel mode typically cuts test suite time by 50-60%.

If you're still on PHPUnit, replace pest with phpunit.

Step 7: Build Frontend Assets

      - name: Build assets with Vite
        run: npm run build

This step serves two purposes. It catches import errors or missing dependencies that would break the frontend. And in some deployment setups, you'll want to upload the built assets rather than building on the server.

Deployment Options

This is where setups diverge. The approach depends on how you host. Three options, in order of complexity.

Option A: Laravel Forge (Simplest)

Forge has a deploy hook, a URL you trigger to run your deploy script. Copy it from your Forge site's Deployments tab and store it as a GitHub secret:

  deploy:
    needs: build-and-test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

    steps:
      - name: Trigger Forge deployment
        run: curl -s "${{ secrets.FORGE_DEPLOY_HOOK }}"

The needs: build-and-test line means this job only runs if the previous job passed. if: github.ref == 'refs/heads/main' restricts deployment to the main branch. PRs run tests but don't deploy.

This is the lowest-friction option. Forge handles the deploy script, zero-downtime switching, and restart management on the server side.

Option B: SSH Deployment

For VPS deployments not managed by Forge, use appleboy/ssh-action:

      - name: Deploy via SSH
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/myapp
            git pull origin main
            composer install --no-dev --optimize-autoloader
            php artisan migrate --force
            php artisan config:cache
            php artisan route:cache
            php artisan view:cache
            php artisan queue:restart

Add these secrets to your GitHub repository under Settings > Secrets and variables > Actions:

SSH_HOST: your server's IP or domain
SSH_USER: the deploy user (create a dedicated non-root user)
SSH_PRIVATE_KEY: the private key whose public key is in the server's authorized_keys

php artisan migrate --force is required in non-interactive environments. Without --force, Laravel prompts for confirmation before running migrations in production. The queue restart command signals workers to gracefully restart after code is updated, so they pick up the new code rather than continuing to run old code.

Option C: Scotty (SSH Task Runner)

If you prefer defining your deploy steps as reusable scripts rather than inline YAML, Scotty pairs well with this setup. Scotty uses plain bash syntax and gives you better deploy output than raw SSH scripts. The Scotty vs Envoy comparison covers when it's worth the switch.

You'd SSH into the server and run your Scotty deploy task:

      - name: Deploy with Scotty
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/myapp
            git pull origin main
            ./vendor/bin/scotty run deploy

Managing Secrets and Environment Variables

GitHub Secrets are encrypted environment variables stored at the repository level. They're never exposed in logs, even if a step tries to print them. Add them under Settings > Secrets and variables > Actions.

For a typical Laravel CI/CD setup, you'll need:

Secret	Used in
`FORGE_DEPLOY_HOOK`	Forge webhook URL to trigger deployment
`SSH_HOST`	Server IP or hostname for SSH deployment
`SSH_USER`	SSH username
`SSH_PRIVATE_KEY`	Private key content (the full key, not a path)

For SSH_PRIVATE_KEY, copy the full content of your private key file (typically ~/.ssh/id_rsa or ~/.ssh/id_ed25519). Paste the entire thing into the secret value, including the -----BEGIN and -----END lines.

One mistake that trips people up: the .env.example file in your repo gets copied to .env.ci during the workflow, but any variables that are genuinely secret (API keys, payment credentials) should not be in .env.example. Use GitHub Secrets for those and inject them as environment variables in the relevant step:

      - name: Run tests
        env:
          DB_CONNECTION: sqlite
          DB_DATABASE: ':memory:'
          STRIPE_SECRET: ${{ secrets.STRIPE_SECRET }}
        run: vendor/bin/pest --parallel

Never commit real secrets to your repo. Even in private repositories. The Composer dependency audit post covers how supply chain attacks target credentials left in repositories. The same principle applies to your CI configuration.

Adding a Status Badge

Once your workflow is running, you can add a status badge to your README.md. It shows the current state of your main branch pipeline:

![Laravel CI](https://github.com/{owner}/{repo}/actions/workflows/ci.yml/badge.svg)

Replace {owner} and {repo} with your GitHub username and repository name. The badge updates automatically after each run. Green means everything passed, red means something failed. Useful at a glance and signals to contributors that the project takes CI seriously.

Branch Strategy

If you're building a SaaS product on Laravel, a working CI/CD pipeline from the start saves significant pain later. The SaaS with Laravel and Filament guide covers the broader architecture, and this pipeline slots in as the deployment layer on top of it.

A pipeline that runs identically on every branch isn't optimized. Here's a sensible split:

On pull requests (any branch → main): Run Pint, Larastan, and tests. Block merging if anything fails. No deployment.

On push to main: Run everything. Deploy only if all checks pass.

On push to develop: Run checks and tests. No deployment (or deploy to a staging environment if you have one).

The workflow trigger at the top handles this:

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

And the deployment job's if condition handles the rest:

if: github.ref == 'refs/heads/main' && github.event_name == 'push'

The Complete Workflow File

Here's the full .github/workflows/ci.yml for copy-pasting:

name: Laravel CI/CD

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  PHP_VERSION: '8.4'
  NODE_VERSION: '20'

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ env.PHP_VERSION }}
          extensions: mbstring, xml, ctype, json, bcmath, pdo_sqlite
          coverage: none

      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
          path: vendor
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-composer-

      - name: Install Composer dependencies
        run: composer install --no-interaction --prefer-dist --optimize-autoloader --no-progress

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install NPM dependencies
        run: npm ci

      - name: Copy environment file
        run: cp .env.example .env.ci

      - name: Generate application key
        run: php artisan key:generate --env=ci

      - name: Set directory permissions
        run: chmod -R 755 storage bootstrap/cache

      - name: Check code style with Pint
        run: vendor/bin/pint --test

      - name: Run static analysis
        run: vendor/bin/phpstan analyse --memory-limit=512M --no-progress

      - name: Run tests
        env:
          DB_CONNECTION: sqlite
          DB_DATABASE: ':memory:'
        run: vendor/bin/pest --parallel

      - name: Build assets
        run: npm run build

  deploy:
    needs: build-and-test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

    steps:
      - name: Deploy
        # Choose one of the deployment options above and add it here
        run: curl -s "${{ secrets.FORGE_DEPLOY_HOOK }}"

FAQ

Do I need a paid GitHub plan to use GitHub Actions?

No. GitHub Actions is free for public repositories and includes 2,000 minutes per month for private repositories on free plans. Most Laravel projects fit comfortably within that limit. The ubuntu-latest runner costs 1 minute per minute of usage.

What if I don't have Larastan set up yet?

Remove the static analysis step and add it back once you've configured phpstan.neon. Don't skip Pint. It takes 10 seconds to set up and pays off immediately.

Can I run tests against MySQL instead of SQLite?

Yes. Add a MySQL service container to your job, then update the database env vars. The tradeoff is slower pipelines (MySQL startup adds 15-30 seconds) and the added complexity of service container health checks. SQLite in-memory is the right default for most apps.

Why npm ci instead of npm install?

npm ci installs exactly what's in package-lock.json and fails if there are any discrepancies. npm install can update lockfiles silently. In CI you want reproducibility, so npm ci is correct.

My tests pass locally but fail in CI. Where do I start?

Nine times out of ten it's an environment difference. Check: missing PHP extensions, .env.ci values not matching what tests expect, or missing APP_KEY. Add a debug step early in the workflow that runs php artisan about, which surfaces environment details quickly.

Put It in Place

The workflow file goes in .github/workflows/ci.yml. Add .env.ci to your repo with your CI-specific values. Add secrets to your repository settings. Push to a branch, open a pull request, and watch the checks run.

After that, every PR gets a green or red status before it's merged. Every push to main deploys automatically when it passes. You stop thinking about deployment and start thinking about what you're building.

If you're setting this up for the first time and hit a wall, get in touch and we can work through it together.

Laravel AI SDK Sub-Agents: Build Multi-Agent Systems That Actually Scale

Hafiz — Tue, 12 May 2026 05:03:07 +0000

Taylor Otwell shipped sub-agent support to the Laravel AI SDK. The announcement is short: return an agent from another agent's tools() method and the parent can delegate focused tasks to it. But what it unlocks is significant.

Before this, you could simulate sub-agents by wrapping agent() calls inside a tool's handle() method. It worked, and the multi-agent patterns post covers that approach in detail. But it was a workaround. The agent logic lived inside a tool class, not in a proper Agent class with its own instructions, tools, provider config, and context.

Now sub-agents are first-class citizens. This post covers how the new API works and how to build a realistic multi-agent system with it.

What Sub-Agents Actually Are

A sub-agent is a dedicated Laravel AI Agent class that a parent agent can invoke as a tool. The parent delegates work to it exactly the way it would call any other tool. The difference is that the sub-agent runs with full autonomy: its own instructions, its own tool set, its own provider configuration, and its own isolated context window.

This matters for a few reasons.

Isolation. The parent's conversation history doesn't bleed into the sub-agent. The sub-agent starts fresh with just its own instructions and what the parent passes to it. No context pollution, no token waste from irrelevant history.

Specialization. Each sub-agent is a proper PHP class with its own instructions(), tools(), and optional schema(). You can build a billing specialist, a technical support specialist, and an order lookup specialist, each configured precisely for its job.

Model flexibility. A sub-agent can run on a different provider or model than its parent. Route simple queries to a cheap model. Route complex reasoning to a capable one. The parent doesn't know or care.

The API

Before sub-agents, you'd build a multi-agent orchestrator by wrapping agents in tool classes. The workaround looked roughly like this:

class HandleRefundTool implements Tool
{
    public function description(): string
    {
        return 'Process a refund request for a customer.';
    }

    public function handle(Request $request): string
    {
        // Agent logic stuffed inside a tool class
        return (string) agent()
            ->withInstructions('You are a refund specialist...')
            ->prompt($request['query']);
    }

    public function schema(JsonSchema $schema): array
    {
        return ['query' => $schema->string()->required()];
    }
}

This works, but the agent logic is buried in a tool. There's no proper instructions() method, no tools() method, no structured output. It's a second-class agent.

With sub-agents, you return a real Agent class directly from tools():

class CustomerSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a customer support orchestrator. Analyze the customer\'s 
                message and delegate to the appropriate specialist agent.';
    }

    public function tools(): iterable
    {
        return [
            new BillingAgent,
            new TechnicalSupportAgent,
            new OrderAgent,
        ];
    }
}

Each of those is a full Agent class with its own configuration. The SDK handles the delegation. The parent sees them as tools and calls them when it decides the task fits their domain.

Building a Real Example

Let's build a customer support system for a SaaS product. Users send messages. A parent orchestrator agent decides which specialist handles the response.

Start with the sub-agents. Each is a focused specialist.

BillingAgent

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\ProcessRefund;
use App\Ai\Tools\CheckSubscriptionStatus;
use App\Ai\Tools\UpdatePaymentMethod;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class BillingAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a billing specialist. You handle refund requests, 
                subscription changes, and payment issues. Be concise and 
                solution-focused. Always confirm before processing any changes.';
    }

    public function tools(): iterable
    {
        return [
            new ProcessRefund,
            new CheckSubscriptionStatus,
            new UpdatePaymentMethod,
        ];
    }
}

TechnicalSupportAgent

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\QueryKnowledgeBase;
use App\Ai\Tools\CreateSupportTicket;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class TechnicalSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a technical support engineer. Diagnose issues, 
                search the knowledge base for solutions, and escalate 
                to a ticket when the problem requires engineering attention.';
    }

    public function tools(): iterable
    {
        return [
            new QueryKnowledgeBase,
            new CreateSupportTicket,
        ];
    }
}

OrderAgent

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\LookupOrder;
use App\Ai\Tools\TrackShipment;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class OrderAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are an order specialist. Look up order status, 
                track shipments, and resolve delivery issues.';
    }

    public function tools(): iterable
    {
        return [
            new LookupOrder,
            new TrackShipment,
        ];
    }
}

CustomerSupportAgent (the orchestrator)

<?php

namespace App\Ai\Agents;

use App\Models\User;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class CustomerSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): string
    {
        return "You are a customer support orchestrator for {$this->user->company_name}. 
                Analyze incoming messages and delegate to the right specialist:
                - BillingAgent: refunds, subscription changes, payment problems
                - TechnicalSupportAgent: bugs, errors, feature questions  
                - OrderAgent: order status, shipping, delivery

                Don't answer questions yourself. Always delegate to the appropriate 
                specialist and return their response directly.";
    }

    public function tools(): iterable
    {
        return [
            new BillingAgent,
            new TechnicalSupportAgent,
            new OrderAgent,
        ];
    }
}

Prompting it from a controller:

public function handle(Request $request)
{
    $response = CustomerSupportAgent::make($request->user())
        ->prompt($request->input('message'));

    return response()->json(['reply' => (string) $response]);
}

The parent receives the message, decides which specialist fits, delegates to that Agent, and returns the result. You didn't hardcode routing logic. The model figures out the delegation from the instructions.

Using Different Models Per Sub-Agent

This is where sub-agents clearly beat the old workaround. You can configure a different provider or model on each sub-agent using PHP attributes directly on the class.

Simple billing queries don't need a powerful model. Complex technical debugging does. The official API uses the #[Provider] and #[Model] attributes from Laravel\Ai\Attributes:

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

#[Provider(Lab::OpenAI)]
#[Model('gpt-4o-mini')]
class BillingAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a billing specialist...';
    }

    public function tools(): iterable
    {
        return [new ProcessRefund, new CheckSubscriptionStatus];
    }
}

#[Provider(Lab::Anthropic)]
#[Model('claude-opus-4-5')]
class TechnicalSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a technical support engineer...';
    }

    public function tools(): iterable
    {
        return [new QueryKnowledgeBase, new CreateSupportTicket];
    }
}

The SDK also ships #[UseCheapestModel] and #[UseSmartestModel] convenience attributes if you'd rather let the provider decide which model to use rather than hardcoding a model string:

use Laravel\Ai\Attributes\UseCheapestModel;
use Laravel\Ai\Attributes\UseSmartestModel;

#[UseCheapestModel]
class BillingAgent implements Agent, HasTools { ... }

#[UseSmartestModel]
class TechnicalSupportAgent implements Agent, HasTools { ... }

The parent orchestrator doesn't know or care which model its sub-agents use. Each runs with its own attributes. This is the practical cost-reduction pattern: cheap models for routine work, capable models only where reasoning depth matters.

Sub-Agents with Structured Output

Sub-agents support structured output the same way regular agents do. If you want the BillingAgent to always return a typed response:

class BillingAgent implements Agent, HasTools, HasStructuredOutput
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a billing specialist. Always return structured results.';
    }

    public function tools(): iterable
    {
        return [new ProcessRefund, new CheckSubscriptionStatus];
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'action_taken' => $schema->string()->required(),
            'resolved'     => $schema->boolean()->required(),
            'message'      => $schema->string()->required(),
        ];
    }
}

The parent receives the structured result from the sub-agent and can use it in its own response or pass it directly back to the caller. This is useful when you need predictable shapes in downstream code, not just a string.

Sub-Agents vs Regular Tools vs agent() Helper

The question you'll hit: when does a sub-agent make sense vs a regular tool vs the agent() helper approach?

A regular tool is right when you're executing a deterministic operation. Looking up a database record, calling an API, running a calculation. No LLM needed in the tool itself; just PHP logic.

The agent() helper (covered in the multi-agent patterns guide) is right for quick inline delegation where you don't need a reusable, testable agent class. It's faster to write but harder to test and reuse.

A sub-agent is right when the delegated work itself requires AI reasoning, has its own set of tools, needs different model config, or is complex enough to warrant its own class with proper instructions. If the delegated task would make sense as a standalone agent on its own, it should be a sub-agent.

A practical rule: if the thing you're delegating to could be independently useful in another context (a BillingAgent, a CodeReviewAgent, an OnboardingAgent), make it a sub-agent. If it's a one-off operation that only makes sense in this specific orchestrator, a regular tool is simpler.

When to Reach for Sub-Agents

Sub-agents shine in three specific scenarios.

Domain routing. You have a broad entry point (customer support, document processing, code review) that needs to delegate to specialists. Each specialist has meaningfully different instructions and tools. The orchestrator shouldn't need to know how each domain works. This is the cleanest use case and the one Taylor's tweet shows directly: a parent agent that routes to a RefundAgent without knowing anything about how refunds actually work.

Cost-optimized workflows. Different tasks warrant different model tiers. Route classification and simple lookups to cheaper models. Reserve the expensive models for tasks that actually need reasoning depth. Sub-agents let you encode that decision in configuration rather than in logic. The billing example above uses gpt-4o-mini for straightforward billing queries but claude-opus-4-5 for technical debugging. You set it once per sub-agent class and it applies everywhere that agent is used.

Large context isolation. If each sub-agent starts with a clean context, you avoid burning tokens on conversation history that's irrelevant to the current task. The parent passes only what the sub-agent needs to know. This is particularly useful when you're also dealing with agent safety concerns, a sub-agent with limited context has a smaller blast radius. A billing sub-agent that only sees the billing-related part of the request can't accidentally act on unrelated data it shouldn't have access to.

When to skip sub-agents. Don't reach for them when a single well-prompted agent handles the task cleanly, or when the overhead of multiple LLM calls is disproportionate to the task's complexity. If your use case is a simple chatbot or a single-domain assistant, sub-agents add latency and cost without adding capability. Start simple. The smart assistant tutorial shows what a well-built single-agent system looks like, and a lot of products never need to go beyond that.

The right question is: does the delegated task benefit from having its own dedicated AI reasoning, its own tools, and isolation from the parent's context? If yes, it's a sub-agent. If it's just a database lookup or a deterministic operation, keep it as a regular tool. The tools and memory tutorial covers the regular tool pattern if you need a refresher on when tools are enough.

Passing Context to Sub-Agents

One thing worth knowing: sub-agents are resolved from the container just like top-level agents. That means you can inject dependencies into them through the constructor.

If your BillingAgent needs access to a specific user's subscription data, pass it through:

class CustomerSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): string
    {
        return 'You are a customer support orchestrator...';
    }

    public function tools(): iterable
    {
        return [
            new BillingAgent($this->user),
            new TechnicalSupportAgent,
            new OrderAgent($this->user),
        ];
    }
}

And in the BillingAgent:

class BillingAgent implements Agent, HasTools
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): string
    {
        $plan = $this->user->subscription?->plan ?? 'free';

        return "You are a billing specialist for a {$plan} plan customer. 
                Customer name: {$this->user->name}. 
                Handle refund requests, subscription changes, and billing issues.";
    }

    public function tools(): iterable
    {
        return [
            new ProcessRefund($this->user),
            new CheckSubscriptionStatus($this->user),
        ];
    }
}

The sub-agent's instructions are dynamically built from the injected user. This is a clean pattern when the specialist's behaviour needs to vary by user context (plan level, account age, support tier). The orchestrator passes the relevant model down to each sub-agent that needs it, keeping the routing logic clean and the specialist logic contained.

Don't over-inject. Sub-agents with too many dependencies become hard to test and understand. The goal is focused specialists. If a sub-agent needs more than one or two injected dependencies, that's often a sign it's trying to do too much.

Testing Sub-Agents

The Laravel AI SDK ships full faking support for agents, confirmed in the official docs: "Fake agents, images, audio, transcriptions, embeddings, reranking, and file stores, so you can ship AI features with real test coverage." This applies to sub-agents the same way it applies to top-level agents.

The general approach is to test each sub-agent in isolation with fake responses, then test the orchestrator separately to verify routing behaviour. Sub-agents are just regular Agent classes, so the same testing patterns from the AI SDK tutorial series apply directly.

For the exact faking API syntax, check the Testing section of the Laravel AI SDK docs. The sub-agent tests follow the same structure as single-agent tests. The only difference is you test each class independently rather than the full orchestration chain at once.

FAQ

Do sub-agents share conversation history with the parent?

No. Each sub-agent has isolated context. The parent passes a task to the sub-agent and the sub-agent works from its own instructions. This is by design and is one of the main benefits of the sub-agent pattern over stuffing agent logic into a tool.

Can a sub-agent have its own sub-agents?

Yes. Since a sub-agent is just a regular Agent class, it can return other Agent classes from its own tools() method. You can nest as deeply as you need, though more than two levels of nesting adds latency and complexity quickly. Most use cases are well-served with one level of sub-agents.

Does this work with streaming?

Yes. Sub-agents support streaming the same way top-level agents do. If the parent agent streams, the response from sub-agents flows through naturally.

What Laravel and PHP versions are required?

The Laravel AI SDK requires PHP 8.2+ and Laravel 12 or 13. Sub-agents are part of the same package, so the same requirements apply.

How does billing work with multiple LLM calls?

Each sub-agent invocation is a separate API call, billed separately at whatever rates your configured provider charges. The cost-optimization angle of using cheaper models for simpler sub-agents is real and worth planning upfront, especially for high-volume endpoints.

Start Building

Sub-agents are a clean solution to the complexity ceiling that single-agent systems eventually hit. The orchestrator stays focused on routing. Each specialist stays focused on its domain. Provider costs stay proportionate to task complexity.

The API is exactly what you'd expect from a Laravel feature: one method change, no boilerplate, full PHP class support. If you've already got agents running in your app, adding sub-agents is a refactor, not a rewrite.

If you're building a multi-agent system and want a second opinion on the architecture, get in touch.

Building an Audit Log in Laravel with spatie/laravel-activitylog v5

Hafiz — Mon, 11 May 2026 05:29:50 +0000

Every SaaS reaches a point where "who changed that?" stops being a casual question and starts being a support ticket. A team member deletes a project. A setting gets changed and nobody knows when. A user loses access and blames an admin. Without an audit log, you're guessing. And in enterprise deals, the absence of audit logging can be an actual blocker.

spatie/laravel-activitylog has been the go-to solution for this in the Laravel ecosystem for years, with over 48 million Packagist installs. Version 5 shipped in late March 2026, and it's a meaningful upgrade: PHP 8.4+, a cleaner API, a new database schema, and properly swappable internals. This post walks through building a complete audit log system for a Laravel SaaS using v5, from installation to displaying the log in Filament.

If you're already on v4, there's a migration section at the end covering the breaking changes.

What Changed in v5

Freek covered the full list on his blog, but the things that matter most for day-to-day use:

No boilerplate for basic model logging. In v4, adding the LogsActivity trait to a model also required a getActivitylogOptions() method even for the simplest cases. In v5, the trait alone is enough to start logging. You only override getActivitylogOptions() when you need custom behaviour.

New attribute_changes column. The old changes column is replaced by attribute_changes, which stores a cleaner structure with attributes (the new values) and old (the previous values). This means a small schema migration if you're upgrading, but fresh installs get a better foundation.

ActivityEvent enum for type-safe filtering. v5 introduces an ActivityEvent enum so you're not relying on raw strings when filtering by event type:

use Spatie\Activitylog\Enums\ActivityEvent;

Activity::forEvent(ActivityEvent::Created)->get();
Activity::forEvent(ActivityEvent::Updated)->get();
Activity::forEvent(ActivityEvent::Deleted)->get();

Plain strings still work for custom event names. But for the standard events, the enum gives you autocompletion and catches typos at the IDE level rather than at runtime.

Customizable action classes. The core operations (saving activities, cleaning old records) are now action classes you can extend and swap via config. This makes it practical to do things like queue activity saves during a request, or redact sensitive fields before anything hits the database.

Installation

Requires PHP 8.4+ and Laravel 12 or 13. Install the package:

composer require spatie/laravel-activitylog

Publish and run the migrations:

php artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-migrations"
php artisan migrate

This creates the activity_log table with the new v5 schema. You can find the full list of available artisan commands in the Laravel Artisan Commands reference.

Optionally publish the config file:

php artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-config"

The config file at config/activitylog.php controls the activity model class, the default log name, the number of days before old records get pruned, and the action classes used internally.

Manual Activity Logging

The simplest usage is logging arbitrary events:

activity()->log('User exported the reports CSV');

More useful is attaching context. You want to know what was affected and who did it:

activity()
    ->performedOn($project)
    ->causedBy($user)
    ->withProperties(['plan' => 'pro', 'via' => 'settings-page'])
    ->log('upgraded plan');

Retrieving logged activities uses the Activity model with a set of built-in query scopes:

use Spatie\Activitylog\Models\Activity;

// All activity for a specific subject
Activity::forSubject($project)->get();

// All activity caused by a user
Activity::causedBy($user)->get();

// Filter by event type
Activity::forEvent('updated')->get();

// Filter by log name (useful when grouping logs by domain)
Activity::inLog('billing')->get();

// Combine scopes
Activity::forSubject($project)
    ->causedBy($user)
    ->latest()
    ->get();

Each Activity record gives you description, subject, causer, event, properties, and attribute_changes. The getProperty() helper reads from the custom properties you attached.

Automatic Model Event Logging

This is where the package earns its place. Add the LogsActivity trait to any Eloquent model and it automatically logs created, updated, and deleted events:

use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;

class Project extends Model
{
    use LogsActivity;
}

That's all you need for basic logging. Any create, update, or delete on this model now creates an activity record.

To control which attributes get tracked, override getActivitylogOptions():

use Spatie\Activitylog\Support\LogOptions;

class Project extends Model
{
    use LogsActivity;

    protected $fillable = ['name', 'description', 'status', 'owner_id'];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
            ->logOnly(['name', 'status', 'owner_id'])
            ->logOnlyDirty()
            ->dontSubmitEmptyLogs();
    }
}

logOnly() limits tracking to specific attributes. logOnlyDirty() means only attributes that actually changed get recorded, not everything including updated_at noise. dontSubmitEmptyLogs() skips saving a record when nothing meaningful changed.

When a project gets updated, the activity record's attribute_changes looks like this:

$activity->attribute_changes;
// [
//     'attributes' => [
//         'status' => 'active',
//         'owner_id' => 42,
//     ],
//     'old' => [
//         'status' => 'draft',
//         'owner_id' => 7,
//     ],
// ]

You can also use logAll() combined with logExcept() to track everything except specific fields:

return LogOptions::defaults()
    ->logAll()
    ->logExcept(['remember_token', 'updated_at']);

And logFillable() to automatically track whatever is in the $fillable array, useful when your fillable list is the authoritative record of what users can change:

return LogOptions::defaults()
    ->logFillable()
    ->logOnlyDirty();

In a typical SaaS you'd apply this to several models at once. A project management app might log changes to Project, Team, Invitation, and Role models, each tracking different attributes:

class Team extends Model
{
    use LogsActivity;

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
            ->logOnly(['name', 'owner_id', 'plan'])
            ->logOnlyDirty()
            ->setDescriptionForEvent(fn(string $event) => "Team was {$event}")
            ->dontSubmitEmptyLogs();
    }
}

class Invitation extends Model
{
    use LogsActivity;

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
            ->logOnly(['email', 'role', 'accepted_at'])
            ->logOnlyDirty()
            ->useLogName('invitations');
    }
}

The setDescriptionForEvent() method lets you control the human-readable description that gets stored. The default is just the event name ("updated", "created"), but a more descriptive string is easier to read in an admin panel.

Grouping Activity with Named Logs

By default everything lands in the default log. For a SaaS with distinct domains (billing, security, content), separating into named logs keeps queries focused and makes it practical to surface the right activity in the right UI context.

Set a log name on the model:

class SubscriptionChange extends Model
{
    use LogsActivity;

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
            ->useLogName('billing')
            ->logOnly(['plan', 'status', 'cancelled_at']);
    }
}

Or set it on a manual log call:

activity('security')
    ->causedBy($user)
    ->withProperties(['ip' => request()->ip()])
    ->log('Two-factor authentication disabled');

Then query each log independently:

// Billing events only
Activity::inLog('billing')->latest()->get();

// Security events for a specific user
Activity::inLog('security')
    ->causedBy($user)
    ->latest()
    ->get();

In Filament, add a filter that lets admins switch between log channels:

Tables\Filters\SelectFilter::make('log_name')
    ->label('Log')
    ->options([
        'default'  => 'General',
        'billing'  => 'Billing',
        'security' => 'Security',
    ]),

This pattern avoids the query performance issues that come from filtering a single massive activity_log table by subject type. Named logs give you logical partitioning without needing separate database tables.

Enriching Logs Before They Save

Sometimes you need to attach extra context right before an activity is persisted. The beforeActivityLogged() method on your model runs at that moment:

class Project extends Model
{
    use LogsActivity;

    public function beforeActivityLogged(Activity $activity, string $eventName): void
    {
        $activity->properties = $activity->properties->merge([
            'ip_address' => request()->ip(),
            'user_agent' => request()->userAgent(),
        ]);
    }
}

This is the right place to add request context, session data, or anything that isn't on the model itself. Don't use model observers for this. The beforeActivityLogged hook runs in the correct position in the activity lifecycle.

Redacting Sensitive Fields

By default, if you log a User model, attribute changes will include whatever fields you track. If that includes anything sensitive, you want to strip it before it hits the database.

Create a custom action class:

namespace App\ActivityLog;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Arr;
use Spatie\Activitylog\Actions\LogActivityAction;

class RedactSensitiveFieldsAction extends LogActivityAction
{
    protected function transformChanges(Model $activity): void
    {
        $changes = $activity->attribute_changes?->toArray() ?? [];

        Arr::forget($changes, [
            'attributes.password',
            'old.password',
            'attributes.two_factor_secret',
            'old.two_factor_secret',
        ]);

        $activity->attribute_changes = $changes;
    }
}

'actions' => [
    'log_activity' => \App\ActivityLog\RedactSensitiveFieldsAction::class,
],

Now password changes never appear in your logs, regardless of which model triggers them. You can also override save() on the action class to dispatch a queued job instead of writing synchronously, which helps if you're concerned about activity logging adding latency during high-traffic requests. The queue jobs guide covers the patterns that apply here.

Displaying the Activity Log in Filament

An audit log is only useful if someone can actually read it. If you're using Filament, the quickest way is a dedicated resource. If you're building a SaaS admin panel, the Filament admin guide covers the broader setup.

Generate the resource:

php artisan make:filament-resource ActivityLog --view

Then configure the list table in ActivityLogResource.php:

use Spatie\Activitylog\Models\Activity;

public static function getModel(): string
{
    return Activity::class;
}

public static function table(Table $table): Table
{
    return $table
        ->columns([
            Tables\Columns\TextColumn::make('causer.name')
                ->label('User')
                ->searchable()
                ->sortable(),

            Tables\Columns\TextColumn::make('description')
                ->label('Action')
                ->searchable(),

            Tables\Columns\TextColumn::make('subject_type')
                ->label('Subject')
                ->formatStateUsing(fn ($state) => class_basename($state))
                ->sortable(),

            Tables\Columns\TextColumn::make('event')
                ->badge()
                ->color(fn (string $state): string => match ($state) {
                    'created' => 'success',
                    'updated' => 'warning',
                    'deleted' => 'danger',
                    default   => 'gray',
                }),

            Tables\Columns\TextColumn::make('created_at')
                ->label('When')
                ->dateTime()
                ->sortable(),
        ])
        ->defaultSort('created_at', 'desc')
        ->filters([
            Tables\Filters\SelectFilter::make('event')
                ->options([
                    'created' => 'Created',
                    'updated' => 'Updated',
                    'deleted' => 'Deleted',
                ]),
        ])
        ->actions([
            Tables\Actions\ViewAction::make(),
        ]);
}

For the view page, show the attribute_changes as a formatted diff so admins can see exactly what changed:

public static function infolist(Infolist $infolist): Infolist
{
    return $infolist
        ->schema([
            Infolists\Components\TextEntry::make('causer.name')->label('User'),
            Infolists\Components\TextEntry::make('description')->label('Action'),
            Infolists\Components\TextEntry::make('created_at')->label('When')->dateTime(),
            Infolists\Components\KeyValueEntry::make('attribute_changes.attributes')
                ->label('New values'),
            Infolists\Components\KeyValueEntry::make('attribute_changes.old')
                ->label('Previous values'),
        ]);
}

This gives admins a readable before/after comparison for any update event. For larger teams, you'd add subject-specific filters and restrict access to senior roles via Filament's policy integration, which is covered in the full SaaS guide.

Cleaning Up Old Records

Activity logs grow fast. The package ships a built-in command that removes records older than the number of days set in config:

php artisan activitylog:clean

Set the retention period in config/activitylog.php:

'delete_records_older_than_days' => 90,

Schedule it in routes/console.php:

Schedule::command('activitylog:clean')->daily();

90 days is a reasonable default for most SaaS products. If you're in a regulated industry (healthcare, finance), you'll want to check your compliance requirements. Some industries mandate 12+ months of audit history.

Migrating from v4

If you're upgrading an existing project, the breaking changes require attention. These are the ones that will actually affect your code:

PHP and Laravel version requirements. v5 requires PHP 8.4+ and Laravel 12+. If you're on older versions, stay on v4 until you've upgraded.

New database column. v5 introduces an attribute_changes column that replaces the old changes column. Create a migration:

Schema::table('activity_log', function (Blueprint $table) {
    $table->json('attribute_changes')->nullable()->after('properties');
});

You'll need to decide what to do with existing changes data. For most teams, archiving the old column and letting new records use attribute_changes is simpler than trying to migrate the data format.

Relation renames. Two relations changed names:

// v4
$user->activity;         // relation to activities caused by this user
$model->activity;        // relation to activities on this model

// v5
$user->actions;          // renamed
$model->activities;      // renamed

Search your codebase for ->activity and update accordingly.

Accessing changes. The changes() method became a property:

// v4
$activity->changes();

// v5
$activity->changes; // or $activity->attribute_changes

Removed config options. table_name and database_connection were removed from the config file. If you need a custom table or connection, create a custom Activity model with $table and $connection properties, then point activity_model in config to that class.

Removed method: addLogChange(), LoggablePipe, and EventLogBag are gone. If you used these to manipulate the changes array, override transformChanges() on a custom LogActivityAction instead; the pattern is shown in the redacting section above.

Before upgrading, check your composer.json for any secondary packages that depend on spatie/laravel-activitylog. This is good practice any time you're doing major version bumps. The auditing your Composer dependencies post covers the workflow.

Testing Your Activity Log

The package ships with a withoutLogs() helper that's useful in tests where you don't want activity logging to interfere:


it('updates a project', function () {
    $project = Project::factory()->create();

    // Disable logging just for this test
    activity()->disableLogging();
    $project->update(['name' => 'Updated Name']);
    activity()->enableLogging();

    expect($project->fresh()->name)->toBe('Updated Name');
    expect(Activity::count())->toBe(0);
});

When you actually want to assert that activity was logged correctly, test it explicitly:

it('logs when a project status changes', function () {
    $user = User::factory()->create();
    $project = Project::factory()->create(['status' => 'draft']);

    actingAs($user);
    $project->update(['status' => 'active']);

    $activity = Activity::latest()->first();

    expect($activity->causer->id)->toBe($user->id)
        ->and($activity->event)->toBe('updated')
        ->and($activity->attribute_changes['attributes']['status'])->toBe('active')
        ->and($activity->attribute_changes['old']['status'])->toBe('draft');
});

Testing the beforeActivityLogged hook works the same way: update the model and assert the custom property was merged onto the activity record. The hook runs synchronously during the model save, so there's no async complexity to deal with in tests.

One thing worth knowing: if you dispatch activity logging via a queued job (using the custom action class pattern), use Queue::fake() in tests and assert the job was dispatched rather than asserting the activity was saved directly.

FAQ

Does v5 work with Laravel 12 and 13?

Yes. The package requires illuminate/support: ^12.0 || ^13.0, so both are supported. Laravel 11 and older are not supported in v5. Stay on v4 if you haven't upgraded yet.

Can I log activity without a logged-in user?

Yes. When there's no authenticated user, causer is null and the log still saves. This is useful for logging background jobs or system-triggered events. You can also set a causer explicitly with causedBy($model).

How do I log soft-deleted models?

The LogsActivity trait hooks into Eloquent model events including SoftDeleting. As long as your model uses SoftDeletes, the activity log records deleted events automatically. Restores are also captured.

Can I use multiple log channels?

Yes. Use useLogName() in getActivitylogOptions() to route activity to different named logs. Then query with Activity::inLog('billing') or Activity::inLog('security'). Useful when you want separate audit trails for different parts of your app.

How do I prevent logging during imports or seeders?

Call activity()->disableLogging() before the operation and activity()->enableLogging() after. This works in tests, seeders, and bulk import scripts anywhere you need a clean run without filling the activity log with noise.

Build It Once, Thank Yourself Later

Audit logs feel optional until the moment they aren't. A team member makes an unexpected change, a user disputes account history, a compliance requirement surfaces. By then it's too late to add the log retroactively.

The good news is that v5 makes the setup surprisingly lightweight. Add the trait, configure what to track, schedule the cleanup command. That's the core of it. Filament display, sensitive field redaction, and queued saves are all additions you can layer in as your needs grow.

If you're setting up activity logging on a production app and want a second set of eyes on the implementation, get in touch.

Laravel Now Has Native Passkeys: A Complete Guide to laravel/passkeys

Hafiz — Sat, 09 May 2026 07:24:25 +0000

For a long time, adding passkeys to a Laravel app meant reaching for a third-party package, assembling WebAuthn ceremonies by hand, or piecing together a tutorial that assumes you already know what a "relying party ID" is. That's done.

In late April 2026, Laravel shipped laravel/passkeys, a first-party package authored by Taylor Otwell that gives you a complete passkey story out of the box. Server package, npm client, Fortify integration. Three pieces that click together so passwordless auth is boring to wire up, which is exactly what you want from a security feature.

I covered the Spatie passkeys approach back in January, and that's still valid if you're Livewire-heavy or already have that package running. But the native package is the right call for new projects and anything using Fortify. Here's the full setup.

What Ships in laravel/passkeys

The passkey stack has three components that each handle a distinct concern.

laravel/passkeys is the server-side Composer package. It handles WebAuthn ceremonies, manages a passkeys database table, registers routes for login, confirmation, and credential management, and fires events you can hook into. If you need custom authorization logic or your own route definitions, escape hatches are built in.

@laravel/passkeys is the npm client. It handles browser-side ceremony coordination (registration and verification) and ships first-class helpers for React, Vue, and Svelte with SSR-safe hooks so client-only APIs don't fight your framework. The public API is two methods: Passkeys.register() and Passkeys.verify(). That's it.

Fortify integration wires everything together via Features::passkeys() in your app config and a passkeys section in config/fortify.php. Fortify apps get the same endpoints and the PasskeyUser and PasskeyAuthenticatable contracts without reimplementing any glue.

The package is v0.1.0 but that's not a red flag. It's already the default in Laravel's official starter kits and used by Fortify in production. The version number signals that the public API may still evolve, not that the package is unstable.

Installation

Start by pulling in the Composer package:

composer require laravel/passkeys

Publish and run the migrations to create the passkeys table:

php artisan vendor:publish --tag=passkeys-migrations
php artisan migrate

Next, add a secret to your .env for deriving stable opaque user handles. This keeps passkey associations private even if your user IDs are sequential integers:

PASSKEYS_USER_HANDLE_SECRET=your-random-secret-here

Generate a value with:

php artisan key:generate --show

Use that output as your secret. The package falls back to APP_KEY if you leave this blank, but keeping them separate is better practice. If you ever rotate your app key, users won't lose their passkeys. You can find a full reference of available artisan commands in the Laravel Artisan Commands reference.

Configuring Your User Model

Add the PasskeyUser contract and PasskeyAuthenticatable trait to your User model:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Passkeys\Contracts\PasskeyUser;
use Laravel\Passkeys\PasskeyAuthenticatable;

class User extends Authenticatable implements PasskeyUser
{
    use PasskeyAuthenticatable;

    // Rest of your model...
}

The trait assumes your users table has name and email columns. Authenticators show these values in their UI during registration and account selection. displayName falls back from name to email to the auth identifier. Same for username.

If you need different display values, override the methods directly on the model:

public function getPasskeyDisplayName(): string
{
    return $this->full_name ?? $this->email;
}

public function getPasskeyUsername(): string
{
    return $this->email;
}

That's the only change your model needs. No extra migrations, no pivot tables. The passkeys table handles credential storage and links to your user via a standard relationship that PasskeyAuthenticatable sets up for you.

Fortify Integration

If you're using Laravel Fortify, enabling passkeys takes one line in your features array:

use Laravel\Fortify\Features;

'features' => [
    Features::registration(),
    Features::resetPasswords(),
    Features::emailVerification(),
    Features::passkeys(), // Add this
],

Fortify automatically registers the passkey routes and wires up the contracts. Nothing else changes on the server side. Your existing authorization setup with policies and gates stays untouched: passkeys only replace the authentication step, not what happens after it.

The Config File

Publish the config if you need to customize anything:

php artisan vendor:publish --tag="passkeys-config"

The defaults in config/passkeys.php are sensible:

return [
    'relying_party_id' => parse_url(config('app.url'), PHP_URL_HOST),
    'allowed_origins' => [config('app.url')],
    'user_handle_secret' => env('PASSKEYS_USER_HANDLE_SECRET', config('app.key')),
    'timeout' => 60000,
    'guard' => 'web',
    'middleware' => ['web'],
    'management_middleware' => ['password.confirm'],
    'throttle' => 'throttle:6,1',
    'redirect' => '/',
];

A few worth understanding before you change anything.

relying_party_id is your domain, derived from APP_URL. Passkeys are cryptographically bound to this value. If the domain the browser accesses doesn't match, the ceremony fails. Make sure APP_URL reflects the actual domain you're serving, especially in local development.

management_middleware defaults to password.confirm, which means users must re-confirm their password before adding or revoking passkeys. Don't disable this. It's the right friction for a security-critical action. The same principle applies here as with sensitive token operations in Passport vs Sanctum.

throttle limits passkey attempts to 6 per minute. Sensible for production. Adjust it if you have unusual traffic patterns, but don't remove it entirely.

Routes the Package Registers

You don't define any routes yourself. The server package registers these automatically:

POST   /passkeys/register/options   (generate registration challenge)
POST   /passkeys/register           (store the new credential)
POST   /passkeys/verify/options     (generate authentication challenge)
POST   /passkeys/verify             (authenticate with passkey)
DELETE /passkeys/{passkey}          (revoke a specific passkey)

If you need custom route definitions (different middleware, prefixes, or custom controllers), you can disable auto-registration in the config and define them yourself. The underlying action classes are all public and importable, so you're not losing functionality by taking manual control.

How the WebAuthn Flow Works

It helps to see the ceremony before writing the frontend code:

Registration follows the same pattern: browser requests options, authenticator creates a key pair, public key gets stored on your server. Nothing sensitive ever leaves the device. The private key never travels over the network, which is the core security advantage over passwords. No credentials to steal from a database breach.

Frontend Integration (Vue)

Install the npm client:

npm install @laravel/passkeys
npm run build

Here's a Vue 3 component that handles both registration (authenticated users adding a passkey) and login (on the login page):

<script setup>
import { ref } from 'vue'
import { Passkeys } from '@laravel/passkeys'

const registering = ref(false)
const verifying = ref(false)
const error = ref(null)

async function registerPasskey() {
    registering.value = true
    error.value = null

    try {
        await Passkeys.register({ name: 'My Device' })
        // Passkey saved, refresh the list or show a success toast
    } catch (e) {
        error.value = e.message
    } finally {
        registering.value = false
    }
}

async function loginWithPasskey() {
    verifying.value = true
    error.value = null

    try {
        await Passkeys.verify()
        // Redirects automatically on success
    } catch (e) {
        error.value = e.message
    } finally {
        verifying.value = false
    }
}
</script>

<template>
    <div class="space-y-4">
        <!-- Show on profile/settings for authenticated users -->
        <button @click="registerPasskey" :disabled="registering" class="btn">
            {{ registering ? 'Registering...' : 'Add a Passkey' }}
        </button>

        <!-- Show on your login page -->
        <button @click="loginWithPasskey" :disabled="verifying" class="btn">
            {{ verifying ? 'Verifying...' : 'Sign in with Passkey' }}
        </button>

        <p v-if="error" class="text-red-500 text-sm">{{ error }}</p>
    </div>
</template>

Passkeys.register() handles the full browser ceremony: it fetches the challenge from /passkeys/register/options, prompts the authenticator, and POSTs the resulting credential back to the server. Passkeys.verify() does the same for login and then redirects to the path defined in config/passkeys.php → redirect on success.

For React, the import and API are identical. The Svelte helpers follow the same pattern. The package abstracts all the @simplewebauthn/browser ceremony complexity behind a clean two-method interface, which is what you want when you're not trying to become a WebAuthn expert.

Managing Registered Passkeys

Users should be able to see and revoke their passkeys. This matters more than people expect. Users register on their laptop, their phone, and their work machine, then wonder why three entries show up. Give them the tools to clean it up.

A basic controller looks like this:

// PasskeyController.php
use Illuminate\Http\Request;
use Laravel\Passkeys\Models\Passkey;

class PasskeyController extends Controller
{
    public function index(Request $request)
    {
        $passkeys = $request->user()->passkeys()->latest()->get();

        return view('passkeys.index', compact('passkeys'));
    }

    public function destroy(Request $request, Passkey $passkey)
    {
        $this->authorize('delete', $passkey);

        $passkey->delete();

        return back()->with('status', 'Passkey removed.');
    }
}

The passkeys() relationship is defined by the PasskeyAuthenticatable trait. Each Passkey record has a name, created_at, and last_used_at column. Surface all three in the UI so users can tell which device is which and spot ones they don't recognise.

Wire the delete action to the DELETE /passkeys/{passkey} route the package already registered. The management_middleware (password confirm by default) protects both the management view and the delete action, so users need to re-authenticate before making changes.

Comparing to spatie/laravel-passkeys

Both packages use web-auth/webauthn-lib under the hood and get you to the same outcome. The difference is approach.

laravel/passkeys (native) is first-party and stack-agnostic on the frontend. Right choice for new Laravel 11, 12, or 13 projects and anything using Fortify. If you're starting fresh, use this.

spatie/laravel-passkeys ships Livewire components out of the box. If your app is already Livewire-heavy and you have Spatie's package working, there's no reason to migrate. The earlier passkeys guide covers that setup in full.

Don't run both at the same time. They register overlapping routes and you'll get conflicts.

Things to Get Right Before You Ship

A few things that will save you a debugging session:

HTTPS is required. WebAuthn only works on secure origins. For local development, use valet secure (Valet or Herd) or configure SSL in Sail. If APP_URL uses http://, the browser refuses to run the ceremony entirely. No error message. Just silence.

Keep password auth as a fallback. Not every user is on a passkey-capable device. Passkeys should be additive. Don't remove your existing login form. Make it an option alongside the passkey button, not a replacement for it.

Account recovery needs thought. If a user loses access to all their registered devices, how do they get back in? The package doesn't solve this. Email-based recovery or admin-initiated password resets are the standard approaches. Build this flow before you go live.

Multiple passkeys per user are supported by default. Users register on multiple devices, and that's expected. Your management UI (a list with a revoke button per passkey) handles this. Show name, created_at, and last_used_at so users can make sense of what's there.

The management_middleware default is password.confirm. Users re-confirm their password before adding or revoking passkeys. Don't strip it out. It's the same security pattern you'd apply to any sensitive account action.

Local Development

One thing that trips people up: APP_URL in .env must match the domain you're actually accessing in the browser. A mismatch makes the relying party check fail, and the error can be cryptic.

APP_URL=https://myapp.test

If you're on Valet:

valet secure myapp

That's all you need. The package reads APP_URL for its relying party config automatically.

FAQ

Does this work on Laravel 11 and 12, or only 13?

The package requires illuminate/contracts: ^11.0|^12.0|^13.0, so all three versions are supported. You don't need to upgrade to Laravel 13 to use it.

Do I need Fortify to use this?

No. Fortify integration is optional. The server package works standalone: you define your own routes and handle redirects. Features::passkeys() just automates the setup if Fortify is already in your stack.

What if I'm already using spatie/laravel-passkeys?

Stay on Spatie unless you have a specific reason to switch, especially if the Livewire setup is working. If you do migrate, uninstall the Spatie package and remove its service provider first. Don't run both simultaneously.

Is v0.1.0 stable enough for production?

The package is already the default in Laravel's official starter kits and backed by Fortify. The v0.1.0 label means the public API may evolve, not that it's experimental. For new projects, use it without hesitation.

Can I use this without a JavaScript framework?

Yes. The framework-specific helpers (Vue, React, Svelte) are convenience wrappers around the same core API. If you're using Blade without a frontend framework, you can call Passkeys.register() and Passkeys.verify() from a plain <script> block after importing @laravel/passkeys.

Get It Wired Up

Native passkeys is a small, focused addition to any Laravel project. The config is sensible by default, Fortify integration is a single line, and the frontend API is two method calls. If you're starting a new Laravel project today and want passwordless auth, this is the path.

If you're adding passkeys to an existing production app or migrating a complex auth setup, get in touch and we can work through the integration together.

PHP 8.4 Features You're Probably Not Using Yet in Your Laravel App

Hafiz — Fri, 08 May 2026 05:21:57 +0000

If you followed the Laravel 13 upgrade path, you're running PHP 8.4 by now (or you should be, since Laravel 13.3+ pulls in Symfony 8 components that require it). The upgrade guide covers the migration steps, but upgrading your runtime and actually using the new language features are two different things.

Most Laravel developers upgrade PHP, confirm their tests pass, and keep writing the same PHP 8.1-style code they've always written. That works, but you're leaving real improvements on the table. PHP 8.4 shipped six features that directly clean up the kind of code you write in a Laravel app every day.

Here's what each one does, with before and after examples.

1. Property Hooks: Replace Your Getters and Setters

Property hooks let you define get and set behavior directly on a class property. No more writing separate getter and setter methods for simple transformations.

Before (PHP 8.3):

class PriceCalculator
{
    private float $priceInCents;

    public function getPriceInCents(): float
    {
        return $this->priceInCents;
    }

    public function setPriceInCents(float $value): void
    {
        if ($value < 0) {
            throw new \InvalidArgumentException('Price cannot be negative.');
        }
        $this->priceInCents = $value;
    }

    public function getPriceInDollars(): float
    {
        return $this->priceInCents / 100;
    }
}

After (PHP 8.4):

class PriceCalculator
{
    public float $priceInCents {
        set {
            if ($value < 0) {
                throw new \InvalidArgumentException('Price cannot be negative.');
            }
            $this->priceInCents = $value;
        }
    }

    public float $priceInDollars {
        get => $this->priceInCents / 100;
    }
}

The $priceInDollars property is virtual. It doesn't store anything. It computes the value on read from $priceInCents. And the set hook on $priceInCents validates the input without a separate method.

Where this shines in Laravel: service classes, value objects, and DTOs where you'd normally write getters with transformation logic. Note that Eloquent models have their own accessor/mutator system via Attribute::make(), so property hooks don't replace those directly. But for any non-Eloquent class in your app (and you should have plenty), property hooks remove a lot of boilerplate.

2. Asymmetric Visibility: Public Read, Private Write

Before PHP 8.4, if you wanted a property that anyone could read but only the class itself could modify, you had two options: make it private and add a getter, or make it readonly. Both had tradeoffs. readonly can only be set once, which doesn't work if the value changes over the object's lifetime.

Asymmetric visibility solves this cleanly:

Before (PHP 8.3):

class OrderStatus
{
    private string $status = 'pending';

    public function getStatus(): string
    {
        return $this->status;
    }

    public function markAsShipped(): void
    {
        $this->status = 'shipped';
    }
}

// Usage
$order->getStatus(); // 'pending'

After (PHP 8.4):

class OrderStatus
{
    public private(set) string $status = 'pending';

    public function markAsShipped(): void
    {
        $this->status = 'shipped';
    }
}

// Usage
$order->status; // 'pending' - direct access, no getter needed
$order->status = 'cancelled'; // Error: Cannot modify private(set) property

The public private(set) declaration means: anyone can read $status directly, but only the class itself can change it. No getter needed. No readonly restriction. The value can change internally through methods like markAsShipped(), but external code can't tamper with it.

This is ideal for data transfer objects in your Laravel app. API response DTOs (especially if you're following REST API best practices), configuration objects, form data objects. Anywhere you want external code to read properties directly without letting them modify the state.

You can also use public protected(set) to allow child classes to modify the property while keeping external write access restricted.

3. array_find(): Stop Filtering When You Only Need One

PHP has had array_filter() forever, but if you only need the first element that matches a condition, you've been writing this:

Before (PHP 8.3):

$users = [
    ['name' => 'Alice', 'role' => 'admin'],
    ['name' => 'Bob', 'role' => 'editor'],
    ['name' => 'Charlie', 'role' => 'admin'],
];

$firstAdmin = array_values(array_filter(
    $users,
    fn ($user) => $user['role'] === 'admin'
))[0] ?? null;

That's ugly. array_filter processes the entire array, array_values re-indexes it, and the [0] ?? null handles the empty case. Three operations for something that should be one line.

After (PHP 8.4):

$firstAdmin = array_find($users, fn ($user) => $user['role'] === 'admin');

array_find() returns the first matching element and stops iterating. No re-indexing, no null coalescing. If nothing matches, it returns null.

PHP 8.4 also adds three related functions:

array_find_key() returns the key of the first match instead of the value
array_any() returns true if at least one element matches (like Collection::contains() for arrays)
array_all() returns true if every element matches (like Collection::every() for arrays)

In Laravel, you'll mostly use these in places where you're working with raw arrays instead of collections: config processing, middleware logic, job payloads, or anywhere performance matters and you don't want to create a Collection instance just to call ->first().

4. The #[\Deprecated] Attribute

PHP has always had a way to deprecate built-in functions, but there was no native mechanism for marking your own functions, methods, or class constants as deprecated. You'd either put a @deprecated docblock comment (which only IDE-level tools read) or throw a manual trigger_error().

Before (PHP 8.3):

/**
 * @deprecated Use calculateTotal() instead
 */
function calculateSubtotal(array $items): float
{
    trigger_error('calculateSubtotal() is deprecated, use calculateTotal()', E_USER_DEPRECATED);
    return calculateTotal($items);
}

After (PHP 8.4):

#[\Deprecated(message: 'Use calculateTotal() instead', since: '2.0')]
function calculateSubtotal(array $items): float
{
    return calculateTotal($items);
}

The #[\Deprecated] attribute triggers a real E_USER_DEPRECATED notice when the function is called. IDEs like PhpStorm show it with a strikethrough. Static analysis tools like PHPStan and Larastan flag it automatically. And you get a since parameter to track when the deprecation started.

Where this helps in Laravel: if you maintain internal packages, APIs with versioned endpoints, or shared service classes across teams, this is a cleaner way to signal "stop using this" than a docblock that nobody reads.

5. Method Chaining on new Without Parentheses

A small quality-of-life improvement that removes an annoying syntax limitation:

Before (PHP 8.3):

$date = (new DateTime())->format('Y-m-d');
$response = (new JsonResponse($data))->setStatusCode(201);

Those extra parentheses around new ClassName() were required to chain a method call. They look awkward and trip up developers who forget them.

After (PHP 8.4):

$date = new DateTime()->format('Y-m-d');
$response = new JsonResponse($data)->setStatusCode(201);

No wrapping parentheses needed. You can also access properties directly: new Foo()->bar. This is a small change, but it cleans up code in places where you create and immediately use throwaway objects, which happens often in tests, seeders, and one-off scripts.

6. Multibyte String Functions: trim, ltrim, rtrim

PHP finally has multibyte-aware trim functions. If your app handles content in languages like Japanese, Chinese, Arabic, or Korean, you've probably been using workarounds with preg_replace to trim multibyte whitespace characters that trim() ignores.

Before (PHP 8.3):

// Standard trim doesn't handle multibyte whitespace like \u{3000} (ideographic space)
$cleaned = preg_replace('/^\s+|\s+$/u', '', $input);

After (PHP 8.4):

$cleaned = mb_trim($input);

PHP 8.4 adds mb_trim(), mb_ltrim(), and mb_rtrim(). If your Laravel app processes user input from a multilingual audience, these are a direct improvement. Use them in your form request prepareForValidation() methods or in custom Eloquent casts where you clean input before storage.

When to Start Using These

You don't need to refactor your entire codebase. The practical approach:

Use immediately in new code. When you write a new service class, DTO, or value object, use property hooks and asymmetric visibility instead of getters/setters. When you write a new array operation on raw data, reach for array_find() before array_filter().

Refactor gradually. When you touch an existing class for a feature or bug fix, modernize it if it takes less than five minutes. Don't create refactoring PRs that touch 50 files. That's risk for no product value.

Don't touch Eloquent models. Eloquent has its own accessor/mutator system that doesn't need property hooks. And asymmetric visibility conflicts with how Eloquent hydrates properties. Keep Eloquent models using Laravel's patterns.

FAQ

Do property hooks work with Eloquent models?

Not in the way you might expect. Eloquent uses dynamic property access via __get and __set, which doesn't interact cleanly with PHP property hooks. Stick with Eloquent's Attribute::make() for model accessors and mutators. Use property hooks in your service classes, DTOs, form data objects, and other non-Eloquent classes.

Can I use asymmetric visibility with constructor promotion?

Yes. public private(set) string $name works in constructor parameters:

public function __construct(
    public private(set) string $name,
    public protected(set) int $age,
) {}

This gives you a publicly readable, internally writable promoted property in one line.

Do I need to upgrade PHPStan or Larastan for PHP 8.4 features?

PHPStan 2.1+ fully supports property hooks, asymmetric visibility, and the #[\Deprecated] attribute. If you're running an older version, upgrade before adopting these features, otherwise your CI pipeline will flag false positives. Larastan follows PHPStan's version, so updating Larastan pulls in the PHP 8.4 support automatically. If you're also upgrading your testing setup to Pest 4, do both at the same time.

What's the minimum PHP 8.4 version I should run?

PHP 8.4.1 or later. The 8.4.0 release had a few edge-case bugs with property hooks in certain inheritance scenarios that were fixed in 8.4.1. If you're deploying to production, start with the latest 8.4.x patch.

What's Next

PHP 8.4 isn't a small release. Property hooks and asymmetric visibility change how you structure classes in a fundamental way. The new array functions remove patterns you've been copy-pasting for years. And the #[\Deprecated] attribute gives you a tool that PHP itself has had forever but never shared with userland code.

If you haven't upgraded yet, the 4 composer conflicts post walks you through the blockers you'll hit on the way to PHP 8.4 and Laravel 13. And if you're building something with Laravel and want help modernizing your codebase for PHP 8.4, get in touch.

The 4 Composer Conflicts That Block Most Laravel 13 Upgrades (And How to Find Yours)

Hafiz — Wed, 06 May 2026 05:12:23 +0000

Most Laravel apps don't fail upgrades because of breaking changes. They fail because composer update throws a wall of red text and the developer closes the terminal.

Laravel 13 shipped with "zero breaking changes" to application code. That's true. Your routes, controllers, and Eloquent models don't need touching. But your composer.json is a different story. Somewhere in your 30-50 dependencies, there's almost certainly a version constraint that won't resolve against laravel/framework:^13.0. And finding it manually means running composer why-not, reading cryptic output, fixing one conflict, discovering the next, and repeating until you either succeed or give up and decide to "upgrade later."

Four specific conflicts catch most developers. After looking at how these surface in real composer.json files, in GitHub issues, and in r/laravel threads, the same patterns keep showing up. Here's what each one looks like, why it happens, and how to fix it.

1. Your PHP Constraint Is Too Loose

This is the most common blocker and the easiest to miss. Your composer.json probably says something like this:

"require": {
    "php": "^8.1"
}

Laravel 13 requires PHP 8.3 as the minimum. That constraint above technically allows 8.1, 8.2, 8.3, and 8.4. Two things can go wrong here.

First, if your server actually runs PHP 8.2, Composer will refuse to install Laravel 13 regardless of what your composer.json says. The error looks like this:

Your requirements could not be resolved to an installable set of packages.

Problem 1
  - laravel/framework v13.0.0 requires php ^8.3 -> your php version (8.2.28)
    does not satisfy that requirement.

Second, even if your server runs 8.3, a loose constraint like ^8.1 means your app could be deployed on 8.1 or 8.2, where Laravel 13 won't work. Tightening the constraint protects you from that.

The fix: Run php -v on production first. If it returns anything below 8.3, upgrade PHP before touching Composer. Then tighten your constraint to match:

"require": {
    "php": "^8.3"
}

Don't skip this. Every other fix in this post is pointless if your PHP version is too low.

2. The Symfony 8 Surprise

This one is newer and won't hit you on day one. Laravel 13.0 through 13.2 work fine on PHP 8.3. But starting with Laravel 13.3, the framework allows Symfony 8 components (symfony/error-handler, symfony/console) that require PHP 8.4.

If you're on PHP 8.3 and you run composer update after the initial upgrade, you might get hit by this weeks later:

Problem 1
  - laravel/framework v13.3.0 requires symfony/error-handler ^7.4.0 || ^8.0.0
    -> satisfiable by symfony/error-handler[v8.0.8].
  - symfony/error-handler v8.0.8 requires php >=8.4
    -> your php version (8.3.30) does not satisfy that requirement.

The fix: You have two options. Either upgrade to PHP 8.4 (the better long-term choice), or pin Symfony to 7.4 in your composer.json:

composer require symfony/console:"^7.4" symfony/error-handler:"^7.4"

This keeps you on Symfony 7.4 while running Laravel 13.3+. It works, but it's a temporary workaround. PHP 8.4 is where you want to be.

If you're reading the full Laravel 13 upgrade guide, this particular conflict isn't covered there because it appeared after the initial release. It's exactly the kind of thing that catches you between "I upgraded successfully" and "why is production broken after composer update?"

3. Spatie Packages Pinned to Old Major Versions

If you use any Spatie packages (and most Laravel apps do), check their version constraints carefully. Older major versions often don't support Laravel 13. The most common offenders:

spatie/laravel-permission v5 doesn't support Laravel 13. You need at least v6.
spatie/laravel-medialibrary older major versions don't support Laravel 13. Check your installed version against the latest release.
spatie/laravel-activitylog requires at least v4.12 for Laravel 13 support. Earlier v4 releases won't resolve.

The error looks like a typical version mismatch:

Problem 1
  - spatie/laravel-permission v5.11.1 requires illuminate/database ^9.0|^10.0|^11.0|^12.0
    -> found illuminate/database v13.0.0 but it does not match ^9.0|^10.0|^11.0|^12.0.

The fix: Upgrade each Spatie package to the latest major version before upgrading Laravel. Check the GitHub releases page for each one. Most have migration guides. Spatie generally ships Laravel support within days of a new release, and they've even backported Laravel 13 compatibility to some older branches so third-party packages have time to catch up.

One tip: run composer outdated --major to see which packages have major version jumps available. That command shows you the gap without trying to resolve anything.

4. Testing Packages That Quietly Block Everything

PHPUnit and Pest are required by almost every Laravel app, but they sit in require-dev and tend to get ignored during upgrades. They shouldn't be.

Laravel 13 requires phpunit/phpunit:^11.5.50 or ^12.0. If your composer.json still has "phpunit/phpunit": "^10.0", that's a blocker. Same with Pest: you need at least Pest 3.8.5 for Laravel 13 support (earlier 3.x releases pin a PHPUnit version that's too low).

The error often looks something like this, showing up in require-dev where some developers skip reading:

Problem 1
  - phpunit/phpunit 10.5.46 requires sebastian/comparator ^5.0
    -> found sebastian/comparator 6.3.1 but it does not match ^5.0.

That's PHPUnit 10 conflicting with a transitive dependency that Laravel 13's newer Symfony components pull in. It's not obvious at all from the error message.

The fix: Update your testing packages first:

composer require --dev phpunit/phpunit:^12.0

# Or if you use Pest:
composer require --dev pestphp/pest:^3.0

If you've been putting off the Pest 4 migration, now is the time. Pest 4 ships with full Laravel 13 support and a cleaner API.

Or Skip All of This

Every conflict above follows the same pattern: something in your composer.json doesn't match what Laravel 13 expects, and finding it requires running commands, reading error output, and debugging one conflict at a time.

There's a faster way. Paste your composer.json into the Laravel Upgrade Analyzer and it'll show you exactly which dependencies need attention. It checks 33 packages (including PHP version, Symfony components, and testing tools) against Laravel 13's requirements and flags each one as Blocker (stops the upgrade entirely), Breaking (needs a major version bump), or Watch (minor bump, low risk). The whole thing takes about 5 seconds and nothing gets stored.

If you went through the Laravel 12 to 13 upgrade guide and already upgraded, the analyzer still catches stale package versions and constraint mismatches you might have missed.

And if you don't want to deal with any of this yourself, I do Laravel upgrades. Send me your composer.json and I'll scope it.

FAQ

Does the Upgrade Analyzer work for older upgrades like Laravel 11 to 12?

Right now it's focused on Laravel 13 specifically. The rules check PHP version requirements, first-party Laravel packages, and 33 of the most common third-party packages against Laravel 13 compatibility. Support for older upgrade paths may come later.

What if one of my packages isn't in the analyzer's rules?

The analyzer covers 33 packages (25 auto-derived from Packagist, 8 hand-curated). If your package isn't covered, you can check manually by running composer why-not laravel/framework:^13.0 or checking the package's GitHub releases for Laravel 13 support. Found a package that should be included? Let me know and I'll add it.

Is my composer.json stored or shared?

No. The analyzer processes your file server-side and discards it immediately. Nothing is stored, logged, or shared. You can verify this in the page footer.