Forem: Hafiz

Generate Beautiful Open Graph Images for Your Laravel App with One Spatie Package

Hafiz — Mon, 27 Apr 2026 05:22:10 +0000

When someone shares a link to your Laravel app on Twitter, LinkedIn, or Slack, the platform shows a preview image. That image is the Open Graph image. Most Laravel apps either ship without one, ship with the same generic image on every page, or rely on an external service like Cloudinary or a separate Node.js renderer.

Spatie released laravel-og-image to solve this in a way that feels native to Laravel: define your OG image as HTML right inside your Blade views, let the package screenshot it, cache it, and serve it automatically. No external API. No separate CSS pipeline. No extra app.

This is the practical walkthrough I wish I had when I first looked at it. Real-world setup, the gotchas, and the Cloudflare alternative for Forge users without Chromium.

Why this package matters

Most Laravel developers I know fall into one of three buckets when it comes to OG images. They have a single static image used across every page. Or they generate images server-side using something like Browsershot directly, which works but means rebuilding the wheel every project. Or they use an external service which adds latency, cost, and another dependency to monitor.

laravel-og-image is the Laravel-native solution. The killer feature: your OG image template lives on the actual page, so it inherits your existing Tailwind classes, fonts, and Vite assets. No separate stylesheet. No design system duplication. Whatever your site looks like, your OG images can match without effort.

The pattern is borrowed from OGKit by Peter Suhm, but where OGKit is a hosted service, laravel-og-image runs entirely on your own server. Spatie also built it on top of their laravel-screenshot package, which means you can swap drivers between Browsershot (local Chromium) and Cloudflare Browser Rendering depending on your infrastructure.

How it actually works

The mental model is worth getting straight before you install anything. Here's the flow when a social platform crawls one of your pages:

Six steps that matter:

You drop an <x-og-image> Blade component into your view with whatever HTML you want.
The package renders that HTML inside a hidden <template data-og-image> tag on the page. It's invisible to humans.
Middleware automatically injects og:image, twitter:image, and twitter:card meta tags into your <head>.
The image URL contains an md5 hash of your HTML content. Change the content, hash changes, crawlers pick up the new image.
When the image URL is first requested, the package visits your page with ?ogimage appended. This renders only the template content at 1200×630 with your full CSS available.
The screenshot is saved to your public disk and served with Cache-Control headers. Cloudflare or your CDN caches it from there.

That last point matters more than it sounds. Image generation only happens once per unique HTML content. After that you're serving a static JPEG with proper cache headers.

Setting it up on a Laravel app

You need PHP 8.3+, Laravel 12+, and either Node.js with Chromium installed (for the default Browsershot driver) or a Cloudflare account with Browser Rendering enabled.

Install the package (full docs are on Spatie's documentation site):

composer require spatie/laravel-og-image

The package depends on spatie/laravel-screenshot, which depends on Browsershot, which needs Node.js and Chrome/Chromium on the server. If you're on Laravel Forge with a standard Ubuntu droplet, you'll need to install these. On Laravel Cloud, the Browsershot driver isn't an option and you'll need the Cloudflare driver instead (covered below).

Optionally publish the config file if you need to customize defaults:

php artisan vendor:publish --tag="og-image-config"

That's the entire setup. The middleware that injects meta tags registers automatically.

Your first OG image

Open any Blade view that you want to add an OG image to. For a Laravel blog, that's typically resources/views/blog/show.blade.php, the single-post view. Drop in the component:

<x-og-image>
    <div class="w-full h-full bg-slate-900 text-white flex flex-col justify-between p-16">
        <div class="flex items-center gap-4">
            <img src="{{ asset('logo.svg') }}" class="w-16 h-16" alt="hafiz.dev">
            <span class="text-2xl font-semibold">hafiz.dev</span>
        </div>

        <h1 class="text-7xl font-bold leading-tight">
            {{ $post->title }}
        </h1>

        <div class="flex items-center justify-between text-2xl text-slate-400">
            <span>By Hafiz Riaz</span>
            <span>{{ $post->published_at->format('M j, Y') }}</span>
        </div>
    </div>
</x-og-image>

That's it. Refresh the page in your browser and view source. You'll see the package has injected meta tags into your head:

<meta property="og:image" content="https://hafiz.dev/og-image/a3f8c2d1e9b4.jpeg">
<meta property="twitter:image" content="https://hafiz.dev/og-image/a3f8c2d1e9b4.jpeg">
<meta property="twitter:card" content="summary_large_image">

If your page already had OG meta tags from a layout file, remove the og:image, twitter:image, and twitter:card ones. The package handles those automatically. Keep your og:title, og:description, og:type, and any other OG tags. The package only manages the image-related ones.

Previewing without sharing the link 100 times

The most useful debugging tool in this package is the ?ogimage query parameter. Append it to any page URL and you'll see exactly what gets screenshotted, at the configured dimensions, with the page's full CSS:

https://hafiz.dev/blog/your-post-slug?ogimage

This loads in your browser as a 1200×630 viewport showing only your template content. You can iterate on the design directly here, watching it update as you tweak the Blade template. No need to actually fire the screenshot or share the URL on Twitter to see what it looks like.

Design tips that took me too long to learn

A few things I wasted time on that you can skip:

Use w-full h-full on your root element. The template renders inside a 1200×630 viewport. If you don't fill it, you'll get whitespace around your design. This is the most common mistake.

Keep text huge. OG images are viewed as thumbnails on most platforms, often around 500px wide on a phone. Your 7xl Tailwind text becomes legible. Anything smaller than 4xl is hard to read. Test at the actual rendered size before shipping.

Stick to your existing brand. Because the template inherits all your CSS, you can use your existing color tokens, fonts, and components. Don't redesign. Use what's already there.

Avoid background images that load externally. Browsershot waits for network idle by default, but external images add latency. Use solid colors, gradients, or assets served from the same domain. SVG inline is best.

Test in the LinkedIn Post Inspector and Twitter Card Validator before publishing widely. Both have rate limits but they're free. Cache busting on social platforms is a separate problem if you ship a bad image.

Using a Blade view instead of inline HTML

If you want the same OG layout across many pages, or if the template is getting complex, reference a Blade view instead:

<x-og-image view="og-image.post" :data="['title' => $post->title, 'author' => $post->author->name]" />

Then in resources/views/og-image/post.blade.php:

<div class="w-full h-full bg-slate-900 text-white flex flex-col justify-between p-16">
    <h1 class="text-7xl font-bold">{{ $title }}</h1>
    <div class="text-2xl text-slate-400">by {{ $author }}</div>
</div>

The data array becomes the variables available in the view. This pattern is what I'd reach for if you have multiple post types or you want OG images on a documentation site with consistent branding.

Fallback images for pages without templates

What about pages that don't have an explicit <x-og-image> component? Blog index pages, tag listings, your homepage. By default, those pages get no OG image at all. The package lets you define a fallback in your AppServiceProvider:

use Illuminate\Http\Request;
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::fallbackUsing(function (Request $request) {
        return view('og-image.fallback', [
            'title' => config('app.name'),
            'tagline' => 'Laravel, Claude Code, and shipping fast',
        ]);
    });
}

