DEV Community: Sumeet Shroff

Laravel Cloud vs Forge vs a Self-Hosted VPS

Sumeet Shroff — Thu, 03 Sep 2026 10:01:05 +0000

Laravel Cloud vs Forge vs a Self-Hosted VPS

Three paths exist for getting a Laravel application into production: let Laravel Cloud handle everything, use Forge to manage your own servers, or configure a VPS from scratch. Each represents a different point on the control-vs-convenience spectrum, and picking the wrong one costs you either money, engineering time, or both.

This article cuts straight to the trade-offs. It assumes you already understand basic Laravel deployment concepts — if you want the broader picture, the Laravel Deployment and Hosting: Cloud, Forge, VPS, Docker, and Octane guide covers the full stack.

Prerequisites: Laravel 12 (PHP 8.2+) or Laravel 13 (PHP 8.3+), Composer 2.x, a GitHub/GitLab repository. For Forge: an account at forge.laravel.com. For Laravel Cloud: an account at cloud.laravel.com.

The Core Difference

Dimension	Laravel Cloud	Forge + VPS	Self-Hosted VPS
Infrastructure owner	Laravel/AWS EC2	You (via DigitalOcean, Hetzner, etc.)	You
SSH access	No	Yes (full root)	Yes (full root)
Deployment trigger	Git push	Git push or Forge webhook	Custom CI/CD
Auto-scaling	Yes (per-replica)	No (manual resize)	No
Pricing model	Usage-based	Flat monthly ($12–$29/mo for Forge + server cost)	Server cost only
Zero-downtime deploys	Built-in	Built-in (single server)	Manual setup
Ops overhead	Near zero	Low	High

Laravel Cloud

Launched on February 24, 2025 alongside Laravel 12, Laravel Cloud is a fully managed, serverful platform running on Amazon EC2. "Serverful" is the important word — your application container stays warm between requests. There are no Lambda cold starts.

What it does automatically:

Provisions isolated environments (production, staging, preview per branch)
Runs composer install --no-dev, config/route/view cache, and migrations on each deploy
Scales replicas up and down based on traffic
Rotates SSL certificates
Manages encrypted environment variables

What you cannot do:

SSH into the underlying instance
Install custom PHP extensions not included in the platform image
Configure Nginx directly
Run long-lived daemons outside of the provided worker abstraction

Pricing: The Starter plan carries no monthly subscription fee — you pay only for compute and bandwidth consumed. Growth plans begin at $20/month with higher resource ceilings. Pricing is usage-based, which is predictable when traffic is steady but can spike with traffic bursts.

When to choose Cloud:
You want zero ops overhead. Your team does not have a dedicated DevOps engineer. Traffic is variable and you want auto-scaling without provisioning extra capacity manually. You are comfortable with the Laravel ecosystem's managed environment and the associated vendor dependency.

Laravel Forge

Forge is a server management panel, not a hosting provider. You bring the cloud server — DigitalOcean, AWS, Hetzner, Vultr, or any provider that lets Forge connect via API. Forge then provisions Ubuntu, configures Nginx, PHP-FPM, MySQL or PostgreSQL, Redis, and Supervisor, and wires up your deployment pipeline.

The October 2025 overhaul introduced Laravel VPS — a DigitalOcean-backed product within Forge that provisions an Ubuntu server in seconds with consolidated billing. You get full SSH and root access, but Forge handles the initial stack configuration.

Zero-downtime deployments (enabled by default for new Forge sites):

Forge uses an atomic symlink strategy. Each deployment clones your repository into a timestamped directory under releases/, runs your deployment script, then switches the current symlink. The last four releases are retained for instant rollback.

# Forge deployment script (configured in Forge dashboard)
cd /home/forge/example.com
git pull origin main

composer install --no-dev --optimize-autoloader --no-interaction

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache
php artisan migrate --force

php artisan queue:restart

Critical note: php artisan migrate --force bypasses the production confirmation prompt. Always test migrations on a staging server first — schema changes can cause irreversible data loss.

Shared paths configuration:

For zero-downtime deployments, .env and storage/ must persist across releases. In Forge's dashboard, under a site's zero-downtime settings, add these shared paths:

.env
storage

Forgetting this causes each release to deploy with an empty storage directory — uploaded files vanish and sessions break.

Multi-server limitation:

Forge's atomic deployments work on a single server only. If you run two application servers behind a load balancer, Forge cannot coordinate a simultaneous atomic deploy across both. For that you need Laravel Envoyer, which deploys a single project across multiple servers with health checks before traffic is switched.

When to choose Forge:
You want full server control — custom Nginx configs, specific PHP extensions, multiple queue worker groups, PostgreSQL 18 (now supported in Forge for new deployments), or the ability to SSH in when things go wrong. Traffic is relatively predictable and a fixed-size server covers your load. You want flat-rate pricing.

Self-Hosted VPS (No Forge)

Provisioning and configuring a VPS without a panel means owning every layer: OS updates, Nginx config, PHP-FPM pools, SSL renewal, firewall rules, and deployment scripting. This is operationally expensive but gives you complete control and the lowest possible cost per compute unit.

Baseline production stack (Ubuntu 24.04 LTS):

# /etc/nginx/sites-available/example.com
server {
    listen 80;
    server_name example.com;
    root /var/www/current/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Queue worker via Supervisor:

# /etc/supervisor/conf.d/laravel-worker.conf
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/current/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=8
redirect_stderr=true
stdout_logfile=/var/www/current/storage/logs/worker.log
stopwaitsecs=3600

Run sudo supervisorctl reread && sudo supervisorctl update && sudo supervisorctl start laravel-worker:* after adding the config.

After every deployment, restart long-running processes:

php artisan queue:restart
sudo supervisorctl restart laravel-worker:*

New application code is NOT picked up by queue workers until they restart. This is the most common production bug in self-managed deployments.

When to choose a bare VPS:
You are running predictable, steady-state traffic on a tight budget. A $6–12/month DigitalOcean or Hetzner droplet handles substantial CRUD traffic. You have the ops experience to manage patching, backups, and incident response, or you are willing to learn.

Common Mistakes Across All Three

1. Calling env() outside config files after config:cache

Once php artisan config:cache runs, .env is no longer read at runtime. Any env() call that is not inside a config/*.php file returns null.

// WRONG — returns null in production after config:cache
$apiKey = env('STRIPE_SECRET');

// CORRECT — read from config, which was cached from .env
$apiKey = config('services.stripe.secret');

2. Not restarting Octane or queue workers after deploy

Laravel Cloud handles this automatically. Forge's deployment script must include php artisan queue:restart. A bare VPS requires a Supervisor restart command in your CI/CD pipeline.

3. Exposing database ports publicly

MySQL, PostgreSQL, and Redis should never be accessible on public interfaces. On a bare VPS, configure UFW to block ports 3306, 5432, and 6379 from external access. Forge provides a firewall UI to do this from the dashboard.

4. APP_DEBUG=true in production

With APP_DEBUG=true and CVE-2024-13918/CVE-2024-13919 present, Laravel's debug error page reflects request parameters unescaped, enabling reflected XSS. Always set APP_DEBUG=false in production .env.

5. Skipping --no-dev on composer install

Development dependencies (PHPUnit, Mockery, Laravel Pint) add 30–50 MB to the vendor directory and introduce unnecessary attack surface. Always use composer install --no-dev --optimize-autoloader in production.

Security Checklist Before Going Live

Patch to Laravel 12.1.1+ or 11.44.1+ to resolve CVE-2025-27515 (file validation bypass)
If using Livewire, update to v3.6.4+ — v3.6.3 and below carry CVE-2025-54068, a critical RCE vulnerability
Confirm register_argc_argv is disabled in php.ini (mitigates CVE-2024-52301, CVSS 8.7)
Verify APP_KEY is unique per environment — sharing keys between staging and production allows session/cookie forgery
Never bake .env files or secrets into Docker images

Verification After Deployment

Laravel 12 introduced native health check routes requiring no extra packages. Hit the endpoint after each deployment:

curl -s https://example.com/up
# Returns HTTP 200 with JSON: {"status":"ok"} when healthy
# Reports database, cache, and queue status

In Forge, you can configure this URL as a deployment health check — Forge aborts the symlink switch if the health endpoint returns a non-200 status, preventing a broken release from going live.

For bare VPS deployments, add the health check as the final step in your CI/CD pipeline:

# In your deploy script — abort if health check fails
HEALTH=$(curl -s -o /dev/null -w "%{http_code}" https://example.com/up)
if [ "$HEALTH" != "200" ]; then
  echo "Health check failed ($HEALTH) — rolling back"
  ln -sfn /var/www/releases/previous /var/www/current
  exit 1
fi

Decision Summary

Laravel Cloud if you want push-to-deploy with zero server management and are comfortable with usage-based pricing and no SSH access.
Forge if you want managed deployment tooling, full SSH access, predictable flat-rate billing, and the ability to customise your stack (PHP extensions, PostgreSQL 18, custom Nginx blocks).
Bare VPS if you have the ops expertise to manage the full stack, want the lowest cost per compute unit, and need maximum control over every layer of the environment.

For the large majority of Laravel projects — especially agencies and product teams without dedicated DevOps — Forge with a mid-tier DigitalOcean or Hetzner droplet is the pragmatic default. Laravel Cloud is compelling when auto-scaling is a hard requirement. A bare VPS pays off only when the ops cost is genuinely lower than the time saved by a managed tool.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Dev.to — Alpine.js Patterns for Dynamic Laravel Forms

Sumeet Shroff — Thu, 03 Sep 2026 08:01:51 +0000

Alpine.js Patterns for Dynamic Laravel Forms

If you're already using Laravel with Blade templates and want form interactions without reaching for a full JavaScript framework, Alpine.js is the right tool. At roughly 15 KB gzipped, it handles conditional fields, multi-step flows, dynamic repeater rows, and inline validation feedback — all declared directly in your HTML attributes.

This article focuses specifically on form patterns: the practical, real-world cases where Alpine.js saves you from writing dozens of lines of jQuery or wiring up a full Vue component for something that's really just three state variables. If you want the broader picture of where Alpine fits in the Laravel frontend ecosystem alongside Livewire 4, Inertia, React, and Vue, see Modern Laravel Frontends: Livewire 4, Inertia, React, Vue, and Alpine.js.

Prerequisites and Versions

Laravel 11 or 12
Alpine.js v3.15.x (latest stable as of June 2026 is v3.15.11, released April 1, 2026)
Blade templates (no Livewire required for any pattern in this article)
Basic familiarity with x-data, x-show, and x-model

Install Alpine via CDN (fast prototyping) or npm (production):

<!-- CDN -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.15.11/dist/cdn.min.js"></script>

# npm
npm install alpinejs@^3.15

// resources/js/app.js
import Alpine from 'alpinejs';
window.Alpine = Alpine;
Alpine.start();

Pattern 1 — Conditional Fields

The most common Alpine form pattern: show or hide fields based on the value of another field. A service enquiry form that reveals extra fields when "Custom Package" is selected:

<form method="POST" action="/enquiry" x-data="{ serviceType: '' }">
    @csrf

    <select name="service_type" x-model="serviceType">
        <option value="">Select a service</option>
        <option value="web-design">Website Design</option>
        <option value="seo">SEO</option>
        <option value="custom">Custom Package</option>
    </select>

    <div x-show="serviceType === 'custom'" x-transition style="display:none">
        <label>Describe your requirements</label>
        <textarea name="custom_requirements" rows="4"></textarea>

        <label>Estimated budget (INR)</label>
        <input type="number" name="budget" placeholder="e.g. 50000" />
    </div>

    <button type="submit">Send Enquiry</button>
</form>

The style="display:none" on the conditional div ensures it's hidden on page load before Alpine initialises — preventing a flash of unwanted content. x-transition adds a smooth opacity-and-scale entrance.

On the Laravel side, your validation rule conditionally requires the textarea only when service_type is custom:

// app/Http/Controllers/EnquiryController.php
public function store(Request $request): RedirectResponse
{
    $request->validate([
        'service_type'        => ['required', 'string'],
        'custom_requirements' => ['required_if:service_type,custom', 'string', 'max:1000'],
        'budget'              => ['required_if:service_type,custom', 'integer', 'min:1000'],
    ]);

    // store enquiry...

    return back()->with('success', 'Enquiry submitted.');
}

Keep validation on the server. Alpine's conditional display is a UX convenience, not a security gate.

Pattern 2 — Dynamic Repeater Rows

Allowing users to add multiple entries — team members, line items, phone numbers — without page reloads. This pattern uses Alpine's x-for with a reactive array.

<div x-data="{
    contacts: [{ name: '', phone: '' }],
    addRow()  { this.contacts.push({ name: '', phone: '' }); },
    removeRow(index) { this.contacts.splice(index, 1); }
}">

    <template x-for="(contact, index) in contacts" :key="index">
        <div class="flex gap-3 mb-3">
            <input
                type="text"
                :name="'contacts[' + index + '][name]'"
                x-model="contact.name"
                placeholder="Full name"
            />
            <input
                type="tel"
                :name="'contacts[' + index + '][phone]'"
                x-model="contact.phone"
                placeholder="Phone number"
            />
            <button type="button" @click="removeRow(index)"
                    x-show="contacts.length > 1">
                Remove
            </button>
        </div>
    </template>

    <button type="button" @click="addRow">Add Contact</button>
</div>

The :name binding uses the array index to produce contacts[0][name], contacts[1][name], etc. Laravel's request()->input('contacts') returns exactly this as a nested array.

Validate nested input in your controller:

$request->validate([
    'contacts'         => ['required', 'array', 'min:1'],
    'contacts.*.name'  => ['required', 'string', 'max:100'],
    'contacts.*.phone' => ['required', 'regex:/^[6-9]\d{9}$/'],
]);

Note on x-for and Alpine v3.15: Alpine now supports Set objects inside x-for, and template-based x-sort handles work correctly — but for basic repeater patterns, arrays remain the simplest choice.

Pattern 3 — Multi-Step Form with Progress

Breaking a long form into steps keeps users on task. Alpine manages the current step index; all form fields live inside a single <form> so a single POST submits everything.

<form method="POST" action="/project-brief"
      x-data="{ step: 1, totalSteps: 3 }">
    @csrf

    {{-- Step indicator --}}
    <p>Step <span x-text="step"></span> of <span x-text="totalSteps"></span></p>
    <div class="h-2 bg-gray-200 rounded">
        <div class="h-2 bg-blue-600 rounded"
             :style="'width:' + (step / totalSteps * 100) + '%'"></div>
    </div>

    {{-- Step 1: Contact details --}}
    <div x-show="step === 1" style="display:none">
        <input type="text"  name="name"  placeholder="Your name" />
        <input type="email" name="email" placeholder="Email address" />
    </div>

    {{-- Step 2: Project type --}}
    <div x-show="step === 2" style="display:none">
        <select name="project_type">
            <option value="ecommerce">Ecommerce Website</option>
            <option value="corporate">Corporate Website</option>
            <option value="landing">Landing Page</option>
        </select>
    </div>

    {{-- Step 3: Budget and deadline --}}
    <div x-show="step === 3" style="display:none">
        <input type="number" name="budget"   placeholder="Budget in INR" />
        <input type="date"   name="deadline" />
    </div>

    {{-- Navigation --}}
    <button type="button" @click="step--" x-show="step > 1">Back</button>
    <button type="button" @click="step++" x-show="step < totalSteps">Next</button>
    <button type="submit"                 x-show="step === totalSteps">Submit</button>
</form>

This approach has a deliberate limitation: client-side step validation is not enforced. A user can click submit on step 3 with step 1 fields empty — Laravel's server-side validation catches this and returns errors. If you need per-step client validation, add a validateStep() method to your x-data that checks required fields before advancing. Keep that lightweight — complex validation logic is a signal to consider Livewire instead.

Pattern 4 — Character Counter and Inline Feedback

Real-time character counts and field-level feedback with zero server round-trips:

<div x-data="{
    message: '',
    maxChars: 500,
    get remaining() { return this.maxChars - this.message.length; },
    get isOverLimit() { return this.message.length > this.maxChars; }
}">
    <textarea
        name="message"
        x-model="message"
        :class="{ 'border-red-500': isOverLimit }"
        rows="5"
        placeholder="Tell us about your project..."
    ></textarea>

    <p :class="isOverLimit ? 'text-red-600' : 'text-gray-500'">
        <span x-text="remaining"></span> characters remaining
    </p>
</div>

Getter properties (get remaining(), get isOverLimit()) in Alpine x-data objects work cleanly and re-evaluate reactively whenever message changes. This avoids storing derived state as separate reactive properties.

Pattern 5 — AJAX Submission Without Page Reload

Alpine can post a form via fetch and display success or error messages inline. This is appropriate for single-action widgets like a newsletter signup or a quick quote request — not for complex multi-field forms where error mapping across many fields gets unwieldy.

<div x-data="{
    email: '',
    status: null,
    errorMsg: '',
    async submit() {
        this.status = 'loading';
        const res = await fetch('/newsletter/subscribe', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-TOKEN': document.querySelector('meta[name=csrf-token]').content,
                'Accept': 'application/json',
            },
            body: JSON.stringify({ email: this.email }),
        });
        if (res.ok) {
            this.status = 'success';
        } else {
            const data = await res.json();
            this.errorMsg = data.message ?? 'Something went wrong.';
            this.status = 'error';
        }
    }
}">
    <input type="email" x-model="email" placeholder="Enter your email" />
    <button type="button" @click="submit" :disabled="status === 'loading'">
        <span x-show="status !== 'loading'">Subscribe</span>
        <span x-show="status === 'loading'">Subscribing...</span>
    </button>
    <p x-show="status === 'success'" class="text-green-600" style="display:none">You're subscribed!</p>
    <p x-show="status === 'error'"   class="text-red-600"   style="display:none" x-text="errorMsg"></p>
</div>

The CSRF token is read from the meta tag — always include <meta name="csrf-token" content="{{ csrf_token() }}"> in your layout. The Laravel controller returns response()->json() with appropriate status codes.

Common Mistakes

Forgetting style="display:none" on x-show elements. Without it, elements flash visible before Alpine boots, especially on slower devices. Always add the inline style to any element using x-show.

Putting business logic in Alpine expressions. Alpine evaluates expressions as JavaScript. Injecting any user-controlled string into an Alpine expression (x-bind, x-on, x-data) creates an XSS vector. Never dynamically construct Alpine directives from server-rendered user data.

Skipping server-side validation because Alpine handles it client-side. Alpine validation is strictly a UX enhancement. Every form submission must be validated in Laravel. Period.

Using Alpine for forms with 10+ interdependent fields. When your x-data object grows beyond 6–8 properties with multiple watchers and computed properties, maintainability drops. That's the signal to move to a Livewire component where PHP handles the logic and you get a clean class structure.

Not accounting for Alpine's CSP constraint. Alpine evaluates expressions using new Function(), which requires unsafe-eval in your Content Security Policy. If you need a strict CSP, use the Alpine CSP build (alpinejs/dist/cdn-csp.min.js). Be aware that enabling Livewire 4's csp_safe mode in config/livewire.php also forces the entire app to use Alpine's CSP evaluator, which restricts complex expressions in directives app-wide.

Testing Alpine Forms

Alpine state is entirely client-side, so testing happens at two levels:

Laravel feature tests — submit the form via HTTP and assert validation behaviour:

// tests/Feature/EnquiryFormTest.php
public function test_custom_package_requires_requirements(): void
{
    $response = $this->post('/enquiry', [
        'service_type' => 'custom',
        // missing custom_requirements
    ]);

    $response->assertSessionHasErrors('custom_requirements');
}

Browser tests — use Laravel Dusk to verify Alpine behaviour in a real browser:

// tests/Browser/EnquiryFormTest.php
public function test_custom_fields_appear_on_selection(): void
{
    $this->browse(function (Browser $browser) {
        $browser->visit('/enquiry')
                ->assertMissing('textarea[name=custom_requirements]')
                ->select('service_type', 'custom')
                ->waitFor('textarea[name=custom_requirements]')
                ->assertVisible('textarea[name=custom_requirements]');
    });
}

Dusk runs a real Chrome instance, so x-show, x-transition, and x-model behaviour is tested accurately.

When Alpine Is Enough vs When It Isn't

Alpine is the right choice when your form interaction is primarily about showing/hiding, counting, or posting to a single endpoint. It is the wrong choice when you need server-side reactivity (e.g., fetching a dynamic price from the database as the user changes fields, or running a real-time search). Those scenarios belong in Livewire, where every user interaction triggers a PHP method and Laravel handles the logic.

The practical line: if solving the problem requires a fetch call that returns structured data (not just a success/error), Alpine starts to fight against you and a Livewire component is cleaner.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Dev.to — Laravel with React or Vue through Inertia

Sumeet Shroff — Thu, 03 Sep 2026 08:00:46 +0000

Laravel with React or Vue through Inertia

If you've spent time with Laravel and wondered how to use React or Vue without abandoning the monolith, Inertia.js is the answer. It bridges the gap between a server-driven Laravel backend and a client-rendered component frontend — no separate API, no JSON contract negotiation, no duplicated routing layer.

This article focuses on the practical setup: how Inertia actually works, how to scaffold it with React or Vue, and where it makes sense compared to going full-SPA or staying with Blade.

Prerequisites and Versions

Before starting, confirm your stack:

Laravel 11 or 12 — required for the Inertia Laravel adapter v3
Inertia.js v3.0.0 (stable since March 25, 2026) — current default
Inertia.js v2.x — still supported; official Laravel starter kits ship with v2
React 19 or Vue 3 — both work with Inertia v2 and v3
Node.js 20+ and Vite for the frontend build pipeline
Composer and pnpm (or npm)

If you are on Laravel 10, you are capped at Inertia adapter v2. The v3 adapter requires Laravel 11 minimum.

How Inertia.js Works (The Mental Model)

Inertia is not a UI framework. It is a protocol adapter that sits between Laravel controllers and React/Vue components.

On a full-page load, Laravel renders an HTML shell with a single <div id="app"> that contains a JSON payload in a data-page attribute. Inertia's client-side adapter bootstraps React or Vue, reads that payload, and renders the correct page component.

On subsequent navigations, clicking an <Link> component triggers a fetch request with an X-Inertia: true header. Laravel detects this header and returns only JSON — the component name and its props — instead of a full HTML page. The client swaps the component without a full browser reload.

The result: your Laravel routes, controllers, and auth middleware work exactly as they always did. Your frontend developers get full React or Vue components with props typed exactly as the controller passes them.

Scaffolding a New Project

Option A — Official Laravel Starter Kit (Fastest)

# React 19 + Inertia 2 + Tailwind 4 + shadcn/ui
laravel new my-app --react

# Vue 3 + Inertia 2 + Tailwind 4
laravel new my-app --vue

Note: as of mid-2026, the official starter kits ship with Inertia v2, not v3. Inertia v3 must be manually upgraded after scaffolding if needed.

Option B — Breeze with Inertia Stack

composer require laravel/breeze --dev
php artisan breeze:install react
# or
php artisan breeze:install vue

npm install
npm run dev

Breeze installs authentication scaffolding (login, register, password reset) wired through Inertia pages. It's a solid starting point for applications that need auth out of the box.

Option C — Manual Inertia Install

For projects where you need fine-grained control:

# Server side
composer require inertiajs/inertia-laravel

# Publish middleware
php artisan inertia:middleware
# Register HandleInertiaRequests in bootstrap/app.php

# Client side — React
npm install @inertiajs/react react react-dom

# Or Vue
npm install @inertiajs/vue3 vue

Root template (resources/views/app.blade.php):

<!DOCTYPE html>
<html>
<head>
    @viteReactRefresh {{-- React only --}}
    @vite(['resources/js/app.jsx', 'resources/css/app.css'])
    @inertiaHead
</head>
<body>
    @inertia
</body>
</html>

React entrypoint (resources/js/app.jsx):

import { createInertiaApp } from '@inertiajs/react';
import { createRoot } from 'react-dom/client';

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.jsx', { eager: true });
        return pages[`./Pages/${name}.jsx`];
    },
    setup({ el, App, props }) {
        createRoot(el).render(<App {...props} />);
    },
});

Vue entrypoint (resources/js/app.js):

import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.vue', { eager: true });
        return pages[`./Pages/${name}.vue`];
    },
    setup({ el, App, props, plugin }) {
        createApp({ render: () => h(App, props) })
            .use(plugin)
            .mount(el);
    },
});

Writing Controllers and Page Components

A Laravel controller renders an Inertia page the same way it would render a Blade view — with one method call:

use Inertia\Inertia;

class ProductController extends Controller
{
    public function index()
    {
        return Inertia::render('Products/Index', [
            'products' => Product::latest()->paginate(20),
        ]);
    }

    public function show(Product $product)
    {
        return Inertia::render('Products/Show', [
            'product' => $product->load('reviews'),
        ]);
    }
}

The matching React page component at resources/js/Pages/Products/Index.jsx:

export default function Index({ products }) {
    return (
        <div>
            <h1>Products</h1>
            {products.data.map(product => (
                <div key={product.id}>{product.name}</div>
            ))}
        </div>
    );
}

Props flow one way: controller → component. There is no need to define API endpoints, serializers, or fetch logic for standard page loads.

Inertia v2 Features Worth Using

Deferred Props

For data that is expensive to compute and not needed for the initial render:

// Controller
return Inertia::render('Dashboard', [
    'user'     => $user,
    'stats'    => Inertia::defer(fn () => $this->getStats()),
    'activity' => Inertia::defer(fn () => $this->getActivity(), 'secondary'),
]);

// React component
import { Deferred } from '@inertiajs/react';

<Deferred data="stats" fallback={<p>Loading stats...</p>}>
    {({ stats }) => <StatsChart data={stats} />}
</Deferred>

stats loads in a second request after the page renders. Props in the same group string ('secondary') are fetched in a single batched request.

Prefetching

import { Link } from '@inertiajs/react';

// Prefetch after 75ms hover
<Link href="/users" prefetch>Users</Link>

// Prefetch on mount (useful for near-certain navigations)
<Link href="/dashboard" prefetch="mount">Dashboard</Link>

Inertia v3 Additions

No More Axios

Inertia v3 ships its own built-in XHR client. Axios is no longer a required dependency, saving approximately 15 KB gzipped from your bundle. If you rely on Axios interceptors for token refresh or request logging, add Axios back as a peer dependency — but most projects do not need it.

useHttp for Non-Navigation Requests

Inertia v3 introduces useHttp for HTTP calls that should not trigger page navigation:

import { useHttp } from '@inertiajs/react';

function SubscribeForm() {
    const { post, processing, errors } = useHttp();

    const submit = (e) => {
        e.preventDefault();
        post('/subscribe', { email: e.target.email.value });
    };

    return (
        <form onSubmit={submit}>
            <input name="email" type="email" />
            {errors.email && <p>{errors.email}</p>}
            <button disabled={processing}>Subscribe</button>
        </form>
    );
}

Optimistic Updates

import { router } from '@inertiajs/react';

function toggleTodo(id) {
    router.patch(`/todos/${id}`, { completed: true }, {
        optimistic: (page) => {
            page.props.todos = page.props.todos.map(t =>
                t.id === id ? { ...t, completed: true } : t
            );
        },
    });
    // If the server returns a non-2xx response, the optimistic change is automatically rolled back
}

ESM-Only Output

Inertia v3 packages are ESM only. CommonJS require('@inertiajs/react') will break. Ensure your Vite config does not force CJS output.

CSRF and Auth

Inertia handles CSRF transparently when used with Laravel. The HandleInertiaRequests middleware automatically shares the CSRF token, and Inertia's client attaches it to every request. You do not need to manually include _token in form submissions.

A token mismatch produces a 419 response. Common cause: the session has expired between page load and form submission. Handle this in the Inertia response handler by redirecting to a re-login page.

Common Mistakes

Passing Eloquent models with too many fields. Every prop you pass is serialized to JSON and embedded in the page. Use API resources or ->only() to limit what leaves the server:

// Avoid
'product' => $product,

// Prefer
'product' => $product->only('id', 'name', 'price', 'slug'),

Choosing Inertia for CRUD-heavy admin panels without React/Vue expertise. Inertia adds a JavaScript build step, component structure, and client-side state management overhead. If your team is PHP-native and the UI is primarily forms and tables, Livewire 4 will ship faster with less complexity.

Forgetting that Inertia v3 requires Laravel 11. Upgrading the npm packages without checking the server adapter version will break the app silently.

Using router.visit() for everything. Inertia's router.visit() triggers a full Inertia page visit including scroll reset and component remount. For in-page data mutations (toggle, delete, update), use router.patch(), router.put(), or router.delete() — these preserve the current page component and merge updated props.

No shared data caching. The HandleInertiaRequests middleware share() method runs on every request. Avoid expensive queries there. Cache shared data (authenticated user, permissions, navigation items) in the session or a short-lived cache.

When Inertia Makes Sense (and When It Does Not)

Use Inertia when	Prefer Livewire when
Your team knows React or Vue	Your team is primarily PHP
You need complex client-side state	The UI is mostly forms and lists
You want the full npm ecosystem	You want minimal JS tooling
You have rich data visualizations	You are building an admin panel
You need SSR for public pages	Server-round-trip latency is acceptable

Inertia is the "modern monolith" pattern: you keep Laravel's routing, auth, and data layer, but your frontend developers work in React or Vue with full HMR, TypeScript support, and component tooling — without maintaining a separate SPA deployment.

Verifying the Setup

After scaffolding, confirm Inertia is wiring correctly:

# Run the Laravel dev server
php artisan serve

# In a second terminal, run Vite
npm run dev

Open the browser DevTools Network tab. Navigate between pages using <Link> components. Subsequent navigations should show XHR requests returning application/json with a X-Inertia: true response header — not full HTML. If you see full HTML on every navigation, the HandleInertiaRequests middleware is not registered.

For automated testing, use Inertia's test helpers:

use Inertia\Testing\AssertableInertia as Assert;

test('products index renders correctly', function () {
    $this->get('/products')
        ->assertInertia(fn (Assert $page) => $page
            ->component('Products/Index')
            ->has('products.data', 20)
        );
});

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Finding and Fixing the Eloquent N+1 Problem

Sumeet Shroff — Mon, 31 Aug 2026 10:01:07 +0000

Finding and Fixing the Eloquent N+1 Problem

You deploy a feature, and within days the DBA flags your page as a top query offender. A single request is issuing 101 queries where one would do. This is the N+1 problem — the most common performance mistake in Eloquent applications and, fortunately, one of the most straightforward to fix once you know where to look.

Prerequisites

Laravel 10.x or higher (examples verified against Laravel 12 / PHP 8.2+)
Familiarity with Eloquent models and basic relationships
A local dev environment running
Composer dev dependencies for detection tooling (details below)

What N+1 Actually Looks Like in Practice

Consider a blog listing page. The controller loads posts and the Blade (or API response) iterates them:

// Controller
$posts = Post::all();

// Blade / resource loop
foreach ($posts as $post) {
    echo $post->author->name; // relationship access inside the loop
}

Eloquent lazy-loads author on first access for each $post. With 100 posts, that is:

1 query: SELECT * FROM posts
100 queries: SELECT * FROM users WHERE id = ? — one per post

Total: 101 queries. The pattern scales linearly with the record count, which means it is invisible during local testing with five seed records and catastrophic in production with fifty thousand.

Step 1 — Detect the Problem Before You Fix It

Fix N+1 issues you can see. Three approaches, from lightest to most automated:

DB::enableQueryLog() — Zero-Dependency Inspection

use Illuminate\Support\Facades\DB;

DB::enableQueryLog();

$posts = Post::all();
foreach ($posts as $post) {
    $_ = $post->author->name;
}

$queries = DB::getQueryLog();
echo count($queries); // 101 with 100 posts
dd($queries); // inspect full SQL + bindings

This is the simplest approach and works in every environment with no package installation.

Model::preventLazyLoading() — Throw Early in Development

Added to app/Providers/AppServiceProvider.php:

use Illuminate\Database\Eloquent\Model;

public function boot(): void
{
    Model::preventLazyLoading(!app()->isProduction());
}

With this in place, any lazy relationship access throws a LazyLoadingViolationException during local development:

Illuminate\Database\LazyLoadingViolationException:
Attempted to lazy load [author] on model [App\Models\Post]
but lazy loading is disabled.

This is the most effective way to catch N+1 issues before they ship. It does not block lazy loading in production — that is intentional so that third-party packages that rely on lazy loading do not break. Complete your with() calls and re-test; the exception disappears.

beyondcode/laravel-query-detector — Real-Time Auto-Detection

composer require beyondcode/laravel-query-detector --dev

After installation and publishing the config (php artisan vendor:publish --provider="BeyondCode\QueryDetector\QueryDetectorServiceProvider"), the package automatically detects N+1 patterns in real-time and can surface them via the browser console, Debugbar, or log file. This is the least invasive option for teams that want passive monitoring rather than hard exceptions.

Step 2 — Fix with Eager Loading

Eager loading with with() is the primary solution. It replaces the per-iteration lazy load with a single additional query, regardless of how many records the initial query returns.

// Before — 101 queries for 100 posts
$posts = Post::all();

// After — 2 queries total
$posts = Post::with('author')->get();

Eloquent now runs:

SELECT * FROM posts
SELECT * FROM users WHERE id IN (1, 2, 3, ...) — all author IDs in one IN clause

Nested Relationships

Chain dot-notation to eager load through multiple levels:

// Loads posts → comments → comment authors in 3 total queries
$posts = Post::with('comments.author')->get();

Constrained Eager Loading

Filter the eager-loaded relationship using a closure:

$posts = Post::with(['comments' => function ($query) {
    $query->where('approved', true)->orderBy('created_at', 'desc');
}])->get();
// $post->comments only contains approved comments, still in 2 queries

Column Selection — Avoid SELECT * Overhead

When eager loading, always specify only the columns you actually need. This is particularly important when the related model has large text or JSON columns:

// Bad — loads all user columns for every post (including password hash, settings JSON, etc.)
$posts = Post::with('author')->get();

// Good — only the columns the view uses
$posts = Post::select('id', 'title', 'user_id')
    ->with(['author:id,name,avatar_url'])
    ->get();

Critical rule: When constraining eager-loaded columns using the colon syntax, you must always include both the primary key (id) and the foreign key (user_id on the parent). If you omit the primary key on the relation, Eloquent cannot match related records back to their parents, and $post->author will always be null.

Step 3 — Always-Eager Relationships with $with

If a relationship is needed on virtually every query for a model, define it on the model directly:

class Post extends Model
{
    protected $with = ['author'];
}

Every Post::query() now eager loads author automatically. Override on a per-query basis with without():

// Suppresses the automatic eager load for this query only
$posts = Post::without('author')->get();

Use $with judiciously. If a relationship is only needed in a few contexts, $with adds unnecessary JOIN/subquery overhead to every other query. Prefer explicit with() at the call site unless the relationship is genuinely used in the majority of code paths.

Common Variant: The Hidden N+1 Inside a Loop Condition

N+1 does not always look like $post->author->name. It can hide inside conditionals and method calls:

// Still N+1 — accessing relationship inside an if
foreach ($posts as $post) {
    if ($post->tags->count() > 2) {
        // render tagged post differently
    }
}

// Fix — eager load tags
$posts = Post::with('tags')->get();
foreach ($posts as $post) {
    if ($post->tags->count() > 2) { ... }
}

Another common variant: loading one relationship with with() but accessing a different, non-eager-loaded relationship inside the same loop:

// Only 'author' is eager loaded — accessing 'category' still causes N+1
$posts = Post::with('author')->get();
foreach ($posts as $post) {
    echo $post->category->name; // N+1 on category
}

// Fix — eager load both
$posts = Post::with('author', 'category')->get();

When Boolean Presence Is All You Need: withExists()

A common pattern is checking whether a relationship exists rather than loading its data. Using withCount() for this works but fires a COUNT(*) subquery for each row. withExists() is more efficient — it generates a cheaper EXISTS subquery instead:

// withCount — generates COUNT(*) subquery, returns integer
$posts = Post::withCount('comments')->get();
// $post->comments_count === 5

// withExists — generates EXISTS subquery, returns boolean
$posts = Post::withExists('comments')->get();
// $post->comments_exists === true
// Use this when you only need to know if comments exist, not how many

Both run as subqueries within the main SELECT, not as separate queries. Pick withExists() whenever the count itself is not needed.

Large Dataset Caveat: cursor() Does Not Support with()

For iterating large result sets, Laravel offers cursor(), which uses a single unbuffered query and hydrates one model at a time — approximately 1.87 MB for 300,000 rows versus batch-size times model-size for chunk().

However, cursor() does not support eager loading with with(). Chaining them does not throw an error, but relationship access inside the loop is lazy-loaded, which puts you squarely back in N+1 territory:

// WRONG — cursor() + relationship access = N+1, no error thrown
foreach (Post::cursor() as $post) {
    echo $post->author->name; // still N+1
}

// Use chunk() instead when you need eager loading on large datasets
Post::with('author')->chunk(500, function ($posts) {
    foreach ($posts as $post) {
        echo $post->author->name; // safe — author is eager loaded per chunk
    }
});

If memory usage is critical and you genuinely cannot use chunk(), restructure the loop to avoid relationship access — preload the related data as a keyed collection before the cursor loop:

// Preload all authors as a lookup map
$authors = User::pluck('name', 'id'); // keyed by user_id

foreach (Post::cursor() as $post) {
    echo $authors[$post->user_id]; // O(1) array lookup, no DB query
}

Testing That You Actually Fixed It

Do not rely solely on visual confirmation. Write a feature test that asserts the query count:

public function test_post_listing_does_not_cause_n_plus_1(): void
{
    // Create 10 posts each with an author
    $users = User::factory()->count(10)->create();
    Post::factory()
        ->count(10)
        ->sequence(fn ($seq) => ['user_id' => $users[$seq->index % 10]->id])
        ->create();

    $queryCount = 0;
    DB::listen(function () use (&$queryCount) {
        $queryCount++;
    });

    // Simulate the controller
    $posts = Post::with('author')->get();
    foreach ($posts as $post) {
        $_ = $post->author->name;
    }

    // Should be exactly 2 queries: one for posts, one for authors
    $this->assertEquals(2, $queryCount);
}

This test will fail if someone later removes with('author') and reintroduces N+1. Add it to CI and it becomes a permanent guard.

Tradeoffs and Limitations

Eager loading vs lazy loading — memory cost. Eager loading trades multiple small queries for a single larger one. If the related dataset is huge (e.g., a post with 50,000 comments), eager loading all of them into memory is worse than lazy loading. Use constrained eager loading with limit() or paginate the relationship in those cases.

preventLazyLoading() in production. The guard only activates when !app()->isProduction() by default. Running it unconditionally in production may break third-party packages that use lazy loading — keep it development-only.

withExists() and withCount() — subquery cost. Both add a correlated subquery per row to the main SELECT. For large tables, ensure foreign key columns are indexed or these subqueries can be slow.

$with on models. Always-eager relationships add overhead to every query. If a relationship is only needed in a minority of code paths, prefer explicit with() at the call site.

For a broader look at query optimization in Laravel — covering upsert() for bulk writes, aggregate subqueries, large-dataset strategies, and vector search in Laravel 13 — see Eloquent and Database Optimization: Relationships, N+1, Upserts, and Vector Search.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Documenting Laravel APIs with Scramble

Sumeet Shroff — Mon, 31 Aug 2026 05:36:18 +0000

Documenting Laravel APIs with Scramble

If you have ever shipped a Laravel API and watched a frontend developer open Postman to reverse-engineer your endpoints, you know the pain of missing documentation. The traditional solution—Swagger annotations—requires you to decorate every controller method with dozens of lines of PHPDoc that drift out of sync the moment someone renames a parameter. Scramble takes a different approach: it reads your existing code and generates an OpenAPI 3.1 spec automatically, with zero annotations required.

This article walks through installing Scramble on a Laravel 11 or 12 project, what it infers automatically, how to fill in the gaps, and the tradeoffs you should know before adopting it in production.

Prerequisites: Laravel 11 or 12, PHP 8.2+, Composer. If you have not scaffolded your API routes yet, run php artisan install:api first—Laravel 11/12 no longer ships routes/api.php by default. See Building Production-Ready APIs with Laravel for the full setup walkthrough.

Why Scramble Instead of Swagger Annotations

The darkaonline/l5-swagger package (and its predecessor swagger-php) requires PHPDoc blocks like this on every endpoint:

/**
 * @OA\Get(
 *     path="/api/v1/posts",
 *     summary="List posts",
 *     tags={"Posts"},
 *     @OA\Parameter(name="page", in="query", ..."),
 *     @OA\Response(response=200, description="Success", ...)
 * )
 */
public function index(): AnonymousResourceCollection
{
    // ...
}

That annotation block is longer than many controller methods. It also does not tell you when the annotation is wrong—if you change the response shape but forget to update @OA\Response, nobody finds out until a consumer hits a 500.

Scramble instead parses your controller return types, FormRequest rules, Eloquent API Resources, and route definitions. If your code is typed correctly, the documentation is correct by construction.

Installation

composer require dedoc/scramble

Scramble auto-discovers itself via Laravel's package discovery. No service provider registration is needed. After installation, two routes are available:

/docs/api — Interactive Stoplight Elements UI
/docs/api.json — Raw OpenAPI 3.1 JSON spec

Both routes are restricted to the local environment by default. To expose them in staging or production, publish the config and adjust the middleware array:

php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider"

This creates config/scramble.php:

return [
    'api_path' => 'api',
    'api_domain' => null,
    'info' => [
        'version' => env('API_VERSION', '1.0.0'),
        'description' => '',
    ],
    'middleware' => [
        'web',
        RestrictedDocsAccess::class, // ships with Scramble
    ],
    'extensions' => [],
];

To restrict docs to authenticated users in production, replace RestrictedDocsAccess with your own middleware or gate check.

What Scramble Infers Automatically

Route Parameters

Given a route like Route::get('/posts/{post}', [PostController::class, 'show']), Scramble reads the route binding and produces the correct {post} path parameter in the spec. If you use model binding (public function show(Post $post)), it infers the parameter type from the model's primary key type.

Request Body from FormRequest

Scramble reads rules() from a FormRequest and maps Laravel validation rules to JSON Schema types:

class StorePostRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'title'    => ['required', 'string', 'max:255'],
            'content'  => ['required', 'string'],
            'status'   => ['required', 'in:draft,published'],
            'tags'     => ['array'],
            'tags.*'   => ['string', 'max:50'],
        ];
    }
}