The closure receives the full Request, so you can use route parameters or model bindings to customize the fallback per URL. Return null to skip the fallback for specific requests. Pages that have an explicit component are never affected.

The Cloudflare driver: when you can't run Chromium

If you're on Laravel Cloud, a serverless platform, or you just don't want to install Chromium on your server, the Cloudflare driver is the answer. It uses Cloudflare's Browser Rendering API to take the screenshot remotely.

To switch to it, configure the screenshot driver in config/screenshot.php after publishing the screenshot config:

'default' => env('SCREENSHOT_DRIVER', 'cloudflare'),

'drivers' => [
    'cloudflare' => [
        'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
        'api_token' => env('CLOUDFLARE_API_TOKEN'),
    ],
],

Then add the Cloudflare credentials to your .env:

SCREENSHOT_DRIVER=cloudflare
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-api-token

Cloudflare's Browser Rendering API has a free tier that's generous enough for most blogs and small SaaS apps. The latency is slightly higher than local Chromium because of the round-trip, but the trade-off is no Chromium dependency on your server.

If you're already on Cloudflare for DNS or CDN, this driver is the path of least resistance.

Pre-generating images so the first share never lags

The first time the OG image URL is hit, the package generates the screenshot. That can take a few seconds, especially with the Cloudflare driver. If you tweet a link to a brand new post, the first crawler might time out before the image is ready.

The fix is to pre-generate the image when the page is published:

use Spatie\OgImage\Facades\OgImage;

class PublishPostAction
{
    public function execute(Post $post): void
    {
        $post->update(['published_at' => now()]);

        dispatch(function () use ($post) {
            OgImage::generateForUrl($post->url);
        });
    }
}

This dispatches a job that generates the image after publishing. By the time anyone shares the URL, the image is already cached on disk. If you're using Laravel Queue Jobs at scale, this slots into your existing queue infrastructure cleanly.

Caching, storage, and clearing old images

By default, generated images are stored on the public disk, served from /og-image/{hash}.jpeg. The hash changes when the underlying HTML changes, so updates work automatically. But that means old images stay on disk forever unless you clean them up.

The package includes an artisan command to clear them:

php artisan og-image:clear

You can find this and the other Artisan commands the package adds in your standard php artisan list output. I run the clear command monthly via the scheduler. The cost of stale images is minimal for a small blog, but if you're running a SaaS with thousands of dynamic pages, regular cleanup keeps your disk under control.

For storage on S3 or another disk, configure it via the facade in AppServiceProvider:

use Spatie\OgImage\Facades\OgImage;

OgImage::format('webp')
    ->size(1200, 630)
    ->disk('s3', 'og-images');

WebP gives smaller file sizes if your CDN supports it. JPEG is the safer default for older crawlers.

When this package isn't the right tool

A few cases where I'd reach for something else:

Static images suffice. If your app has a single OG image used everywhere and it never needs to change, Spatie's package is overkill. Just use a static asset and reference it in your layout.

You need pixel-perfect control over fonts and rendering. Browsershot uses headless Chromium, which is great but not identical to Photoshop. If your design team wants exact rendering parity, generate images in Figma or use a service like Bannerbear.

You're on a free Laravel Cloud tier with strict timeouts. The first generation can be slow. Use the Cloudflare driver and pre-generate aggressively, or fall back to a static image.

You don't have control over the page layout. The package needs to inject meta tags into your <head> and a template into the body. If you're working inside an iframe or a constrained CMS where you can't control these, this won't work.

For everyone else building a Laravel app where shareable URLs matter, this is the right tool.

FAQ

Does this work with Laravel Cloud?

Yes, but only with the Cloudflare driver. Laravel Cloud doesn't include Chromium, so the default Browsershot driver won't work out of the box. Set up Cloudflare Browser Rendering, point the screenshot driver at it, and you're good. Pre-generation via queue jobs is also fine on Laravel Cloud.

How do I make sure social platforms pick up the new image when I update a post?

The image URL contains a hash of your template HTML. When you change the HTML (like updating a post title), the hash changes, so the URL changes, and crawlers fetch the new image automatically. The catch is that platforms like Facebook and LinkedIn cache aggressively. Use their respective debug tools to force a refresh: Facebook Sharing Debugger and LinkedIn Post Inspector.

Can I have different OG images for different page sections without writing custom logic?

Yes. Just place a different <x-og-image> component in each Blade view. Each one generates its own image based on its HTML content. For pages without an explicit component, use the fallback closure to define page-specific defaults based on the request URL or route name.

What happens if Browsershot fails to generate the image?

The package logs the error and the meta tag URL still points to the path it would have been served from. The crawler gets a 404 or 500 response on the image URL. The page itself still loads fine. To handle this gracefully, monitor the og-image queue and alert on failures. If you're using a Laravel monitoring tool like Pulse or Nightwatch, watch for failed jobs related to image generation.

Does this affect page load performance?

No. The component renders an empty hidden <template> tag in your HTML, which adds a few hundred bytes at most. The actual image generation happens out-of-band when the OG URL is requested by a crawler, not when a user loads your page. Your page weight is essentially unchanged.

Conclusion

The whole setup takes about 30 minutes from composer require to a working OG image, including some design iteration. The package does exactly what it advertises, the documentation is solid, and the Cloudflare driver makes it usable on platforms where Chromium isn't an option.

If you're shipping a Laravel app where shareable URLs matter, blog posts, product pages, documentation, this is one of those packages that pays for itself the first time someone retweets your link. Set it up once, design the template once, never think about OG images again.

Building something in Laravel where the marketing layer needs to actually work? Let's talk.

Claude Opus 4.7: What Laravel AI SDK Developers Need to Check Before Upgrading

Hafiz — Fri, 24 Apr 2026 05:44:46 +0000

Claude Opus 4.7 dropped on April 16, 2026. If you're using the Laravel AI SDK with the Anthropic driver, there are breaking API changes that will throw 400 errors in your existing setup the moment you swap the model string. Not deprecation warnings. Not behavior shifts. Actual request failures.