Scramble converts in:draft,published to an OpenAPI enum, infers tags as an array of strings, and marks title, content, and status as required. You get accurate request body documentation without writing a single annotation.

Response Shape from API Resources

When a controller method returns a typed Resource or ResourceCollection, Scramble resolves the return type and inspects the toArray() method:

// app/Http/Resources/PostResource.php
class PostResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id'             => $this->id,
            'title'          => $this->title,
            'status'         => $this->status,
            'author'         => new UserResource($this->whenLoaded('author')),
            'comments_count' => $this->whenCounted('comments'),
            'created_at'     => $this->created_at->toISOString(),
        ];
    }
}

Scramble picks up the field names and their types. It handles whenLoaded() by marking the nested resource as nullable/optional, which is accurate—the field only appears when the relationship is eager-loaded.

HTTP Status Codes

Scramble infers the success status code from what the controller returns. A response()->json([], 201) produces a 201 in the spec. Validation failures via FormRequest automatically produce a 422 response schema showing the standard Laravel error envelope.

Filling the Gaps with Attributes

Scramble cannot infer everything from code structure alone. For cases where inference falls short, it provides PHP 8 attributes instead of PHPDoc annotations.

Describe an Endpoint

use Dedoc\Scramble\Attributes\OperationId;
use Dedoc\Scramble\Attributes\Summary;
use Dedoc\Scramble\Attributes\Description;

#[Summary('Create a new post')]
#[Description('Stores a draft or published post. Requires the `posts.create` permission.')]
public function store(StorePostRequest $request): PostResource
{
    $post = Post::create($request->validated());
    return new PostResource($post);
}

Document Query Parameters

Query parameters that are not in a FormRequest (filters, sort options, cursor values) need explicit documentation:

use Dedoc\Scramble\Attributes\QueryParameter;

#[QueryParameter('sort', description: 'Sort field. Allowed: created_at, title.', type: 'string', example: 'created_at')]
#[QueryParameter('direction', description: 'Sort direction.', enum: ['asc', 'desc'], default: 'desc')]
public function index(Request $request): AnonymousResourceCollection
{
    $posts = Post::with(['author'])
        ->withCount('comments')
        ->orderBy($request->input('sort', 'created_at'), $request->input('direction', 'desc'))
        ->paginate(20);

    return PostResource::collection($posts);
}

Exclude Internal Endpoints

Not every route belongs in public documentation. Tag internal or admin-only endpoints to exclude them:

use Dedoc\Scramble\Attributes\ExcludeFromDocs;

#[ExcludeFromDocs]
public function internalMetrics(): JsonResponse
{
    // ...
}

Versioned APIs

If you are running versioned route groups (the recommended approach for production APIs), configure Scramble to point at a specific API prefix:

// config/scramble.php
'api_path' => 'api/v1',

For multiple versions with separate documentation UIs, register additional Scramble instances in a service provider:

// app/Providers/AppServiceProvider.php
use Dedoc\Scramble\Scramble;
use Dedoc\Scramble\Support\Generator\OpenApi;
use Dedoc\Scramble\Support\Generator\SecurityScheme;

public function boot(): void
{
    Scramble::registerApi('v2', [
        'api_path' => 'api/v2',
        'info' => ['version' => '2.0.0'],
    ]);
}

This produces separate docs at /docs/v2 without conflating the two versions.

Authentication in the Spec

Scramble does not automatically detect that your routes are behind auth:sanctum. Register the security scheme manually:

// app/Providers/AppServiceProvider.php
use Dedoc\Scramble\Scramble;
use Dedoc\Scramble\Support\Generator\OpenApi;
use Dedoc\Scramble\Support\Generator\SecurityScheme;

public function boot(): void
{
    Scramble::configure()
        ->withDocumentTransformers(function (OpenApi $openApi) {
            $openApi->secure(
                SecurityScheme::http('bearer')
            );
        });
}

This adds a BearerAuth security requirement globally. If some routes are public, apply ->withoutSecurity() per-route using the attribute approach.

Exporting the Spec for CI and Postman

Generate a static JSON spec on demand:

php artisan scramble:export

This writes storage/api-docs/api.json by default. You can commit this file and fail the CI build if it changes unexpectedly, which forces developers to update documentation alongside code:

# .github/workflows/api-docs.yml (pseudocode)
- run: php artisan scramble:export
- run: git diff --exit-code storage/api-docs/api.json

Import storage/api-docs/api.json directly into Postman using File > Import to generate a full collection with examples.

Limitations and Tradeoffs

What Scramble does not infer well:

Dynamic response shapes built with conditional logic inside toArray() beyond whenLoaded() and whenCounted(). If you use $this->when(someCondition(), ...) with complex expressions, the inferred schema may be incomplete.
Endpoints that return raw response()->json([...]) with an inline array instead of a typed Resource. Scramble cannot inspect an anonymous array literal for types.
Polymorphic relationships inside Resources. Scramble cannot resolve which of several model types might appear inside a morphTo() relationship without a hint.
Custom exception handlers that return non-standard JSON envelopes. If you override Handler::render(), Scramble may not know about your custom error shape.

Annotation fatigue is not zero. Scramble eliminates most annotations but not all. Query parameters, custom response descriptions, and security declarations still require attributes or document transformers.

The docs UI is not customisable without overriding the view. If your team requires Swagger UI instead of Stoplight Elements, you will need to point a separate Swagger UI instance at the generated JSON endpoint.

Scramble vs. l5-swagger: Scramble wins on maintenance cost (no annotation drift), accuracy (spec is derived from running code), and setup speed. l5-swagger wins when you need fine-grained control over every schema detail or are working with a legacy codebase that lacks return-type declarations and FormRequest classes.

Verifying Your Documentation

After setup, open /docs/api in your browser and cross-check:

Every route in routes/api.php appears in the sidebar.
FormRequest fields match what the endpoint actually accepts.
Resource fields match the database columns and casts.
Status codes are correct (201 for creation, 204 for deletion, 422 for validation).
Bearer auth appears on protected routes.

For automated verification, use Spectral to lint the exported spec against the OpenAPI 3.1 ruleset:

npx @stoplight/spectral-cli lint storage/api-docs/api.json --ruleset @stoplight/spectral-owasp-ruleset

The OWASP ruleset flags common API security issues (missing authentication declarations, overly permissive schemas) directly from the spec file.

Common Mistakes

Not typing controller return values. Scramble relies on PHP return type declarations. public function index() without a return type yields an empty response schema. Add AnonymousResourceCollection or PostResource return types everywhere.
Using response()->json($data) instead of Resources. Once you bypass the Resource layer, Scramble cannot inspect the shape. Reserve raw JSON responses for simple cases and document them with attributes.
Exposing the docs route in production without authentication. The default RestrictedDocsAccess middleware only allows local access. Wrap the docs routes with auth:sanctum or an IP allowlist before staging deployment.
Forgetting to re-export after schema changes. If your CI pipeline imports a stale spec into Postman or a mock server, consumers test against outdated contracts. Automate php artisan scramble:export in your deployment pipeline.
Running Scramble on routes that include Livewire or Inertia endpoints. Set api_path precisely to your API prefix so Scramble does not attempt to parse server-rendered page routes.

Scramble is the lowest-friction path to accurate OpenAPI documentation for Laravel APIs. It will not eliminate every annotation, but it eliminates the most tedious ones—the ones that duplicate information already present in your types, FormRequests, and Resource classes.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Filtering Laravel APIs with Spatie Query Builder

Sumeet Shroff — Mon, 31 Aug 2026 04:41:49 +0000

If you have spent any time building Laravel APIs, you have almost certainly written a controller method that looks like this:

public function index(Request $request)
{
    $query = Post::query();

    if ($request->has('status')) {
        $query->where('status', $request->status);
    }
    if ($request->has('author_id')) {
        $query->where('author_id', $request->author_id);
    }
    if ($request->has('sort')) {
        $query->orderBy($request->sort, $request->get('direction', 'asc'));
    }

    return PostResource::collection($query->paginate(20));
}

This works for two filters. At ten filters it becomes a maintenance problem. At twenty, it's a bug surface. Spatie Laravel Query Builder replaces that entire pattern with a declarative, tested, composable API that scales cleanly.

This article focuses narrowly on Spatie Query Builder — installation through production patterns. For the broader context of Laravel API architecture (versioning, Sanctum auth, rate limiting, N+1 prevention), see Building Production-Ready APIs with Laravel.

Prerequisites

Laravel 11 or 12 (PHP 8.2 minimum)
spatie/laravel-query-builder ^6.x (supports Laravel 11/12)
Composer installed
Basic familiarity with Eloquent and API Resources

Install the package:

composer require spatie/laravel-query-builder

No service provider registration is required — the package auto-discovers itself.

The Core Concept

Spatie Query Builder wraps an Eloquent query and maps incoming HTTP query parameters to allowed filters, sorts, and includes. Only parameters you explicitly allow are applied. Everything else is silently ignored, which prevents query-injection style attacks where a client passes arbitrary column names.

The basic structure:

use Spatie\QueryBuilder\QueryBuilder;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\AllowedSort;
use Spatie\QueryBuilder\AllowedInclude;

$posts = QueryBuilder::for(Post::class)
    ->allowedFilters([...])
    ->allowedSorts([...])
    ->allowedIncludes([...])
    ->paginate(20);

The client controls the query via URL parameters:

GET /api/v1/posts?filter[status]=published&sort=-created_at&include=author

Filters in Depth

Exact Filters

The simplest filter matches a column exactly:

->allowedFilters(['status', 'author_id'])

A request to ?filter[status]=published translates to WHERE status = 'published'.

Partial (LIKE) Filters

For search-style filtering:

use Spatie\QueryBuilder\AllowedFilter;

->allowedFilters([
    AllowedFilter::partial('title'),
])

?filter[title]=laravel becomes WHERE title LIKE '%laravel%'. Be aware this disables index usage on most database engines — add a full-text index or move to a search engine (Meilisearch, Typesense) if the table is large.

Scope Filters

Scope filters delegate the filtering logic to a named Eloquent scope on the model:

// Post model
public function scopePublishedAfter(Builder $query, string $date): Builder
{
    return $query->where('published_at', '>=', $date);
}

// Controller
->allowedFilters([
    AllowedFilter::scope('published_after'),
])

Request: ?filter[published_after]=2026-01-01

Scope filters are the cleanest way to encapsulate complex WHERE logic (date ranges, geographic bounding boxes, status machines) without polluting the controller.

Custom Filters

When you need full control — joining another table, conditional subqueries, or multi-column logic — implement \Spatie\QueryBuilder\Filters\Filter:

use Spatie\QueryBuilder\Filters\Filter;
use Illuminate\Database\Eloquent\Builder;

class TagFilter implements Filter
{
    public function __invoke(Builder $query, mixed $value, string $property): void
    {
        $tags = is_array($value) ? $value : explode(',', $value);

        $query->whereHas('tags', function (Builder $q) use ($tags) {
            $q->whereIn('slug', $tags);
        });
    }
}

// Controller
->allowedFilters([
    AllowedFilter::custom('tags', new TagFilter()),
])

Request: ?filter[tags]=php,laravel

Filter Defaults

You can supply a default value so that the filter applies even when the client does not pass it:

AllowedFilter::exact('status')->default('published')

This is useful for endpoints that should only surface active records by default, with an opt-in to see all records for admin consumers.

Sorting

Allowed sorts map request parameter values to column names:

->allowedSorts([
    'title',
    'created_at',
    AllowedSort::field('newest', 'created_at'),
])

The client prefixes a column name with - for descending order:

?sort=-created_at        → ORDER BY created_at DESC
?sort=title              → ORDER BY title ASC
?sort=newest             → ORDER BY created_at ASC (aliased)

Set a default sort so paginated responses are stable without a client-supplied sort:

->defaultSort('-created_at')

Without a default sort, paginate() on a large dataset produces non-deterministic page boundaries — records can appear on multiple pages or be skipped entirely as rows are inserted.

Eager-Loading Includes

Allowed includes let the client opt into relationship loading:

->allowedIncludes(['author', 'tags', 'comments.author'])

Request: ?include=author,tags

Behind the scenes this calls with(['author', 'tags']) on the query. Because the relationships are eager-loaded before the Resource layer runs, whenLoaded() in your API Resource works correctly:

// PostResource.php
public function toArray($request): array
{
    return [
        'id'     => $this->id,
        'title'  => $this->title,
        'author' => new UserResource($this->whenLoaded('author')),
        'tags'   => TagResource::collection($this->whenLoaded('tags')),
    ];
}

When author is not included, whenLoaded('author') returns MissingValue and the key is omitted from the response. No N+1. No accidental data exposure.

A Full Controller Example

namespace App\Http\Controllers\Api\V1;

use App\Http\Resources\PostResource;
use App\Models\Post;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\AllowedSort;
use Spatie\QueryBuilder\QueryBuilder;

class PostController
{
    public function index(): AnonymousResourceCollection
    {
        $posts = QueryBuilder::for(Post::class)
            ->allowedFilters([
                AllowedFilter::exact('status')->default('published'),
                AllowedFilter::exact('author_id'),
                AllowedFilter::partial('title'),
                AllowedFilter::scope('published_after'),
                AllowedFilter::custom('tags', new TagFilter()),
            ])
            ->allowedSorts([
                'title',
                AllowedSort::field('newest', 'created_at'),
            ])
            ->defaultSort('-created_at')
            ->allowedIncludes(['author', 'tags'])
            ->paginate(request()->integer('per_page', 20));

        return PostResource::collection($posts);
    }
}

This replaces 50+ lines of imperative if-blocks with a structure that is readable, testable in isolation, and extendable by adding a single line.

Common Mistakes

1. Using AllowedFilter::partial() on unindexed columns
LIKE queries with a leading wildcard (%term%) cannot use standard B-Tree indexes. For any table above a few thousand rows, either add a full-text index, limit the search to a prefix pattern (term%), or offload to a dedicated search service.

2. Allowing includes without thinking about depth
Nested includes like comments.author.profile can generate deep join trees. Audit every allowed include path — or cap depth using the package's allowedIncludes list and never use wildcards.

3. Omitting defaultSort()
Pagination without a stable sort order is broken by definition. Always set a default sort, ideally on an indexed column.

4. Filtering on non-guarded columns in custom filters
Custom Filter implementations receive the raw client-supplied value. Always validate or cast inside the implementation. Do not interpolate $value into raw SQL strings.

5. Not wrapping the QueryBuilder in a FormRequest
QueryBuilder handles the query-parameter side. It does not validate that filter[author_id] is an integer or that filter[published_after] is a valid date. Add a FormRequest alongside the QueryBuilder for input validation:

public function index(IndexPostRequest $request): AnonymousResourceCollection
{
    // $request->validated() runs before QueryBuilder reads the parameters
    ...
}

Limitations and Tradeoffs

Spatie Query Builder works on Eloquent queries. It does not integrate with raw DB::select() calls or Eloquent queries that have already been executed. If your endpoint returns data from a stored procedure or a complex multi-union query, you will need to handle filtering manually.

The filter[] bracket syntax is conventional for this library and matches PHP's native query-string parsing. However, some API clients and gateways (AWS API Gateway URL validation, certain proxies) require additional configuration to allow bracket characters in query parameters. Test your infrastructure with this syntax early.

Sorting by computed or aggregate columns (e.g., sort=comments_count) requires that the column is already selected or appended via withCount() on the base query before handing control to QueryBuilder. Use AllowedSort::field() to alias the aggregate:

$posts = QueryBuilder::for(
    Post::withCount('comments') // must be in the base query
)
->allowedSorts([
    AllowedSort::field('popularity', 'comments_count'),
])
->paginate(20);

Testing Filtered Endpoints

Feature tests against filtered endpoints are straightforward with Laravel's test helpers:

use Illuminate\Foundation\Testing\RefreshDatabase;

test('filters posts by status', function () {
    Post::factory()->create(['status' => 'published']);
    Post::factory()->create(['status' => 'draft']);

    $response = $this->actingAs($this->user, 'sanctum')
        ->getJson('/api/v1/posts?filter[status]=draft');

    $response->assertOk()
             ->assertJsonCount(1, 'data')
             ->assertJsonPath('data.0.status', 'draft');
});