This isn't a "what's new" roundup. It's a migration guide for Laravel developers who already have Anthropic agents in production and want to know exactly what to touch before flipping the switch.

The model string and pricing

Start with the easy bit. The API model ID is claude-opus-4-7. In your Laravel AI SDK agent, that's one line:

#[Provider(Lab::Anthropic)]
#[Model('claude-opus-4-7')]  // was: 'claude-opus-4-6'
class YourAgent implements Agent
{
    use Promptable;
}

Pricing is unchanged from Opus 4.6: $5 per million input tokens, $25 per million output. That said, keep reading before you celebrate, because the new tokenizer changes the effective cost even though the per-token rate didn't.

The three breaking changes that will actually bite you

These apply to the Messages API. If you're using Claude Managed Agents, Anthropic says no breaking API changes are required beyond the model name. But the Laravel AI SDK talks to the Messages API under the hood, so you're affected.

1. The `#[Temperature]` attribute breaks on Opus 4.7

This is the one that will catch most Laravel AI SDK users off guard.

Starting with Opus 4.7, setting temperature, top_p, or top_k to any non-default value returns a 400 error. Not a warning. A hard failure.

The Laravel AI SDK's #[Temperature] attribute passes that value directly to the Anthropic API. So this:

#[Provider(Lab::Anthropic)]
#[Model('claude-opus-4-7')]
#[Temperature(0.7)]  // This will throw a 400 error
class YourAgent implements Agent
{
    use Promptable;
}

Will fail at runtime. The fix is to remove the attribute entirely when using Opus 4.7 with the Anthropic driver:

#[Provider(Lab::Anthropic)]
#[Model('claude-opus-4-7')]
// No #[Temperature] - Anthropic controls this internally on Opus 4.7
class YourAgent implements Agent
{
    use Promptable;
}

Same applies to any code that passes temperature directly through the SDK's fluent interface when calling Anthropic. Omit it.

If you were using temperature: 0 for determinism, note that this never actually guaranteed identical outputs on previous models either. Opus 4.7 just makes it explicit by refusing the parameter.

2. Extended thinking is gone, swap it for adaptive thinking

If you have any agents that used thinking: {type: "enabled", budget_tokens: N}, that now returns a 400 error as well.

Opus 4.7 replaces extended thinking with adaptive thinking. The model decides how much to think based on the task's complexity, guided by the effort level you set. You don't allocate a token budget manually anymore.

For the Anthropic PHP SDK directly, the before/after looks like this:

// Before (Opus 4.6)
$response = $client->messages()->create([
    'model'      => 'claude-opus-4-6',
    'max_tokens' => 64000,
    'thinking'   => ['type' => 'enabled', 'budget_tokens' => 32000],
    'messages'   => [['role' => 'user', 'content' => $prompt]],
]);

// After (Opus 4.7)
$response = $client->messages()->create([
    'model'         => 'claude-opus-4-7',
    'max_tokens'    => 64000,
    'thinking'      => ['type' => 'adaptive'],
    'output_config' => ['effort' => 'high'],
    'messages'      => [['role' => 'user', 'content' => $prompt]],
]);

Adaptive thinking is off by default on Opus 4.7. If you don't set thinking: {type: "adaptive"} explicitly, the model runs without thinking, matching Opus 4.6's default behavior when no thinking was configured. Enable it explicitly when you want it.

3. Thinking content is silently omitted

This one doesn't throw an error, but it can cause a subtle bug if your agent streams reasoning to users or logs thinking blocks.

On Opus 4.7, thinking blocks still appear in the response stream, but their thinking field is empty by default. The previous default was to return summarized thinking text. If you have frontend code or logging that reads reasoning content from the response, it will now receive an empty string without any error telling you why.

To restore visible reasoning, opt in explicitly:

'thinking' => [
    'type'    => 'adaptive',
    'display' => 'summarized',  // default is 'omitted'
],

If you're streaming responses and your UI shows a long pause before output starts, this is the cause. The model is thinking but not emitting visible progress. Set display: 'summarized' and the progress comes back.

The tokenizer change: your bill may go up

Opus 4.7 uses a new tokenizer. The same text now tokenizes to roughly 1x to 1.35x as many tokens as it did on Opus 4.6, varying by content. The per-token price didn't change. The token count for the same input did.

On a small single-turn prompt this is negligible. For multi-turn conversations, long system prompts, or agentic loops with large tool results, the compounding effect is real. A workflow that cost $10/day on Opus 4.6 could cost up to $13.50/day on Opus 4.7 without changing a single line of prompt.

Anthropic recommends updating your max_tokens to give extra headroom, including any context compaction triggers you have set. The 1M context window is unchanged and comes with no long-context premium.

Run your common prompts through /v1/messages/count_tokens on claude-opus-4-7 before and after to see your actual multiplier. It varies by content type, and code-heavy prompts tend to tokenize differently than prose. Dense PHP files and long Blade templates may be closer to the 1.35x ceiling, while short conversational messages sit nearer 1x. Check before you ship.

New features worth actually using

The `xhigh` effort level

Opus 4.7 adds xhigh as a new effort level above high. Anthropic recommends starting with xhigh for coding and agentic use cases, and a minimum of high for most intelligence-sensitive tasks. Lower effort levels (medium, low) trade quality for speed and cost.

This matters practically for the kind of agents covered in the multi-agent patterns post. A research agent that runs for several minutes benefits from xhigh. A quick classification call doesn't need more than medium.

The effort parameter is Messages API only. Claude Managed Agents handles effort automatically.

Task budgets for long agentic loops

This is worth knowing for anyone building workflows like the RAG support bot in part two of the AI SDK tutorial.

A task budget is an advisory token cap across the entire agentic loop, not per request. The model sees a running countdown and uses it to scope and prioritize work. It's distinct from max_tokens, which is a hard per-request cap the model never sees.

// Task budgets require the beta header + output_config
$response = $client->beta()->messages()->create([
    'model'         => 'claude-opus-4-7',
    'max_tokens'    => 128000,
    'output_config' => [
        'effort'      => 'high',
        'task_budget' => ['type' => 'tokens', 'total' => 128000],
    ],
    'messages'      => [['role' => 'user', 'content' => $prompt]],
    'betas'         => ['task-budgets-2026-03-13'],
]);

Use task budgets when you need the model to self-moderate on a token allowance. Skip them for open-ended quality-first tasks where you don't care about scoping. The minimum value is 20k tokens.

High-resolution image support

If your agent processes screenshots, documents, or charts, this matters. Max image resolution went from 1568px to 2576px on the long edge. That's a jump from 1.15MP to 3.75MP. Coordinate mapping is now 1:1 with actual pixels, so no more scale-factor math when using computer use workflows.

High-res images use more tokens though. If you're sending images where the extra detail isn't needed, downsample before sending to avoid unnecessary token cost.

Behavior changes that might need prompt updates

These aren't breaking changes, but they can make existing prompts behave differently.

More literal instruction following. Opus 4.7 will not silently generalize an instruction from one item to another. If your prompt says "summarize the first document," it won't infer you also want the second one summarized. This is actually a net positive for structured workflows, but you might need to be more explicit in prompts that relied on the old model filling in gaps.

Fewer tool calls by default. The model uses reasoning more and makes fewer tool calls at lower effort levels. If your agent is not invoking tools as expected after upgrading, raise the effort level.

Response length calibrates to task complexity. Opus 4.7 doesn't default to a fixed verbosity. Short tasks get shorter responses, complex ones get longer. If you had prompts that said "be concise" to fight verbose defaults, try removing that scaffolding after upgrading and see if it's still needed.

More direct tone. Opus 4.7 is more opinionated and less validation-forward than 4.6. Fewer filler phrases, fewer emoji. For most developer-facing agents this is an improvement. If your product intentionally used a warmer persona, you may need to reinforce that in the system prompt.

Migration checklist

Before upgrading any production agent to claude-opus-4-7:

API breaking changes (fix these first):

[ ] Remove #[Temperature] attribute on all Anthropic agents, or confirm your SDK version handles this automatically
[ ] Search for temperature, top_p, top_k in any direct Anthropic API calls and remove them
[ ] Search for thinking: enabled or budget_tokens patterns and migrate to thinking: adaptive
[ ] Check any code that reads thinking content from responses and add display: "summarized" if needed

Token budget:

[ ] Run your heaviest prompts through count_tokens on claude-opus-4-7 and compare with 4.6
[ ] Update max_tokens to give extra headroom on long agentic loops
[ ] Adjust context compaction triggers if you have them

Behavior validation:

[ ] Run your existing eval suite or a sample of real prompts through Opus 4.7 before switching production traffic
[ ] Check tool-call rates in agentic workflows, raise effort if the model is under-calling
[ ] Review any prompts that relied on the model generalizing instructions across items

Automate the code changes:
Anthropic ships a Claude API skill for Claude Code that applies the model ID swap, breaking parameter changes, and effort calibration across your codebase automatically. In Claude Code, run:

/claude-api migrate this project to claude-opus-4-7

It covers the same steps as the manual checklist above and outputs a list of items to verify manually after. Worth running before you do anything by hand.

Is the upgrade worth it?

For agentic coding workflows: yes, without much debate. Opus 4.7 records 64.3% on SWE-bench Pro and 87.6% on SWE-bench Verified. If you're building agents that write, review, or refactor Laravel code (the kind of thing covered in the complete Laravel AI SDK guide), the improvement on long-horizon autonomy is real.

For simple single-turn assistants: the breaking changes create migration work for no benefit if your use case doesn't involve agentic loops or vision. You can stay on Opus 4.6 for now. The model is not deprecated.

For anything processing images or documents: the resolution jump makes this worth it. 2576px is meaningfully better for reading dense screenshots, technical diagrams, and multi-column PDFs.

FAQ

Do the breaking changes apply if I'm using Claude Managed Agents instead of the Messages API?

No. Anthropic explicitly states that Claude Managed Agents has no breaking API changes for Opus 4.7. You only need to update the model name. The parameter changes described in this post apply to the Messages API, which is what the Laravel AI SDK uses under the hood.

Can I run Opus 4.6 and Opus 4.7 in the same Laravel app?

Yes. The model string is a per-agent attribute in the Laravel AI SDK, so you can point different agents at different models. Keep critical production agents on 4.6, migrate lower-stakes agents first, and validate before switching over.

If I remove #[Temperature], how do I control the model's behavior?

Prompting and the effort parameter. Anthropic's official guidance is to use prompting to guide behavior on Opus 4.7 rather than sampling parameters. If you need more creative outputs, say so in the system prompt. If you need more deterministic outputs, use stricter instructions and structured output schemas.

Will the tokenizer change affect my context window usage?

Yes. With up to 35% more tokens for the same input, you'll hit compaction or truncation thresholds sooner on long conversations. If you have logic that triggers a context summary at a specific token threshold, lower that threshold to compensate for the new tokenizer.

Is temperature still available on other Anthropic models like Haiku 4.5?

Probably, but I wouldn't assume it. The official docs say "Starting with Claude Opus 4.7, setting temperature, top_p, or top_k to any non-default value will return a 400 error," which reads like it's scoped to Opus 4.7 specifically for now. Before removing #[Temperature] from agents running Haiku or Sonnet, check the models overview directly rather than taking my word for it.

Conclusion

The summary is short: three things break, one of them silently. Remove #[Temperature] from Anthropic agents, update the extended thinking syntax if you use it, and check whether anything reads thinking content from responses. After that, Opus 4.7 is a meaningful upgrade for anything involving agentic coding or vision.

Run the migration on a staging environment first, validate with real traffic, then switch production. The /claude-api migrate skill handles most of the mechanical changes automatically.

Building something with the Laravel AI SDK that needs an architecture review before you push to production? Get in touch and let's talk through it.

Claude Code Routines: Put Your Laravel Workflows on Autopilot

Hafiz — Wed, 22 Apr 2026 04:45:27 +0000

The problem with most AI coding workflows is they stop when you do. You close your laptop, the session ends. You're asleep, nothing runs. You come back Monday morning to a pile of unreviewed PRs and no idea whether Friday's deploy is healthy.

Claude Code Routines changes that. They run on Anthropic-managed cloud infrastructure, which means the session keeps going whether your machine is on or not. You write the prompt once, wire up a trigger, and the work happens in the background.

This is a practical guide to getting Routines set up on a real Laravel project. Five concrete use cases, actual prompts, and the gotchas you'll run into before you do.