test('ignores unknown filters', function () {
    Post::factory()->count(3)->create(['status' => 'published']);

    // 'unknown_column' is not in allowedFilters — should be ignored, not error
    $response = $this->actingAs($this->user, 'sanctum')
        ->getJson('/api/v1/posts?filter[unknown_column]=value');

    $response->assertOk()->assertJsonCount(3, 'data');
});

By default Spatie Query Builder ignores disallowed filters silently. If you want it to throw a 422 when an unknown filter is passed (useful for strict API clients), set 'throw_invalid_query_exceptions' => true in the config/query-builder.php file (publish it first with php artisan vendor:publish --provider="Spatie\QueryBuilder\QueryBuilderServiceProvider").

Summary

Spatie Query Builder solves a real, recurring Laravel API problem — complex, hand-rolled filtering logic — through a clean declarative interface. The key patterns:

Use exact and scope filters for most cases; reserve custom filters for complex multi-table logic
Always set a default sort on an indexed column
Combine allowedIncludes with whenLoaded() in API Resources to avoid N+1 queries
Validate raw input in a FormRequest — QueryBuilder applies filters but does not type-check them
Publish the config and enable throw_invalid_query_exceptions in strict consumer environments

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Building a Production REST API with Laravel

Sumeet Shroff — Fri, 28 Aug 2026 10:00:50 +0000

Building a Production REST API with Laravel

Prerequisites: PHP 8.2+, Composer, Laravel 12.x, Redis (for production rate limiting and queues), basic familiarity with Eloquent and routing.

Laravel 12 (released March 2025) is a maintenance release on top of the structural changes introduced in Laravel 11. If you are starting a new API project today, the setup steps are meaningfully different from what you may remember from Laravel 9 or 10. This article walks through the decisions and implementation steps that matter most when shipping a REST API to production — authentication strategy, resource transformation, rate limiting, CORS, versioning, and testing — without rehashing the basics.

Step 1: Scaffold the API Layer

In Laravel 11 and 12, routes/api.php is not present in a fresh installation. Running php artisan install:api creates the file, installs Sanctum, registers the throttle:api middleware on the api route group, and adds the EnsureFrontendRequestsAreStateful middleware.

php artisan install:api

If you genuinely need a full OAuth2 server — authorization code flows, client credentials for machine-to-machine, or token introspection for third-party developers — swap in Passport:

php artisan install:api --passport

For the vast majority of projects (own SPA, own mobile app, internal microservice), Sanctum is the correct choice. Passport adds migrations, encryption key management, and client administration overhead that you do not need for first-party consumers.

Security note: If you are on Passport 13.0.0–13.7.0, upgrade to 13.7.1+ immediately. CVE-2026-39976 (CVSS 7.1) allows a client_credentials JWT token to authenticate as a real user when the client ID integer matches a user's ID. See the official advisory.

Step 2: Version Your Routes from Day One

Retrofitting versioning after launch means coordinating client updates and maintaining dual routing indefinitely. The URL prefix strategy (/api/v1/, /api/v2/) is the most debuggable and cache-friendly approach.

// routes/api.php
use Illuminate\Support\Facades\Route;

Route::prefix('v1')->group(base_path('routes/api_v1.php'));
Route::prefix('v2')->group(base_path('routes/api_v2.php'));

Keep separate controller namespaces:

App\Http\Controllers\Api\V1\PostController
App\Http\Controllers\Api\V2\PostController

And separate Resource classes per version so V1 and V2 response shapes evolve independently. Sharing a Resource class across versions is a false economy — when V2 requires a renamed field, you will end up with conditionals that are harder to maintain than two clean files.

Step 3: Protect Routes with Sanctum

// routes/api_v1.php
use App\Http\Controllers\Api\V1\PostController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('posts', PostController::class);
    Route::get('/user', fn (Request $r) => $r->user());
});

For browser-based SPAs, use Sanctum's stateful (HttpOnly cookie) authentication — tokens stored in localStorage are vulnerable to XSS exfiltration. For mobile apps and CLI clients, use Sanctum API tokens stored in the device's secure keychain.

Step 4: Transform Responses with API Resources

Returning raw Eloquent models from controllers leaks internal field names, exposes timestamps in inconsistent formats, and makes it painful to add computed fields later. API Resources are the standard transformation layer.

php artisan make:resource PostResource

// app/Http/Resources/V1/PostResource.php
use Illuminate\Http\Resources\Json\JsonResource;

class PostResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id'             => $this->id,
            'title'          => $this->title,
            'author'         => new UserResource($this->whenLoaded('author')),
            'comments_count' => $this->whenCounted('comments'),
            'created_at'     => $this->created_at->toISOString(),
        ];
    }
}

Two methods worth understanding deeply:

whenLoaded('author') — only includes the relationship data if it was already eager-loaded. Without this, accessing $this->author inside toArray() fires a lazy-load query per resource item (N+1).
whenCounted('comments') — only includes the count if withCount('comments') was called on the query. Neither method triggers additional queries.

In the controller, eager-load everything the Resource needs:

// app/Http/Controllers/Api/V1/PostController.php
public function index(): AnonymousResourceCollection
{
    $posts = Post::with(['author', 'tags'])
        ->withCount('comments')
        ->paginate(20);

    return PostResource::collection($posts);
}

paginate() works well for small-to-medium datasets. For tables with millions of rows, switch to cursorPaginate() — it uses keyset pagination on an indexed column and does not degrade with OFFSET like paginate() does.

Step 5: Validate Inputs Safely

Always use a FormRequest and pass $request->validated() to model methods — never $request->all().

// app/Http/Requests/V1/StorePostRequest.php
use Illuminate\Contracts\Validation\Validator;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Http\Exceptions\HttpResponseException;

class StorePostRequest extends FormRequest
{
    public function authorize(): bool { return true; }

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

    protected function failedValidation(Validator $validator)
    {
        throw new HttpResponseException(
            response()->json([
                'success' => false,
                'errors'  => $validator->errors(),
            ], 422)
        );
    }
}

The failedValidation() override ensures API clients receive a consistent JSON envelope instead of Laravel's default 422 response format, which varies depending on the Accept header and exception handler configuration.

In the controller:

public function store(StorePostRequest $request): PostResource
{
    $post = Post::create($request->validated());
    return new PostResource($post->load('author'));
}

Never define $guarded = [] or call forceFill() on user-controlled input. Mass assignment attacks are entirely preventable — define $fillable explicitly on every model.

Step 6: Rate Limiting with Redis

In Laravel 11 and 12, rate limiters are configured in bootstrap/app.php (the Kernel.php approach from Laravel 10 is gone).

// bootstrap/app.php
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('api', function (Request $request) {
    return $request->user()
        ? Limit::perMinute(120)->by($request->user()->id)
        : Limit::perMinute(30)->by($request->ip());
});

This applies automatically to all api.php routes via the throttle:api middleware registered during php artisan install:api.

Critical: in production, set CACHE_DRIVER=redis. Using the file or database cache driver for rate limiting creates race conditions under concurrent load and introduces disk I/O bottlenecks. The file driver also does not share state across multiple application servers.

Step 7: Configure CORS Correctly

Laravel handles CORS natively via Illuminate\Http\Middleware\HandleCors. Edit config/cors.php:

return [
    'paths'                => ['api/*'],
    'allowed_methods'      => ['*'],
    'allowed_origins'      => [env('FRONTEND_URL', 'https://app.example.com')],
    'allowed_headers'      => ['Content-Type', 'Authorization', 'X-Requested-With'],
    'supports_credentials' => true,
    'max_age'              => 86400,
];

Do not set allowed_origins to ['*'] with supports_credentials => true. Browsers reject credentialed requests to wildcard origins (CORS spec requirement) and this configuration is a security misconfiguration regardless.

Step 8: Prevent N+1 Queries

Add this to AppServiceProvider::boot() to throw an exception on lazy-loaded relationships in non-production environments:

// app/Providers/AppServiceProvider.php
use Illuminate\Database\Eloquent\Model;

public function boot(): void
{
    Model::preventLazyLoading(! app()->isProduction());
}

This catches N+1 issues during development and staging before they reach production. Pair it with withCount() and with() calls in every controller method that returns a collection.

Step 9: Write Feature Tests

Test the HTTP contract, not implementation details. Laravel's actingAs() with the 'sanctum' guard makes authenticated API tests straightforward:

// tests/Feature/Api/V1/PostTest.php
use Illuminate\Foundation\Testing\RefreshDatabase;

test('authenticated user can create a post', function () {
    $user = User::factory()->create();

    $response = $this->actingAs($user, 'sanctum')
        ->postJson('/api/v1/posts', [
            'title'   => 'Hello World',
            'content' => 'Body text',
        ]);

    $response->assertStatus(201)
             ->assertJsonStructure(['data' => ['id', 'title']]);
});

test('unauthenticated request returns 401', function () {
    $this->postJson('/api/v1/posts', ['title' => 'x'])
         ->assertUnauthorized();
});

test('validation rejects missing content', function () {
    $user = User::factory()->create();

    $this->actingAs($user, 'sanctum')
         ->postJson('/api/v1/posts', ['title' => 'No content'])
         ->assertStatus(422)
         ->assertJsonPath('success', false)
         ->assertJsonStructure(['errors' => ['content']]);
});

Use RefreshDatabase to reset state between tests. Test the 422 envelope shape explicitly — your failedValidation() override is part of the API contract.

Common Mistakes Checklist

Mistake	Fix
Skipping `php artisan install:api`	No `routes/api.php` exists in L11/L12 fresh installs
`$request->all()` in `Model::create()`	Use `$request->validated()` always
`APP_DEBUG=true` in production	Full stack traces leak in JSON error responses
`allowed_origins: ['*']` with credentials	Browsers reject it; enumerate origins explicitly
File/database cache for rate limiting	Use Redis; file driver has race conditions under load
Missing `whenLoaded()` in Resources	Every resource item triggers a lazy-load query (N+1)
No versioning from day one	Retrofitting `/api/v2/` after launch is painful
Passport 13.0.0–13.7.0 with `client_credentials`	CVE-2026-39976 — upgrade to 13.7.1+

Production Deployment Checklist

APP_DEBUG=false and APP_ENV=production in .env
CACHE_DRIVER=redis, QUEUE_CONNECTION=redis, SESSION_DRIVER=redis
Rotate APP_KEY before first deploy (invalidates sessions and signed URLs)
Run composer audit to check installed packages against the PHP Security Advisories Database
Configure Horizon with named queues (critical, default, emails) and --max-jobs + --max-time flags on workers to cap memory drift
Set secure flag to true on cookies and enforce HTTPS with HSTS headers

For a broader look at authentication strategies, pagination patterns, and Octane configuration for high-throughput APIs, see Building Production-Ready APIs with Laravel.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Livewire 4 Patterns for Interactive Laravel Interfaces

Sumeet Shroff — Tue, 25 Aug 2026 10:01:04 +0000

Livewire 4 Patterns for Interactive Laravel Interfaces

Livewire 4.0 shipped on January 15, 2026, and the latest patch as of June 2026 is v4.3.1. If you are building interactive UIs inside Laravel Blade without reaching for a full JavaScript framework, this release changes what is practical — not just what is possible.

This post focuses on five specific patterns: Islands for isolated re-renders, async actions to unblock parallel requests, the corrected wire:model modifier chain, SPA-like navigation with wire:navigate, and CSP-safe configuration. Each section covers the correct usage, the common mistake, and the tradeoff.

For the broader frontend landscape (Inertia.js, React, Vue, Alpine.js, and how to choose between them), see Modern Laravel Frontends: Livewire 4, Inertia, React, Vue, and Alpine.js.

Prerequisites: Laravel 11+, PHP 8.2+, Livewire v4.3.1 (composer require livewire/livewire:^4.0).

Pattern 1 — Islands: Isolate Expensive Re-Renders

Livewire's default update model re-renders the entire component on every server round-trip. For simple CRUD forms this is fine. For components that mix a frequently-updated region (a live search box) with an expensive region (a paginated data table with complex joins), it is wasteful.

Livewire 4 introduces the @island directive. Wrapping a region in @island tells Livewire to treat that sub-region as an isolated render unit. Actions triggered inside an island only cause that island to re-render — the rest of the component is untouched.

{{-- resources/views/livewire/product-dashboard.blade.php --}}
<div>
    {{-- This region re-renders on its own update cycle --}}
    @island('search-results')
        <div>
            <livewire:product-search :query="$query" />
        </div>
    @endisland

    {{-- Refresh only the island, not the full component --}}
    <button wire:click.island="refreshSearch">Refresh results</button>

    {{-- This expensive region is NOT re-rendered when the island updates --}}
    <div class="mt-8">
        @include('partials.featured-products', ['products' => $featuredProducts])
    </div>
</div>

What this replaces: Creating a separate child Livewire component just for isolation. With islands you get isolated re-renders without the overhead of a full independent component lifecycle.

Common mistake: Leaving expensive query data outside the island boundary — it still runs on every full-component update. Use #[Lazy] or move the query inside the island's scope.

Tradeoff: Islands cannot be reused across Blade files. If you duplicate @island blocks, extract a proper child component instead.

Pattern 2 — Async Actions: Fire-and-Forget Without Blocking

In Livewire 3, every action was synchronous from the user's perspective — clicking one button queued its request, and the next interaction waited until the response came back. Livewire 4 adds an async modifier that decouples the HTTP request from the UI update cycle.

Two equivalent ways to mark an action as async:

{{-- Modifier on the wire:click directive --}}
<button wire:click.async="logActivity">Track</button>

<?php

namespace App\Livewire;

use Livewire\Component;
use Livewire\Attributes\Async;

class ProductCard extends Component
{
    // PHP attribute approach — keeps the Blade template clean
    #[Async]
    public function logActivity(): void
    {
        // Writes to analytics, sends to a queue, etc.
        // Does not block other wire:model.live inputs or clicks
        activity()->log('product-viewed');
    }

    public function render()
    {
        return view('livewire.product-card');
    }
}

When to reach for async: Logging, analytics, non-critical side effects, queue dispatching — anything where the user doesn't need the response to keep interacting.

When not to use it: Any action that modifies state the user immediately sees. Async actions don't guarantee execution order relative to synchronous ones — a race between async logActivity and synchronous updateCart can leave component state inconsistent.

Parallel requests in v4: wire:model.live fields now fire in parallel by default (v3 serialised them) — no change needed beyond upgrading.

Pattern 3 — The Corrected wire:model Modifier Chain

This is the Livewire 4 change most likely to silently break existing v3 components after an upgrade.

How it worked in v3:

{{-- v3: .blur meant "send a network request when the input loses focus" --}}
<input wire:model.blur="email">

How it works in v4:

{{-- v4: .blur now controls CLIENT-SIDE sync timing only --}}
{{-- This syncs the JS value on blur, but sends NO network request --}}
<input wire:model.blur="email">