What Routines are (and what they're not)

A Routine is a saved Claude Code configuration: a prompt, one or more GitHub repositories, and optional MCP connectors, packaged together and triggered automatically. Each run creates a full Claude Code cloud session on Anthropic's infrastructure. Claude clones your repo, does the work, and pushes to a claude/-prefixed branch.

Three things are worth knowing upfront.

First, Routines are different from /loop and Desktop scheduled tasks. /loop runs prompts inside your current terminal session and dies when you close it. Desktop scheduled tasks run on a schedule but need your machine to be on and Claude Code Desktop open. Routines are the only option that runs fully unattended on cloud infrastructure.

Second, this feature is currently in research preview. Behavior, the API shapes, and rate limits may change. That said, it's available right now on Pro, Max, Team, and Enterprise plans with Claude Code on the web enabled at claude.ai/code.

Third, Routines run fully autonomously. No approval prompts during a run. Whatever you write in the prompt is what runs. This is meaningfully different from a normal Claude Code session where you can steer mid-task. If you've used Claude Code Channels to send commands remotely, think of Routines as the version that runs without you sending anything at all.

Option	Where it runs	Machine required?	Survives closing terminal?
`/loop`	Local terminal	Yes	No
Desktop scheduled task	Your machine	Yes	No
Routine	Anthropic cloud	No	Yes

The three trigger types

Every Routine needs at least one trigger. You can also stack them on the same Routine.

Schedule triggers run on a recurring cadence. Hourly is the minimum interval. Daily, weekdays, and weekly are the built-in presets. For something like "every two hours" or "first Monday of the month," you pick the closest preset in the form and then run /schedule update in the CLI to set a specific cron expression after creation.

API triggers give the Routine a dedicated HTTP endpoint. POST to it with a bearer token and optionally pass a text field for run-specific context. This is what makes Routines composable with the rest of your stack: your deploy pipeline, your alerting system, a webhook from Sentry. Any service that can make an authenticated HTTP request can trigger a Routine.

GitHub triggers react to repository events automatically. A PR is opened. A release is published. A labeled PR gets a new commit pushed. You add filters to narrow which events fire: base branch equals main, is draft is false, author contains a specific username.

One Routine can use multiple triggers. A code review Routine might run nightly (for anything opened the day before), fire on every new PR, and be callable via API from your CI pipeline. All three wired to the same prompt.

Five Laravel use cases worth setting up

1. Nightly PR review

The most immediately useful Routine for any active Laravel project. Claude reviews all open PRs opened in the last 24 hours, runs your Pest test suite, flags anything touching auth or database migrations, and leaves inline comments.

Prompt to use:

Review all open pull requests in this repository that were opened in the last 24 hours and have no reviewer assigned.

For each PR:
- Run the Pest test suite and report any failures
- Check that migrations are reversible and include both up() and down() methods
- Flag any raw queries that bypass Eloquent
- Check that jobs implement ShouldQueue and define both $tries and $timeout
- Flag any use of env() outside of config files
- Leave inline review comments for issues found
- Add a summary comment listing all issues, or confirming the PR is clean

Do not approve the PR. Add a "needs-changes" label if any issues are found, and "passed-ai-review" if clean.

Set a schedule trigger for every weekday at 8:00 AM. You start the morning with feedback already posted. Human reviewers can focus on architecture instead of catching env() in the wrong place.

2. Queue health check

Horizon is great but it doesn't catch everything. A nightly Routine can run queue diagnostics on your Laravel project and ping you only when something is actually wrong, not just generate noise.

Using the environment variables available in this session, run the following checks:

1. Run php artisan queue:monitor against all configured queue drivers
2. Check the failed_jobs table for any entries created in the last 24 hours
3. Hit the /horizon/api/stats endpoint and verify Horizon is running and workers are active
4. Check the application log for any CRITICAL or ERROR entries from the last 24 hours

If all checks pass, exit without posting anything.
If any check fails, post a message to the #alerts Slack channel with the failure details and the exact artisan commands to fix it.

You'll need a Slack MCP connector configured and your environment credentials set as environment variables in the cloud environment. For a full list of queue-related Artisan Commands, the reference page is worth bookmarking when you're building out the prompt.

3. Automated code review on PR open

Set a GitHub trigger to fire on pull_request.opened with one filter: is draft is false. This catches every non-draft PR the moment it's opened and runs your team's checklist before a human reviewer even looks at it.

A new pull request has just been opened. Apply our Laravel code review checklist:

- New controllers must use the single-action pattern (one public __invoke method only)
- Form Requests used for all validation, never validate() inside controllers
- No env() calls outside of config files
- No missing $fillable on new Eloquent models
- All new jobs implement ShouldQueue and define $tries and $timeout
- Flag any database queries inside loops (N+1 problem) with the exact file and line
- No direct use of DB::statement() or DB::select() without a comment explaining why

Leave an inline comment for each violation. Post a summary comment at the bottom of the PR. Add label "passed-ai-review" if clean, or "needs-changes" if violations were found. Do not approve or request changes on the PR directly.

The filter matters here. is draft: false means the Routine only fires on PRs that are actually ready for review. You don't want it running every time someone pushes a commit to a draft.

4. Post-deploy smoke test via API

Wire your CD pipeline to trigger a Routine every time a production deploy completes. The Routine runs smoke checks against the new build and posts the result to your release channel.

The API trigger gives you a text field you can use to pass deploy context. From your deploy script:

curl -X POST https://api.anthropic.com/v1/claude_code/routines/trig_01XXXXX/fire \
  -H "Authorization: Bearer YOUR_ROUTINE_TOKEN" \
  -H "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "Deploy complete. SHA: abc123. Environment: production."}'

Note: the bearer token here is your Routine-specific token, not your Anthropic API key. Generate it from the API trigger setup in the web UI. It's shown once, so store it in your secrets manager immediately.

The Routine prompt can reference the deploy context passed via text:

A production deploy has just completed. The deploy details are in your session context.

Run the following smoke checks:
1. Hit the /health endpoint and verify a 200 response
2. Run php artisan about to confirm the application is responding
3. Run php artisan queue:monitor and report queue status
4. Check the error log for any new CRITICAL entries in the last 5 minutes

Post results to the #deployments Slack channel. Include the deploy SHA from the context. Mark as PASS if all checks succeed, FAIL with details if any check fails.

5. Weekly documentation drift detection

Docs get stale. A weekly Routine that scans merged PRs, compares changed methods against your /docs directory, and opens update PRs when it finds drift handles this automatically.

Scan all pull requests merged in the last 7 days.

For each merged PR:
1. Identify which PHP files changed
2. Check whether the changed public methods or classes are referenced in the /docs directory
3. If documentation references a changed method but looks outdated based on the diff, open a PR against the docs branch with a suggested update

Skip PRs that only changed tests, migrations, config files, or frontend assets. Only flag documentation that references changed public-facing methods or API endpoints.

Schedule it for Sunday at midnight. By Monday morning you have doc update PRs queued, not a manual task sitting in someone's backlog.

Setting up your first Routine

The fastest path is through the web UI. Go to claude.ai/code/routines and click New routine.

Give it a descriptive name. "Nightly PR Review" is better than "Routine 1." Write the prompt. This is the most important part: the Routine runs without you in the loop, so the prompt must be explicit about what to do and what success looks like. Vague prompts produce vague results, and there's no one watching to redirect them.

Select your GitHub repository. Claude clones it fresh at the start of every run, starting from the default branch.

Pick an environment. The Default environment works for most cases. If your Routine needs to call external APIs or read secrets like Sentry tokens or Slack webhooks, create a custom environment first and set those values as environment variables there.

Add your trigger. For a scheduled Routine, pick the frequency. Times are set in your local timezone and converted automatically, so "9:00 AM" fires at 9:00 AM wherever you are, not in some UTC offset you have to calculate.

Review the connectors. All connected MCP connectors are included by default. Remove anything the Routine doesn't actually need. A Routine that only reviews code and opens PRs has no reason to have Linear or Google Drive in scope.

Click Create. Hit Run now on the detail page to test it immediately without waiting for the next scheduled time.

From the CLI, run /schedule in any Claude Code session to create a Routine conversationally. Useful when you know exactly what you want and don't want to click through the web UI. /schedule list shows all your Routines, /schedule update changes one, and /schedule run triggers it immediately.

Branch permissions: the default that catches people

By default, Routines can only push to branches prefixed with claude/. This is intentional. An autonomous agent creating commits on main or develop is risky if the prompt isn't perfectly scoped.

When you add a repository to a Routine, there's an Allow unrestricted branch pushes toggle. Leave it off unless you have a specific need. The claude/ prefix keeps automated work clearly identifiable and makes cleanup straightforward if something goes sideways.

If your Routine is creating PRs that look right but fails on push, this is almost certainly the reason. Enable unrestricted pushes for that repo in the Routine's settings.

The flip side: PRs created by a Routine appear under your GitHub identity. Commits carry your username. Slack messages sent by a Routine's connector use your Slack account. The Routine acts as you, not as a bot account.

Plans and limits

Routines are available on Pro, Max, Team, and Enterprise plans. They draw from your regular Claude Code subscription usage the same way interactive sessions do. There's also a daily cap on how many Routine runs can start per account, visible at claude.ai/settings/usage.

If you hit the daily cap, additional runs are rejected until the window resets. On Team and Enterprise plans with extra usage enabled, Routines continue on metered overage instead.

GitHub event triggers also have per-routine and per-account hourly caps during the research preview. Events beyond the limit are dropped until the window resets. Worth keeping in mind if you're setting up a trigger on a high-volume repository.

When to use GitHub Actions instead

Routines are not a replacement for CI/CD. Running tests on every push, deploying to staging on merge, enforcing security checks before a PR can be merged, anything that needs to block a developer workflow belongs in GitHub Actions. It integrates with branch protections, runs in your own infrastructure, and has native visibility in the PR UI.

Routines are better for background work that doesn't need to gate anything. Review, triage, documentation updates, monitoring. Think of it as the difference between a gatekeeper (CI/CD) and an assistant handling repetitive work in the background.

Also, Routines run with no approval prompts. That's the point, but it's also a risk. Test any Routine with Run now and review what it actually did before leaving it to run unattended. A badly scoped PR review prompt that opens 30 spurious PRs is not a great Monday morning.

The Claude Code ecosystem post covers where Routines fit alongside other pieces like CLAUDE.md, skills, MCP, and the plugin marketplace if you want the full picture.

FAQ

Do Routines work on private repositories?

Yes. Routines clone your connected GitHub repositories, including private ones, as long as you've granted the necessary access via the web setup flow or /web-setup in the CLI. GitHub event triggers specifically require installing the Claude GitHub App on the repository. Repository access via /web-setup is separate and doesn't install the App automatically.

What's the difference between a Routine and a GitHub Action that calls Claude Code?

GitHub Actions run on GitHub's infrastructure, count against your GitHub Actions minutes, and can gate PRs and deployments through required status checks. Routines run on Anthropic-managed infrastructure and count against your Claude Code subscription. Use GitHub Actions when you need to block something. Use Routines for background work that doesn't need to block anything.

Can I share Routines with teammates?

Not currently. Routines belong to your individual claude.ai account and aren't shared. Everything a Routine does through your GitHub identity or connectors appears as you. For team workflows where multiple people need the same automation, each person sets up their own Routine, or you handle it through GitHub Actions with shared secrets.

Can I pass different context on each API trigger call?

Yes. The optional text field in the API request body is passed to the Routine as run-specific context alongside its saved prompt. Pass anything: a Sentry alert body, a deploy SHA, a list of changed files. The Routine receives it as a literal string, so don't send structured JSON expecting it to be parsed. If you need structured data, serialize it yourself and parse it in the prompt instructions.

What happens when a Routine run fails mid-session?

The run session stays visible at claude.ai/code/routines. You can open it, see exactly what Claude did, and continue the conversation manually if needed. The Routine itself keeps running on future triggers. Only that individual run failed.

Conclusion

Routines flip the default. Instead of Claude Code being a tool you actively drive, it becomes something that works in the background while you're focused on other things, or asleep. The nightly PR review alone is worth the setup time on any project with more than one contributor.

Start with one. Set up the nightly PR review, run it manually a few times to tune the prompt, then leave it running. Once you trust it, you'll think of five more things to automate.

Building a Laravel application that needs architectural review or a second set of eyes on code quality? Get in touch and let's talk about what that looks like.

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

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

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

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

What Problem Are We Actually Solving?

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

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

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

    return redirect('/dashboard');
}

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

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