{{-- v4: Add .live to trigger the actual network request --}}
{{-- Sends a request when the input loses focus --}}
<input wire:model.live.blur="email">

{{-- Send a request 300ms after the user stops typing --}}
<input wire:model.live.debounce.300ms="email">

{{-- Lazy — sync client value immediately, send request on blur --}}
<input wire:model.live.lazy="email">

Why it changed: In v4, the modifier chain follows a consistent two-layer model. The first layer is always the network timing (.live, .lazy, or nothing for deferred). The second layer is the client-side sync timing (.blur, .debounce, .throttle). The v3 shortcut conflated these two concerns, which caused edge cases when combining modifiers.

Upgrade checklist:

grep -rn 'wire:model\.blur\|wire:model\.change' resources/views/

Replace each hit with wire:model.live.blur or wire:model.live.change. Verify the network request fires at the expected time in the browser's Network tab.

Common mistake: Finding zero grep results and assuming the app is clean. wire:model with no modifier now defaults to deferred batch updates at form submission — review every bare wire:model, not just the ones that used .blur.

Pattern 4 — wire:navigate for SPA-Like Page Transitions

Livewire 4 ships a built-in SPA navigation mode. Adding wire:navigate to anchor tags replaces full-page browser navigation with a Livewire-managed fetch, a DOM swap, and browser history API updates.

{{-- Standard SPA navigation --}}
<a href="/dashboard" wire:navigate>Dashboard</a>

{{-- Prefetch the page after 75ms hover --}}
<a href="/products" wire:navigate.hover>Products</a>

{{-- Inside a nav partial used across all pages --}}
<nav>
    <a href="/" wire:navigate.hover>Home</a>
    <a href="/services" wire:navigate.hover>Services</a>
    <a href="/contact" wire:navigate.hover>Contact</a>
</nav>

What prefetch does: After the user hovers for 75ms, Livewire fetches the target page in the background. If the user then clicks, the page swap is near-instant because the HTML is already in memory. On slower connections — common on mobile networks in India — the perceived performance improvement is significant.

Alpine.js state across navigations: Alpine components are torn down on each wire:navigate swap. Mark persistent elements with x-persist (Alpine 3.x) or move global state to a Livewire persistent component.

Tradeoff vs. Inertia.js: wire:navigate gives SPA-like navigation with zero JS framework overhead. If your team is PHP-first and pages are Blade-driven, it covers most SPA UX needs. For rich client-side state (React hooks, Pinia stores), use Inertia instead.

Pattern 5 — CSP Safe Mode

Both Livewire and Alpine.js evaluate JavaScript expressions using new Function() by default. This violates a Content-Security-Policy header that disallows unsafe-eval — a header that provides meaningful XSS protection in production.

Livewire 4 adds a csp_safe flag in config/livewire.php. Setting it to true switches Livewire to a pre-compiled expression evaluator and — automatically — forces Alpine.js into its own CSP-safe evaluator as well.

<?php
// config/livewire.php

return [
    'csp_safe' => true,

    // ... other config
];

Your HTTP response headers can then include:

Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';

What breaks when you enable this: Alpine directives that use complex JS expressions ($event.detail.productId, window.myGlobalVar, ternary chains) will fail — the CSP-safe evaluator supports only a limited syntax subset.

grep -rn 'x-on\|x-bind\|@click\|:class' resources/views/ | grep -E '\$event\.detail|window\.'

Replace complex expressions with named Alpine methods in x-data, or move logic into Livewire actions called via wire:click.

Security note: This removes the unsafe-eval attack surface from the browser sandbox. For apps handling sensitive data or public-facing forms, the refactor cost is worth it.

Security: The Livewire 3 CVE You Cannot Ignore

If any of your applications are still on Livewire 3.x below 3.6.4, stop and upgrade before doing anything else.

CVE-2025-54068 (CVSS 9.2, CRITICAL): Unauthenticated remote code execution via Livewire v3 component property hydration. An attacker who can guess or obtain the Laravel APP_KEY can forge a signed payload and execute arbitrary code. Patched in Livewire 3.6.4. Livewire 4.x is not affected.

# Check your current Livewire version
composer show livewire/livewire | grep versions

# Upgrade Livewire 3 to the patched release
composer require livewire/livewire:^3.6.4

# Or upgrade to v4 (recommended for greenfield and early-stage projects)
composer require livewire/livewire:^4.0

If your APP_KEY was ever exposed in a repo or config file committed to version control, rotate it immediately — even after patching.

Testing Your Livewire 4 Components

Livewire 4 replaced Volt::test() with Livewire::test(). If you used Volt in v3, update every test file:

<?php

use Livewire\Livewire;
use App\Livewire\ProductSearch;

it('filters products when query is updated', function () {
    Livewire::test(ProductSearch::class)
        ->set('query', 'laptop')
        ->assertSee('MacBook Pro')
        ->assertDontSee('Office Chair');
});

it('logs activity asynchronously without blocking state', function () {
    // Async actions resolve before assertions in test context
    Livewire::test(ProductCard::class)
        ->call('logActivity')
        ->assertDispatched('activity-logged');
});

Verifying wire:navigate prefetch: Use Playwright or Dusk with network throttling. Hover a wire:navigate.hover link, wait 100ms, then click — navigation should complete in under 100ms because the page was prefetched.

Verifying islands: In the Network tab, trigger an island-scoped action and confirm only island HTML appears in the response diff, not the full component HTML.

Limitations Worth Knowing Before You Commit

Real-time push requires Laravel Echo. Neither Livewire polling nor wire:navigate provides WebSocket-based push. You need Laravel Echo + Pusher or Laravel Reverb for real-time data.
Complex client-side UIs hit the round-trip ceiling. Drag-and-drop interfaces, rich text editors, and data visualisation charts are better served by dedicated React or Vue libraries. Livewire's server round-trip model adds latency that pure client-side rendering avoids.
Islands cannot be composed like components. An @island block is inlined in one template. If you need the same isolation logic in three different Blade files, extract a child Livewire component instead.
CSP safe mode is all-or-nothing per application. There is no per-component toggle. Enabling it changes Alpine's evaluation mode globally.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Practical PHP Attributes Introduced for Laravel Applications

Sumeet Shroff — Tue, 25 Aug 2026 09:11:10 +0000

Practical PHP Attributes Introduced for Laravel Applications

PHP 8.0 introduced native attributes — a structured metadata syntax that replaces docblock annotations. Laravel 13 is the first Laravel release to lean into them at framework scale, shipping attribute support across 15+ framework locations. This article walks through every major attribute available in Laravel 13, explains when to use them, and calls out the traps developers fall into when adopting them.

Prerequisites

PHP 8.3 or higher (hard minimum for Laravel 13)
Laravel 13.x (composer require laravel/framework:^13.0)
Familiarity with Eloquent models, controllers, middleware, and jobs

For the full picture of what shipped in Laravel 13 beyond attributes, see Laravel 13: Features, Upgrade Guide, and Breaking Changes.

What PHP Attributes Actually Are

A PHP attribute is a structured piece of metadata you attach directly to a class, method, property, or parameter using #[...] syntax. Before PHP 8.0, developers used docblock annotations like @ORM\Column(type="string"). Those worked only if a library parsed the docblock at runtime. Native attributes are parsed by PHP itself — no string parsing required.

// Before (docblock annotations — library must parse these at runtime)
/**
 * @Table(name="posts")
 * @Fillable({"title", "body"})
 */
class Post extends Model {}

// After (native PHP attributes — parsed by the PHP engine)
#[Table('posts')]
#[Fillable('title', 'body')]
class Post extends Model {}

The difference matters: native attributes are faster to resolve, work with static analysis tools like PHPStan out of the box, and are visible in IDE autocompletion without special plugins.

Eloquent Model Attributes

The most widely used attributes in Laravel 13 live on Eloquent models. They replace a cluster of static properties that every model used to carry.

use Illuminate\Database\Eloquent\Attributes\Table;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Attributes\Cast;

#[Table('posts', primaryKey: 'post_id', incrementing: true, timestamps: true)]
#[Fillable('title', 'body', 'user_id', 'published_at')]
#[Hidden('deleted_at', 'internal_score')]
#[Cast('published_at', 'datetime')]
#[Cast('metadata', 'array')]
class Post extends Model {}

What each attribute replaces:

Attribute	Replaces
`#[Table('posts', primaryKey: 'id')]`	`$table`, `$primaryKey`, `$incrementing`, `$timestamps`
`#[Fillable('title', 'body')]`	`$fillable` array
`#[Hidden('secret')]`	`$hidden` array
`#[Cast('column', 'type')]`	`$casts` array

Important: Both Syntaxes Work

Attributes do not replace the property-based syntax. If you declare both $fillable and #[Fillable(...)] on the same model, the property wins. Pick one approach per model and stay consistent.

// This will NOT behave as expected — $fillable overrides #[Fillable]
#[Fillable('title')]
class Post extends Model {
    protected $fillable = ['title', 'body']; // body is accessible, but attribute is ignored
}

Controller and Routing Attributes

Controllers gain #[Middleware] and #[Authorize] attributes that move protection declarations out of the constructor and into the method signature.

use Illuminate\Routing\Attributes\Controllers\Middleware;
use Illuminate\Routing\Attributes\Controllers\Authorize;

#[Middleware('auth')]          // applies to every method in this controller
#[Middleware('verified')]      // stacked — both run
class PostController extends Controller
{
    public function index() {
        // auth + verified middleware runs here
    }

    #[Middleware('subscribed')]                         // method-level addition
    #[Authorize('create', [Post::class, 'category'])]  // policy check
    public function store(Request $request) {
        // auth + verified + subscribed + policy gate runs here
    }

    #[Middleware('admin')]                              // only admin needed here
    public function destroy(Post $post) {
        // auth + verified + admin middleware runs here
    }
}

The #[Authorize] attribute maps directly to $this->authorize() — it accepts the ability name and an optional model or array of models. If the gate check fails, Laravel throws an AuthorizationException before the method body runs.

When Controller Attributes Make Sense

Use them when different methods in the same controller have meaningfully different authorization rules. If every method needs the same middleware, the constructor $this->middleware() approach remains cleaner:

// Still valid — and arguably more visible for uniform middleware
class ApiController extends Controller {
    public function __construct() {
        $this->middleware(['auth:sanctum', 'throttle:api']);
    }
}

Job and Queue Attributes

Jobs in Laravel have always accepted configuration through public properties ($queue, $connection, $tries, $timeout). Attributes provide the same control at the class definition level.

use Illuminate\Queue\Attributes\Queue as QueueName;
use Illuminate\Queue\Attributes\Connection;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Timeout;
use Illuminate\Queue\Attributes\BackoffStrategy;

#[QueueName('video-processing')]
#[Connection('redis')]
#[Tries(3)]
#[Timeout(120)]
#[BackoffStrategy([10, 30, 60])]
class TranscodeVideo implements ShouldQueue
{
    public function handle(): void
    {
        // video processing logic
    }
}

Note that Queue::route() (also new in Laravel 13) overrides job-level queue/connection configuration from a service provider. If you use both, Queue::route() takes precedence. Use attributes when the routing belongs to the job itself; use Queue::route() when you need centralized routing control across many jobs.

Artisan Command Attributes

Artisan commands now accept attributes for their signature and description instead of class properties:

use Illuminate\Console\Attributes\Command as CommandAttribute;

#[CommandAttribute('posts:publish {--dry-run}', description: 'Publish all scheduled posts')]
class PublishScheduledPosts extends Command
{
    public function handle(): void
    {
        $dryRun = $this->option('dry-run');
        // logic here
    }
}

This is syntactically clean, but the practical benefit over protected $signature and protected $description is modest. The command still needs to extend Illuminate\Console\Command and the handle() method works identically.

Listener and Event Attributes

Event listeners can declare their event binding using an attribute rather than type-hinting the event class:

use Illuminate\Events\Attributes\ListensTo;

#[ListensTo(PostPublished::class)]
class SendPublishedNotification
{
    public function handle(PostPublished $event): void
    {
        // send notification
    }
}

For listeners auto-discovered by Laravel's event system, this attribute makes the binding explicit and statically analysable without requiring the listener to be registered in EventServiceProvider.

Common Mistakes and Limitations

1. Mass-converting existing models without a plan

The most common mistake teams make is running a find-and-replace on $fillable and $hidden across every model. This creates a large diff with zero runtime benefit and introduces inconsistency if any model gets missed. Adopt attributes incrementally — new models first, existing models during refactors.

2. Assuming attributes provide runtime validation

PHP attributes are metadata. #[Fillable('title')] does not throw if you try to mass-assign body — Laravel reads the attribute at model boot and populates its internal $fillable array. The validation behaviour is identical to the property approach.

3. Stacking conflicting middleware attributes

Attributes stack. If a parent class has #[Middleware('auth')] and a child class adds #[Middleware('auth')] again, both run — resulting in the middleware executing twice. Always check the inheritance chain before stacking.

4. Forgetting import statements

Attributes require a use statement for each attribute class. Unlike properties, which are just array values, each attribute has a fully qualified class name. A missing import causes a fatal error at class-load time, not at the point of use.

// Missing this import will throw at model boot, not at query time
use Illuminate\Database\Eloquent\Attributes\Fillable;

5. Mixing property and attribute syntax in the same model

As noted above, the property-based values take precedence. If you have both on the same model, the attribute is silently ignored. Enable PHPStan or run a project-wide grep after migration to confirm there are no mixed cases:

grep -rn 'protected \$fillable\|#\[Fillable' app/Models/

Testing Models and Controllers Using Attributes

Attributes do not change how you test models or controllers — the test API is identical. You can verify attribute resolution indirectly:

// Test that fillable is correctly resolved from #[Fillable] attribute
public function test_post_fillable_fields(): void
{
    $post = new Post();
    $this->assertEquals(['title', 'body', 'user_id', 'published_at'], $post->getFillable());
}

// Test that middleware protects the route (controller attribute in effect)
public function test_store_requires_auth(): void
{
    $response = $this->postJson('/api/posts', ['title' => 'Test']);
    $response->assertStatus(401);
}

// Test that unauthorized user cannot create a post (Authorize attribute)
public function test_store_requires_create_permission(): void
{
    $user = User::factory()->create(); // user without create permission
    $response = $this->actingAs($user)->postJson('/api/posts', ['title' => 'Test']);
    $response->assertStatus(403);
}

When to Use Attributes vs. Properties

Situation	Recommendation
New model in a greenfield project	Use attributes — consistent from the start
Existing model mid-project	Keep properties until a natural refactor point
Controller with varied per-method authorization	Use `#[Authorize]` and `#[Middleware]` — it's more readable
Controller with uniform middleware for all methods	Keep constructor `$this->middleware()` — less noise
Job configuration owned by the job itself	Use job attributes
Job routing owned by ops / infrastructure	Use `Queue::route()` in a service provider
Team unfamiliar with PHP attribute syntax	Defer adoption — the old syntax works indefinitely