Events: The Signal

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

<?php

namespace App\Events;

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

class UserRegistered
{
    use Dispatchable, SerializesModels;

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

Create one with Artisan:

php artisan make:event UserRegistered

Fire it anywhere in your application:

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

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

Listeners: What Reacts

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

php artisan make:listener SendWelcomeEmail --event=UserRegistered

<?php

namespace App\Listeners;

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

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

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

Auto-Discovery in Laravel 11+

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

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

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

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

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

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

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

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

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

php artisan event:cache

Clear it during deployment with:

php artisan event:clear

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

use Illuminate\Support\Facades\Event;

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

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

Queued Listeners

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

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

class SendWelcomeEmail implements ShouldQueue
{
    use InteractsWithQueue;

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

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

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

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

After Database Commit

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

The fix is ShouldHandleEventsAfterCommit:

use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;

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

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

Observers: Model Lifecycle Hooks

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

php artisan make:observer UserObserver --model=User

<?php

namespace App\Observers;

use App\Models\User;

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

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

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

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

<?php

namespace App\Models;

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

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

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

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

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

The Full List of Observer Methods

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

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

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

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

What Goes in an Observer vs a Listener

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

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

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

Here's a practical SaaS breakdown:

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

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

A Real-World Pattern: User Registration

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

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

        UserRegistered::dispatch($user);

        return redirect('/dashboard');
    }
}

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

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

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

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

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

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

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

Testing Events and Listeners

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

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

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

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

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

Test the listener separately by instantiating it directly:

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

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

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

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

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

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

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

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

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

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

Artisan Commands Reference

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

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

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

# Clear the event cache
php artisan event:clear

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

Common Mistakes

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

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

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

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

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

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

FAQ

Should I use Events or Jobs for background tasks?

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

Can one listener handle multiple events?

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

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

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

Do observer methods run inside database transactions?

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

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

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

Conclusion

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

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

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

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

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

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

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

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

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

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

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

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

Why NativePHP and Why Laravel 12, Not 13

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

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

The stack for ForcedBreak:

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

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

The Core Architecture: Two Timers, Not One

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

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

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

The solution is two separate systems:

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

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

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

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

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

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

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

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

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

This is registered in NativeAppServiceProvider:

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

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

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

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

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

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

Problem 1: The Dual-Database Trap

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

Here's what was happening.

NativePHP stores its database at:

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

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

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

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

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

    // ... rest of boot
}

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

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

To debug this yourself:

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

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

Problem 2: Not All NativePHP Facades Work From Child Processes

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

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

Here's what I found through testing:

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

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

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

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

Problem 3: URL Resolution in Artisan Context

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

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

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

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

Then in the ticker command:

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

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

Problem 4: Multi-Screen Overlay

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

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

$displays = Screen::displays();

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

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

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

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

Distributing the App

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

php artisan native:build mac

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

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

xattr -cr /Applications/ForcedBreak.app

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

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

What I Shipped vs What I Cut

Six features were planned and cut before v1:

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

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

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

What's Next

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

Download ForcedBreak v1.0.0 for Apple Silicon →

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

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

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

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

FAQ

Does ForcedBreak work on Intel Macs?

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

Can NativePHP build Windows apps?

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

Why not just build this in Swift?

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

How large is the final .dmg?

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

What happens if a user disables all challenges?

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

Conclusion

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

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

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

Laravel Policies vs Gates: The Complete Authorization Guide

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

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

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

Gates vs Policies: The One-Sentence Version

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

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

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

Gates: Quick Authorization Without a Model

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

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

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

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

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

use Illuminate\Support\Facades\Gate;

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

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

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

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

When to use Gates:

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

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

Policies: Authorization Organized Around a Model

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

php artisan make:policy PostPolicy --model=Post

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

<?php

namespace App\Policies;

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

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

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

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

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

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

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

Registering Policies: Three Ways in Laravel 13

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

Manual registration in AppServiceProvider:

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

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

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

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

<?php

namespace App\Models;

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

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

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

How to Call a Policy

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

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

use Illuminate\Support\Facades\Gate;

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

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

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

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

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

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

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

use Illuminate\Routing\Attributes\Controllers\Authorize;

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

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

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

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

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

<?php

namespace App\Http\Controllers;

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

abstract class Controller extends BaseController
{
    use AuthorizesRequests;
}

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

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

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

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

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

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

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

Returning Rich Responses Instead of Booleans

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

use Illuminate\Auth\Access\Response;

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

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

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

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

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

Authorization in Blade

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

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

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

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

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

Authorization and Inertia: Sharing Policy Data with the Frontend

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

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

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

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

The Mistakes Worth Knowing

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

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

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

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

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

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

When Spatie Permission Fits In

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

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

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

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

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

Frequently Asked Questions

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

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

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

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

Can a Policy method allow unauthenticated users?

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

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

Can I authorize multiple models in one Policy method?

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

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

Then accept both in the policy method:

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

Where should I put authorization logic for API routes?

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

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

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

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

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

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

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

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

What Each Tool Is Actually Solving

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

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

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

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

Laravel Telescope: Your Local Debugging Companion

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

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

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

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

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

Laravel Pulse: The Production Health Dashboard

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

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

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

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

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

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

Laravel Nightwatch: Full Production Observability

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

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

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

php artisan nightwatch:agent

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

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

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

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

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

How to Pick the Right Tool

The decision tree is simpler than it looks:

A few real-world scenarios to make this concrete:

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

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

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

Can You Use All Three Together?

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

The practical setup for a team running all three:

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

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

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

Setting Up Nightwatch on Laravel Forge (The Quickest Path)

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

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

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

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

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

Frequently Asked Questions

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

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

Does Pulse replace Telescope?

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

Can Nightwatch run on shared hosting?

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

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

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

Should I disable Nightwatch in local development?

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

Nightwatch in Practice: Where It Earns Its Keep

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

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

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

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

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

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

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

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

Why Pest Instead of PHPUnit

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

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

Now look at the Pest equivalent:

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

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

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

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

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

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

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

Installing Pest 4 in a Laravel 13 Project

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

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

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

Then initialise Pest in your project:

./vendor/bin/pest --init

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

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

Configure Pest.php Before Writing Anything

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

<?php

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

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

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

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

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

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

The Feature We're Testing

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

The controller:

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

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

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

Routes:

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

The form request validates incoming data:

// app/Http/Requests/StorePostRequest.php

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

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

Writing Your First Feature Tests

Create the test file:

php artisan make:test Api/PostTest

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

<?php

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

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

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

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

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

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

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

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

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

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

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

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

What Actually Deserves a Test

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

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

Three categories always worth covering:

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

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

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

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

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

Shared Setup with beforeEach

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

<?php

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

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

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

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

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

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

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

Datasets for Validation Testing

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

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

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

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

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

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

<?php

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

Then reference by name from any test file:

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

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

Architecture Testing: The Feature Nobody Covers

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

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

Create tests/Arch/AppTest.php:

<?php

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

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

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

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

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

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

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

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

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

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

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

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

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

Running Tests in Parallel

One flag changes the runtime dramatically:

./vendor/bin/pest --parallel

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

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

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

Workflow configuration:

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

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

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

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

Type Coverage

Install the plugin:

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

Run it with a minimum threshold:

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

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

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

Frequently Asked Questions