Static Analysis and Tooling Support

Native PHP attributes integrate cleanly with the PHP ecosystem:

PHPStan / Psalm: Both understand #[...] attribute syntax natively. No special stubs needed for the attributes themselves, though you may need Laravel-specific stubs for the IDE to understand what each attribute does at runtime.
PhpStorm / VS Code with Intelephense: Full autocompletion on attribute class names and constructor parameters once the laravel/framework source is indexed.
Laravel Telescope / Debugbar: Attribute-configured middleware and authorization run identically to property-based configuration — the debug bar output looks the same.

Summary

PHP Attributes in Laravel 13 are an additive, optional improvement to developer ergonomics. They collocate configuration with the class it belongs to, make metadata visible to static analysis tools, and reduce the number of class properties a model or controller carries. They do not change runtime behaviour — every attribute maps to an existing framework mechanism.

The practical rule: adopt them in new code, migrate existing code only during planned refactors, and never mix both syntaxes in the same class.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Read the full guide

Composer Security Practices for Laravel Projects

Sumeet Shroff — Tue, 25 Aug 2026 06:13:21 +0000

Composer Security Practices for Laravel Projects

If you are running composer update in CI and calling it a security practice, you are doing the opposite of what is safe. This article walks through concrete, version-specific Composer hardening steps for Laravel projects — from lockfile discipline to CI egress controls — using lessons from the May 2026 Laravel-Lang supply chain attack.

Prerequisites: Composer 2.4 or later, Laravel 10 / 11 / 12, a CI pipeline (GitHub Actions examples used throughout).

Why Composer Is a High-Value Attack Surface

The average Laravel application pulls in 80–120 Composer packages. Each package maintainer's GitHub account is a potential entry point for an attacker. The May 2026 Laravel-Lang incident proved this: a single GitHub organization compromise let an attacker rewrite every git tag across four packages — laravel-lang/lang, laravel-lang/attributes, laravel-lang/http-statuses, and laravel-lang/actions — within a 90-minute window. Over 5,500 downstream repositories received a backdoored helpers.php within six hours.

That file was wired into Composer's autoload.files directive, which means it executed on every PHP request once installed. It silently exfiltrated .env files, AWS keys, GitHub tokens, Stripe secrets, SSH keys, and more to the attacker-controlled domain flipboxstudio.info.

The mechanism that made this possible — and that most teams overlook — is that git tags are mutable. When you pin "laravel-lang/lang": "^2.1" in composer.json, Composer resolves the tag at install time. If that tag is silently rewritten to point at a malicious commit, composer update will pull the new payload. The only immutable anchor is the SHA-256 hash recorded in composer.lock.

Rule 1: Commit `composer.lock` and Never Run `composer update` in CI

This is the single highest-impact change you can make.

# Safe — uses exact SHAs from composer.lock
composer install --no-dev --optimize-autoloader

# Dangerous in CI or production — upgrades deps and rewrites composer.lock
composer update

composer install respects the lockfile exactly. composer update re-resolves every constraint, which can pull in any newly tagged (or re-tagged) version.

In your GitHub Actions workflow:

- name: Install PHP dependencies
  run: composer install --no-dev --optimize-autoloader --no-interaction

Do not run composer update as part of any automated pipeline. Reserve it for a dedicated branch where a human reviews the diff before merging. If composer.lock is not committed to your repository, fix that before anything else:

git add composer.lock
git commit -m "chore: commit composer.lock for reproducible builds"

Rule 2: Run `composer audit` on Every Build

Composer 2.4 introduced the audit command, which reads composer.lock and checks every installed package against the PHP Security Advisories Database. It takes a few seconds and surfaces real CVEs.

# Human-readable output
composer audit

# Machine-parseable output for CI artifact storage
composer audit --format=json

Add it as a required step in CI, placed after composer install:

- name: Security audit
  run: composer audit --format=json > composer-audit.json

- name: Upload audit results
  uses: actions/upload-artifact@v4
  with:
    name: composer-audit
    path: composer-audit.json

Do not suppress audit output with COMPOSER_NO_AUDIT=1. Every advisory that surfaces represents a real CVE that should be triaged, not silenced.

Rule 3: Understand Composer 2.9 Security Blocking

Composer 2.9 (released 7 November 2025) added automatic security blocking via two new config keys:

{
  "config": {
    "audit": {
      "block-insecure": true,
      "block-abandoned": false,
      "ignore-abandoned": ["some/abandoned-package"]
    }
  }
}

block-insecure defaults to true, meaning composer update will fail if any installed package has a known security advisory. This broke CI builds for teams with unresolved advisories in existing dependencies — builds that previously succeeded now fail.

The correct response is to resolve the advisory, not to disable the feature. If you have a legitimate reason to suppress a specific advisory (for example, a vulnerability that does not affect your usage pattern), audit-ignore it explicitly rather than turning off the entire mechanism:

# Acknowledge a specific advisory without disabling the feature
composer audit --ignore-severity low