Does Pest 4 work with my existing PHPUnit tests?

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

Can I use Pest with Livewire and Filament?

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

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

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

Is arch testing worth adding to a small project?

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

How do I run just one test or one file?

Run a specific file:

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

Filter by test description: ""

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

Run a specific group:

./vendor/bin/pest --group api

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

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

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

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

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

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

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

The Problem With the Old Two-File Pattern

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

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

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

What a Single-File Component Looks Like

Create one with:

php artisan make:livewire search-posts

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

<?php

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

new class extends Component {

    public string $query = '';

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

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

};

?>

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

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

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

Adding an Island for Expensive Data

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

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

<?php

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

new class extends Component {

    public string $query = '';

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

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

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

};

?>

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

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

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

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

Rendering the Component

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

<livewire:search-posts />

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

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

php artisan make:livewire pages::search

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

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

When to Use Single-File vs Multi-File

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

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

php artisan make:livewire post.editor --mfc

This generates a directory:

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

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

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

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

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

Migrating a v3 Component

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

Before (v3 class-based):

app/Livewire/SearchPosts.php:

<?php

namespace App\Livewire;

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

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

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

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

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

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

After (v4 single-file):

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

<?php

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

new class extends Component {

    public string $query = '';

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

};

?>

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

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

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

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

FAQ

Do I have to rewrite my existing v3 components?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The Problem With Laravel Envoy

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

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

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

Scotty addresses both directly.

What Scotty Does Differently

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

#!/usr/bin/env scotty

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

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

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

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

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

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

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

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

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

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

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

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

scotty run deploy --pretend

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

Installing Scotty

Install it as a global Composer package:

composer global require spatie/scotty

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

composer global config bin-dir --absolute

Once installed, verify it works:

scotty list

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

scotty init

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

Migrating From Envoy

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

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

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

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

Zero-Downtime Deployments

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

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

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

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

Here's the complete zero-downtime script:

#!/usr/bin/env scotty

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

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

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

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

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

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

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

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

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

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

Run with:

scotty run deploy

Or deploy a specific branch:

scotty run deploy --branch=develop

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

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

So Is It Worth Switching?

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

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

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

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

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

FAQ

Does Scotty work with multiple servers?

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

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

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

Can I run Scotty in CI/CD?

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

What happens if a task fails mid-deploy?

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

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

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

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

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

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

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

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

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

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

What Livewire 4 Actually Changed

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

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

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

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

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

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

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

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

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

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

What Inertia.js 3 Actually Changed

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

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

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

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

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

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

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

The Fundamental Difference Is Still the Same

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

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

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

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

The Real Decision in 2026

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

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

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

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

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

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

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

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

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

My Take

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

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

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

FAQ

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

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

Does Livewire 4 require Filament v5?

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

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

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

Which performs better?

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

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

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

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

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

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

What's Actually New in v3

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

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

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

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

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

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

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

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

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

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

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

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

Can You Upgrade Right Now?

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

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

Before You Run composer update: Check Your Requirements

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

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

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

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

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

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

The Upgrade Steps

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

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

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

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

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

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

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

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

Breaking Changes to Fix

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

Event renames

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

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

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

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

Axios, qs, and lodash-es are gone

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

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

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

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

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

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

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

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

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

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

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

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

`Inertia::lazy()` is removed

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

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

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

Progress indicator exports

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

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

The `future` config block is gone

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

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

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

Config file restructuring

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

ESM-only output

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

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

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

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

Two Things Worth Using Right Away

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

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

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

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

Should You Upgrade This Weekend?

Depends on your stack.

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

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

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

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

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

Frequently Asked Questions

Do I have to use the new Vite plugin?

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

Can I still use Axios with Inertia v3?

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

What if I'm on Laravel 10?

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

Does Inertia v3 work with Filament?

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

Is the useHttp hook available in all three adapters?

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

What's Next

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

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

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

Forem: Hafiz

Generate Beautiful Open Graph Images for Your Laravel App with One Spatie Package

Why this package matters

How it actually works

Setting it up on a Laravel app

Your first OG image

Previewing without sharing the link 100 times

Design tips that took me too long to learn

Using a Blade view instead of inline HTML

Fallback images for pages without templates

The Cloudflare driver: when you can't run Chromium

Pre-generating images so the first share never lags

Caching, storage, and clearing old images

When this package isn't the right tool

FAQ

Conclusion

Claude Opus 4.7: What Laravel AI SDK Developers Need to Check Before Upgrading

The model string and pricing

The three breaking changes that will actually bite you

1. The #[Temperature] attribute breaks on Opus 4.7

2. Extended thinking is gone, swap it for adaptive thinking

3. Thinking content is silently omitted

The tokenizer change: your bill may go up

New features worth actually using

The xhigh effort level

Task budgets for long agentic loops

High-resolution image support

Behavior changes that might need prompt updates

Migration checklist

Is the upgrade worth it?

FAQ

Conclusion

Claude Code Routines: Put Your Laravel Workflows on Autopilot

What Routines are (and what they're not)

The three trigger types

Five Laravel use cases worth setting up

1. Nightly PR review

2. Queue health check

3. Automated code review on PR open

4. Post-deploy smoke test via API

5. Weekly documentation drift detection

Setting up your first Routine

Branch permissions: the default that catches people

Plans and limits

When to use GitHub Actions instead

FAQ

Conclusion

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

What Problem Are We Actually Solving?

Events: The Signal

Listeners: What Reacts

Auto-Discovery in Laravel 11+

Queued Listeners

After Database Commit

Observers: Model Lifecycle Hooks

The Full List of Observer Methods

What Goes in an Observer vs a Listener

A Real-World Pattern: User Registration

Testing Events and Listeners

Artisan Commands Reference

Common Mistakes

FAQ

Conclusion

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

Why NativePHP and Why Laravel 12, Not 13

The Core Architecture: Two Timers, Not One

Problem 1: The Dual-Database Trap

Problem 2: Not All NativePHP Facades Work From Child Processes

Problem 3: URL Resolution in Artisan Context

Problem 4: Multi-Screen Overlay

Distributing the App

What I Shipped vs What I Cut

What's Next

FAQ

Conclusion

Laravel Policies vs Gates: The Complete Authorization Guide

Gates vs Policies: The One-Sentence Version

Gates: Quick Authorization Without a Model

Policies: Authorization Organized Around a Model

Registering Policies: Three Ways in Laravel 13

1. The `#[Temperature]` attribute breaks on Opus 4.7

The `xhigh` effort level

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

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

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

`Inertia::lazy()` is removed

The `future` config block is gone