Note: A bug in early Composer 2.9 releases (GitHub issue #12607) caused COMPOSER_NO_AUDIT=1 and --no-audit to be ignored by the new blocking logic. Verify your Composer version with composer --version if you rely on those flags.

Rule 4: Add Enlightn as a Complementary Scanner

composer audit covers the PHP Security Advisories Database. The Enlightn Laravel Security Checker adds Laravel-specific checks and integrates with Artisan:

composer require --dev enlightn/laravel-security-checker
php artisan security:check

Enlightn can also be scheduled to email your team when new vulnerabilities appear in your installed packages — useful for production monitoring between deployments:

// app/Console/Kernel.php
$schedule->command('security:check')->weekly();

The tradeoff: composer audit is zero-dependency and ships with every Composer 2.4+ installation. Enlightn requires an additional dev dependency but gives you scheduler integration and a broader Laravel-specific rule set. Most teams benefit from running both.

Rule 5: Enforce CI Egress Controls

The Laravel-Lang attack exfiltrated secrets by making outbound HTTP connections from build machines. GitHub Actions, by default, allows any process running in a workflow to make arbitrary outbound connections — including a backdoored Composer package.

StepSecurity Harden-Runner adds network-policy enforcement to GitHub Actions:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: step-security/harden-runner@v2
        with:
          egress-policy: block
          allowed-endpoints: |
            packagist.org:443
            repo.packagist.org:443
            github.com:443
            api.github.com:443

      - uses: actions/checkout@v4

      - name: Install dependencies
        run: composer install --no-dev --optimize-autoloader --no-interaction

      - name: Security audit
        run: composer audit

With egress-policy: block, any process in the workflow that tries to connect to flipboxstudio.info (or any domain not in your allowlist) will be blocked and logged. This is the exact mechanism that would have contained the May 2026 Laravel-Lang attack in CI environments with this control in place.

Tradeoff: You need to allowlist every outbound endpoint your build touches — Packagist, GitHub, your CDN, any API called during tests. Misconfigurations break legitimate builds. The allowlist is typically 5–10 entries and stable once configured.

Rule 6: Check for the Laravel-Lang Compromise Indicator

If your project uses any of the four affected packages, verify your build history:

# Check whether affected packages are in your lockfile
grep -E '"laravel-lang/(lang|attributes|http-statuses|actions)"' composer.lock

Indicator of compromise: outbound connections to flipboxstudio.info in network logs from your build machines or containers between 22–23 May 2026 UTC. If found, rotate all secrets accessible from your CI environment immediately — GitHub tokens, AWS credentials, Stripe keys, .env values.

Packagist.org now enforces stable version immutability for published releases, preventing re-tagging. This applies only to packages hosted on Packagist. Private forks or packages installed via repositories entries in composer.json do not benefit from this protection.

Patch Status for Active CVEs

Run composer audit to surface these automatically, but know the target versions:

Package	CVE	Fixed In	Risk
`laravel/framework`	CVE-2025-27515 (wildcard file validation bypass)	10.48.29 / 11.44.1 / 12.1.1	Moderate
`livewire/livewire`	CVE-2025-54068 (unauthenticated RCE, CISA KEV)	3.6.4	Critical
`laravel/passport`	CVE-2026-39976 (authentication bypass, Passport 13.x)	13.7.1	High
`plank/laravel-mediable`	CVE-2026-4809 (arbitrary file upload / RCE)	> 6.4.0	Critical

The Livewire CVE (CVE-2025-54068) deserves emphasis: it bypasses the APP_KEY-signed checksum mechanism used for component state hydration. Attackers do not need your application key to exploit it. CISA confirmed active exploitation. If you are on any Livewire v3 release below 3.6.4, update immediately:

composer update livewire/livewire
composer audit

After upgrading Livewire, test any components that pass complex objects through properties — the patch tightened how untrusted input is handled during hydration.

Verification Checklist

Before considering your Composer security posture production-ready:

[ ] composer.lock is committed and not in .gitignore
[ ] CI runs composer install, not composer update
[ ] composer audit runs as a required CI step and fails the build on findings
[ ] Composer version is 2.9+ (composer --version)
[ ] audit.block-insecure is true in composer.json config (or Composer 2.9 default)
[ ] Livewire is on 3.6.4 or later
[ ] Laravel Passport is on 13.7.1 or later (if using Passport 13.x)
[ ] laravel/framework is on 10.48.29 / 11.44.1 / 12.1.1 or later
[ ] CI egress is restricted to known-good endpoints
[ ] Network logs checked for flipboxstudio.info connections (if using laravel-lang packages)

Common Mistakes to Avoid

Pinning to a version constraint instead of committing the lockfile. Writing "laravel-lang/lang": "^2.1" in composer.json is not a pin — it is a range that resolves at install time. The lockfile SHA is the real pin.

Running composer update on a schedule in CI. Automated upgrades are appealing but introduce the risk of pulling in newly compromised package versions without human review of the diff.

Setting COMPOSER_NO_AUDIT=1 globally. This silences real CVE warnings. Each advisory should be triaged and either patched or explicitly acknowledged with a documented reason.

Assuming autoload.files packages are low-risk. Any package listed under autoload.files executes on every PHP request. The Laravel-Lang backdoor used exactly this mechanism.

For a broader look at supply chain attack anatomy, CVE timelines, and static analysis tooling for Laravel applications, see the Laravel Security Guide: Supply-Chain Risks, Composer, and Application Scanning.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Read the full guide

Scanning Laravel Applications with Ward and Other Security Tools

Sumeet Shroff — Tue, 25 Aug 2026 04:18:39 +0000

Scanning Laravel Applications with Ward and Other Security Tools

If you maintain a Laravel application in production, you already know that composer audit exists. What you may not have set up yet is a layered scanning pipeline that catches what composer audit misses — hardcoded secrets, insecure Blade output, weak crypto configuration, and runtime file-upload bypasses. This article walks through assembling exactly that pipeline using Ward, composer audit, and StackShield, with concrete commands and a realistic CI integration.

Prerequisites

PHP 8.1+ and Composer 2.4+ (Composer 2.9+ strongly recommended)
Laravel 10, 11, or 12 (examples tested against 12.x)
Go 1.21+ if building Ward from source (or use the pre-built binary)
A GitHub Actions or similar CI environment

Why `composer audit` Alone Is Not Enough

composer audit (available since Composer 2.4) does one thing well: it reads your composer.lock and cross-references every installed package against the PHP Security Advisories Database. Run it in any project:

# Standard audit — human-readable output
composer audit

# Machine-parseable JSON for CI artifact storage
composer audit --format=json

Composer 2.9 (released November 2025) made auditing more aggressive by defaulting audit.block-insecure to true. This means composer update will fail outright if any package has an unresolved advisory. If your builds started breaking after upgrading Composer, this is why:

{
  "config": {
    "audit": {
      "block-insecure": true,
      "block-abandoned": false
    }
  }
}

The limitation is scope. composer audit only knows about CVEs that have been published to the advisories database. During the May 2026 Laravel-Lang supply-chain attack, roughly six hours elapsed between initial tag-rewrite and any public advisory. In that window, composer audit returned clean results on a poisoned lockfile. A defence-in-depth strategy needs additional layers.

Ward: Static Analysis Purpose-Built for Laravel

Ward is a Go binary that understands Laravel project structure — routes, models, controllers, middleware, Blade templates, config files, .env, and Composer dependencies. It runs 42+ built-in rules grouped into categories: secrets, injection, XSS, debug, crypto, config, and auth.

Installation

# macOS (Homebrew tap)
brew install eljakani/tap/ward

# Linux — download the latest release binary
curl -L https://github.com/Eljakani/ward/releases/latest/download/ward-linux-amd64 \
  -o /usr/local/bin/ward && chmod +x /usr/local/bin/ward

# Verify installation
ward --version

Basic scan

# Scan a Laravel project rooted at the current directory
ward scan .

# Output JSON for programmatic processing
ward scan . --output json > ward-results.json

# Output SARIF for GitHub Code Scanning integration
ward scan . --output sarif > ward-results.sarif

# Output Markdown for PR comments or reports
ward scan . --output markdown > ward-results.md

Ward also queries OSV.dev in real time, covering the broader open-source vulnerability ecosystem beyond the PHP Security Advisories Database — giving it wider CVE coverage than composer audit alone.

What Ward Catches That `composer audit` Misses

Consider these two common Laravel anti-patterns:

{{-- Unsafe: {!! !!} skips Laravel's auto-escaping, enabling XSS --}}
<h1>{!! $userInput !!}</h1>

{{-- Safe: {{ }} HTML-encodes the value by default --}}
<h1>{{ $userInput }}</h1>

Or a raw SQL query that reintroduces injection risk:

// Dangerous: direct string interpolation bypasses prepared statements
$results = DB::select("SELECT * FROM users WHERE email = '{$email}'");

// Safe: Query Builder uses PDO bindings
$results = DB::table('users')->where('email', $email)->get();

Ward's static analysis flags both patterns. composer audit is silent on both because they are not CVEs in installed packages — they are code-level vulnerabilities in your own application.

Ward Findings to Prioritise

After running a scan, focus on the high-severity findings first:

Secrets in code — hardcoded API keys, tokens, or credentials that should be in .env
Unescaped Blade output — {!! !!} applied to request or user-controlled data
Raw SQL with interpolation — bypassing the ORM's prepared statements
Debug mode leaks — APP_DEBUG=true references in non-test config
Weak encryption — use of md5() or sha1() for password hashing

StackShield: External Black-Box Scanning

StackShield takes the opposite approach to Ward. It is a zero-installation external scanner — you supply a URL, it probes your live deployment the way an attacker would, running 30+ checks without needing Composer or server access.

Use StackShield when you want a quick external audit of a staging environment, confirmation that .env is not publicly accessible, debug routes are disabled in production, or to check security headers (CSP, HSTS, X-Frame-Options).

The tradeoff: StackShield cannot read your source code and requires a live, publicly reachable deployment.

Ward vs StackShield — when to use each:

Concern	Ward	StackShield
Source-level XSS patterns	Yes	No
Hardcoded secrets in code	Yes	No
Exposed `.env` file	Partial	Yes
Missing security headers	No	Yes
Requires live deployment	No	Yes
Requires source code access	Yes	No
Queries OSV.dev for CVEs	Yes	No

Run Ward in CI on every push; run StackShield periodically against a live staging environment.

Enlightn as a Complement

Enlightn integrates directly with Laravel's Artisan scheduler and can email your team when new advisories appear against your installed packages:

# Install as a dev dependency
composer require --dev enlightn/laravel-security-checker

# Run the security check via Artisan
php artisan security:check

Schedule it in app/Console/Kernel.php (Laravel 10/11) or routes/console.php (Laravel 12):

// routes/console.php (Laravel 12)
Schedule::command('security:check')->daily();

Enlightn covers the same PHP Security Advisories Database as composer audit but adds scheduling, email notifications, and Artisan integration — useful for teams that do not monitor CI dashboards daily.

Critical CVEs Your Scanner Should Be Detecting

Make sure your current toolchain flags the following. If it does not, the scanner's database is out of date:

CVE-2025-27515 — File validation bypass in laravel/framework. Wildcard validation rules like files.* could be circumvented. Patched in 10.48.29, 11.44.1, and 12.1.1. If you are below these versions, composer audit should flag this immediately.

CVE-2025-54068 — Unauthenticated RCE in Livewire v3 through v3.6.3. This one bypasses the APP_KEY-signed checksum mechanism entirely — the attacker does not need your application key. It is on CISA's Known Exploited Vulnerabilities catalog. Update to Livewire v3.6.4.

CVE-2026-39976 — Authentication bypass in Laravel Passport 13.0.0–13.7.0. The TokenGuard does not verify whether a JWT sub claim belongs to a user or a client, allowing machine tokens to impersonate real users when IDs collide. Patched in Passport 13.7.1.

Verify your current versions:

# Check installed versions of affected packages
composer show laravel/framework | grep versions
composer show livewire/livewire | grep versions
composer show laravel/passport | grep versions

Integrating Ward into GitHub Actions

A complete CI job that runs composer audit and Ward in sequence:

name: Security Scan

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: step-security/harden-runner@v2
        with:
          egress-policy: block
          allowed-endpoints: |
            packagist.org:443
            repo.packagist.org:443
            github.com:443
            osv.dev:443

      - uses: actions/checkout@v4

      - name: Install PHP dependencies (lockfile only)
        run: composer install --no-dev --optimize-autoloader

      - name: Run Composer audit
        run: composer audit --format=json | tee composer-audit.json

      - name: Install Ward
        run: |
          curl -L https://github.com/Eljakani/ward/releases/latest/download/ward-linux-amd64 \
            -o /usr/local/bin/ward && chmod +x /usr/local/bin/ward

      - name: Run Ward scan
        run: ward scan . --output sarif > ward-results.sarif

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ward-results.sarif

Note the harden-runner step. This egress-policy enforcement would have contained the May 2026 Laravel-Lang supply-chain attack: blocking outbound connections to flipboxstudio.info would have silenced the credential exfiltration payload injected via autoload.files.

Common Mistakes

Not committing composer.lock. Without a committed lockfile, composer install resolves dependencies fresh each time, making your builds non-reproducible and vulnerable to tag-rewrite attacks. Always commit composer.lock.

Running composer update in CI. Use composer install in automated pipelines — it respects the lockfile. Reserve composer update for deliberate, reviewed dependency bumps in a local or staging environment.

Suppressing audit warnings. Setting COMPOSER_NO_AUDIT=1 to silence failing builds defeats the security feature. Triage each advisory; do not silence them.

Relying on Ward for runtime checks. Ward is a static analyser. It will not catch a runtime misconfiguration that only manifests under specific request conditions. Pair it with runtime anomaly detection or penetration testing for complete coverage.

Treating Ward findings as a one-time task. New rules are added as new vulnerability patterns emerge. Re-run Ward on a schedule, not just when onboarding it.

Testing and Verification

After running your scanning pipeline, verify the most critical outputs:

# Confirm composer audit exits non-zero when advisories exist
composer audit; echo "Exit code: $?"

# Parse Ward JSON output to count high-severity findings
ward scan . --output json | jq '[.findings[] | select(.severity == "high")] | length'

# Check your lockfile for the May 2026 Laravel-Lang affected packages
grep -E '"laravel-lang/(lang|attributes|http-statuses|actions)"' composer.lock

# Verify network egress from your CI runner does not reach the known IOC domain
# (check build logs for any connection to flipboxstudio.info)

For a broader view of supply-chain risk patterns and how Composer's lockfile semantics interact with tag-rewrite attacks, see the Laravel Security Guide: Supply-Chain Risks, Composer, and Application Scanning.

Summary

No single tool covers the full attack surface of a Laravel application. composer audit is fast and built-in — run it on every CI push. Ward brings static analysis that understands Laravel's structure and queries a broader vulnerability database. StackShield gives you an external attacker's perspective on a live deployment. Enlightn ties advisory checking into Laravel's scheduler for ongoing team notifications. Stack them, automate them, and do not suppress their warnings.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Read the full guide

Lessons Laravel Developers Should Learn from the laravel-lang Attack

Sumeet Shroff — Sat, 22 Aug 2026 10:01:02 +0000

Lessons Laravel Developers Should Learn from the laravel-lang Attack

On 22–23 May 2026, four packages in the laravel-lang organization — laravel-lang/lang, laravel-lang/attributes, laravel-lang/http-statuses, and laravel-lang/actions — were silently backdoored through a single account compromise. Every existing git tag across all four packages was rewritten within a 90-minute window. Within six hours, 5,561+ downstream repositories had received the poisoned code.

The injected payload was a helpers.php file wired into autoload.files in composer.json. Because autoload.files executes code on every PHP request immediately after installation, the backdoor ran without any action from application code. It exfiltrated AWS keys, GitHub tokens, Stripe secrets, SSH keys, .env files, JWTs, Kubernetes secrets, and crypto recovery phrases to flipboxstudio.info.

This is a technical walkthrough of the exact failure modes the attack exploited, and the concrete steps you can take today to prevent the same class of attack against your Laravel projects.

Prerequisites

Composer 2.4+ for composer audit; 2.9+ for audit.block-insecure
Laravel 10, 11, or 12
CI pipeline access (GitHub Actions or equivalent)

Why Tag Pinning Failed

Most developers assume that pinning a package to a specific version ("laravel-lang/lang": "^6.3") means Composer will always install the same code. That assumption is wrong when it comes to git tags.

Composer resolves a version constraint to a git tag. It then fetches the commit that the tag currently points at. If a maintainer (or attacker) rewrites the tag to point at a different commit, Composer will pull the new commit — there is no version mismatch, no checksum failure, no warning.

The laravel-lang attack exploited this precisely. The attackers rewrote every stable tag, so any project running composer update or even a fresh composer install with an outdated composer.lock received the backdoored code.

The only tamper-evident anchor Composer has is composer.lock. The lockfile stores the resolved commit SHA alongside the dist hash. If you commit your lockfile and deploy with composer install (not composer update), Composer will refuse to install a package whose content hash no longer matches.

# Safe — installs exactly what composer.lock specifies, verifies hashes
composer install --no-dev --optimize-autoloader

# Dangerous in CI/production — resolves constraints fresh, rewrites composer.lock
# Do not use in automated pipelines
composer update

This is the single most impactful change you can make: never run composer update in CI or production. Run it locally, review the diff in composer.lock, and commit the result as a deliberate change.

Check Your Lockfile Right Now

If you use any of the four affected packages, check immediately:

grep -E '"laravel-lang/(lang|attributes|http-statuses|actions)"' composer.lock

If any of those packages appear and you ran composer update or a fresh install between 22–23 May 2026 UTC, treat the host as compromised. Rotate all secrets that were accessible from the build environment.

Indicator of compromise: outbound HTTP/S connections from your build machines or containers to flipboxstudio.info.

The `autoload.files` Threat Surface

The attack vector — autoload.files — deserves specific attention. Composer's autoload.files section lists PHP files that are included on every request via the generated vendor/autoload.php. Unlike PSR-4 classes that only load when referenced, these files execute unconditionally as part of the autoloader bootstrap.

Legitimate packages use autoload.files for global helper functions (Laravel itself uses it for Illuminate/Support/helpers.php). Attackers use it for the same reason: guaranteed execution with no trigger required.

When auditing third-party packages, pay attention to any package that declares autoload.files. You can audit yours:

# List all packages using autoload.files
cat composer.lock | php -r '
$lock = json_decode(file_get_contents("php://stdin"), true);
foreach ($lock["packages"] as $pkg) {
    if (!empty($pkg["autoload"]["files"])) {
        echo $pkg["name"] . "\n";
        foreach ($pkg["autoload"]["files"] as $f) {
            echo "  " . $f . "\n";
        }
    }
}
'

Review the output. Any unfamiliar file in an autoload.files entry is worth reading.

Running `composer audit` in CI

Composer 2.4 introduced the audit command. It reads composer.lock and checks every installed package against the PHP Security Advisories Database. This should be a required step in every CI pipeline.

# Run audit — exits non-zero if advisories are found
composer audit

# JSON output for machine parsing
composer audit --format=json

Composer 2.9 (released November 2025) went further and introduced audit.block-insecure, which defaults to true. This blocks composer update operations when any installed package version has a known security advisory.

{
  "config": {
    "audit": {
      "block-insecure": true,
      "block-abandoned": false
    }
  }
}

One important caveat: composer audit checks packages against published CVEs. The laravel-lang attack went undetected by composer audit for the first several hours because no CVE existed yet. Dependency scanning catches known vulnerabilities. It does not catch novel supply chain attacks where a backdoor has not yet been catalogued. This is why egress controls matter.

Egress Controls in GitHub Actions

The most effective defence against credential exfiltration from a compromised package is preventing the exfiltration itself. GitHub Actions workflows run in network-accessible environments where every installed package can open outbound connections.

StepSecurity's Harden-Runner adds network-level egress policy to your workflow jobs:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: step-security/harden-runner@v2
        with:
          egress-policy: block
          allowed-endpoints: |
            packagist.org:443
            repo.packagist.org:443
            github.com:443
            api.github.com:443

      - uses: actions/checkout@v4

      - name: Install dependencies
        run: composer install --no-dev --optimize-autoloader

      - name: Run security audit
        run: composer audit

With egress-policy: block, any outbound connection not in the allowlist is blocked. A package attempting to reach flipboxstudio.info would have been silently dropped before it could exfiltrate anything. Add this to your workflows before you need it.

Static Analysis with Ward

For deeper code-level inspection, Ward is a Go binary security scanner built specifically for Laravel projects. It runs 42+ built-in rules across secrets, injection, XSS, debug configuration, crypto, auth categories, and queries the OSV.dev vulnerability database in real time.

# macOS
brew install eljakani/tap/ward

# Or download binary from GitHub releases
# github.com/Eljakani/ward

# Scan your project
ward scan /path/to/laravel-project

# Export SARIF for GitHub Code Scanning integration
ward scan . --output sarif > ward-results.sarif

# Export JSON for automation
ward scan . --output json > ward-results.json

Ward does not require Composer or access to a running deployment. The SARIF output integrates with GitHub's Code Scanning feature, surfacing findings as pull request annotations.

The Three CVEs You Must Patch

The May 2026 attack was the headline, but three other vulnerabilities are equally urgent:

CVE-2025-54068 — Livewire RCE (Critical, CISA KEV)
Affects Livewire v3 through v3.6.3. An attacker can bypass the APP_KEY-signed checksum and achieve unauthenticated remote code execution via deserialization during component hydration. This does not require knowledge of your application key. CISA added it to the Known Exploited Vulnerabilities catalog, meaning it is being actively used in the wild.

# Check your Livewire version
composer show livewire/livewire | grep versions

# Upgrade
composer update livewire/livewire
# Target: 3.6.4 or later

CVE-2026-39976 — Laravel Passport Authentication Bypass (CVSS 7.1)
Affects Passport 13.0.0 through 13.7.0. TokenGuard does not verify whether the JWT sub claim belongs to a user or a client. A machine token issued via client_credentials can authenticate as a real user when integer IDs collide between the clients and users tables. Fixed in Passport 13.7.1.

This only triggers if you use EnsureClientIsResourceOwner middleware and have Passport::$clientUuids set to false. Check whether your Passport configuration matches this profile before concluding you are safe.

CVE-2025-27515 — Laravel File Validation Bypass (Moderate)
Affects wildcard file validation rules (e.g., 'files.*') in Laravel Framework. Fixed in 10.48.29, 11.44.1, and 12.1.1. If your application accepts file uploads and validates them via wildcard rules, update your framework version.

Common Mistakes to Avoid

Running composer update in CI. This rewrites composer.lock and may pull in newly poisoned versions. CI must always run composer install.

Not committing composer.lock. Without a committed lockfile you cannot detect whether a dependency changed between deployments.

Suppressing audit warnings. COMPOSER_NO_AUDIT=1 silences real CVE alerts. Triage and resolve each advisory instead.

Trusting autoload.files entries blindly. These files execute on every request — review them before including any package in production.

Not rotating after a compromise. If your build environment ran the poisoned packages, rotate all accessible secrets immediately: AWS keys, GitHub tokens, Stripe secrets, and your APP_KEY.

Packagist's Response and Remaining Gaps

Following the attack, Packagist implemented stable version immutability — published stable releases can no longer be overwritten, directly addressing the git tag rewrite vector.

This protection applies only to packages on Packagist. Private forks, VCS repositories in composer.json's repositories section, and path-installed packages are not covered. If your project pulls from any non-Packagist source, integrity verification is your responsibility.

Planned improvements include FIDO2 MFA for maintainers, organizational package ownership verification, and SLSA provenance with Sigstore attestations — none are in place today for all packages.

Verification Checklist

Run through this after making the changes above:

composer.lock is committed to version control
CI pipeline runs composer install, never composer update
composer audit runs in CI and exits non-zero on findings
audit.block-insecure: true is set in composer.json (Composer 2.9+)
Egress controls are applied to CI workflow jobs
Livewire is at 3.6.4 or later
Laravel Passport (if used) is at 13.7.1 or later
Laravel Framework is at 10.48.29, 11.44.1, or 12.1.1+ for file validation fix
autoload.files entries in third-party packages have been reviewed
Network logs checked for any connections to flipboxstudio.info

For a broader look at Composer security hardening, dependency scanning with Enlightn, and application-level scanning with StackShield, read the Laravel Security Guide: Supply-Chain Risks, Composer, and Application Scanning.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.