Laravel Middleware Order: Auth Before Role Prevents 403

<?php

// File: app/Http/Middleware/RequestLifecycleDemo.php
// Purpose: Illustrate exactly WHEN code runs relative to the next layer.

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class RequestLifecycleDemo
{
    public function handle(Request $request, Closure $next): mixed
    {
        // ─────────────────────────────────────────────────────────
        // BEFORE phase: runs BEFORE the request reaches the controller.
        // Perfect for: authentication checks, rate limiting, input sanitising.
        // ─────────────────────────────────────────────────────────
        Log::info('⬇ Middleware BEFORE — request arriving', [
            'url'    => $request->fullUrl(),
            'method' => $request->method(),
        ]);

        // Hand the request to the next layer (another middleware or the controller).
        // $response contains whatever that next layer ultimately returned.
        $response = $next($request);

        // ─────────────────────────────────────────────────────────
        // AFTER phase: runs AFTER the controller has built the response.
        // Perfect for: adding headers, logging response times, caching.
        // ─────────────────────────────────────────────────────────
        $response->headers->set('X-Processed-By', 'TheCodeForge');

        Log::info('⬆ Middleware AFTER — response leaving', [
            'status' => $response->getStatusCode(),
        ]);

        return $response; // Send the (possibly modified) response back up the stack.
    }
}

<?php

// File: app/Http/Middleware/EnsureUserIsAdmin.php
// Run: php artisan make:middleware EnsureUserIsAdmin

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Symfony\Component\HttpFoundation\Response;

class EnsureUserIsAdmin
{
    public function handle(Request $request, Closure $next): Response
    {
        // If no one is logged in at all, send them to the login page.
        if (!Auth::check()) {
            return redirect()->route('login')
                ->with('status', 'Please log in to continue.');
        }

        // Auth::user() returns the currently authenticated User model.
        // We check a 'role' column on the users table — adjust to your schema.
        if (Auth::user()->role !== 'admin') {
            // Abort with 403 Forbidden and a clear reason.
            // This gets caught by Laravel's exception handler,
            // which renders your custom 403.blade.php if it exists.
            abort(403, 'You do not have permission to access this area.');
        }

        // User is an admin — let the request continue normally.
        return $next($request);
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// REGISTRATION — Laravel 11+ style (bootstrap/app.php)
// ─────────────────────────────────────────────────────────────────────────────
// In bootstrap/app.php:
//
// use App\Http\Middleware\EnsureUserIsAdmin;
//
// ->withMiddleware(function (Middleware $middleware) {
//     $middleware->alias([
//         'admin' => EnsureUserIsAdmin::class,
//     ]);
// })

// ─────────────────────────────────────────────────────────────────────────────
// REGISTRATION — Laravel 10 style (app/Http/Kernel.php)
// ─────────────────────────────────────────────────────────────────────────────
// protected $middlewareAliases = [
//     'admin' => \App\Http\Middleware\EnsureUserIsAdmin::class,
// ];

// ─────────────────────────────────────────────────────────────────────────────
// USAGE IN ROUTES (routes/web.php)
// ─────────────────────────────────────────────────────────────────────────────

// routes/web.php
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\AdminDashboardController;
use App\Http\Controllers\ReportController;

// Single route — only admins can view the dashboard.
Route::get('/admin/dashboard', [AdminDashboardController::class, 'index'])
    ->middleware('admin')
    ->name('admin.dashboard');

// Route group — apply 'admin' middleware to every route inside.
Route::prefix('admin')
    ->middleware('admin')
    ->name('admin.')
    ->group(function () {
        Route::get('/reports', [ReportController::class, 'index'])->name('reports');
        Route::get('/users',   [ReportController::class, 'users'])->name('users');
    });

<?php

// File: app/Http/Middleware/EnsureUserHasRole.php
// A single middleware that handles ANY role via a parameter.

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Symfony\Component\HttpFoundation\Response;

class EnsureUserHasRole
{
    /**
     * @param string $requiredRole  — injected by Laravel from the route definition.
     *                                e.g. middleware('role:editor') sets $requiredRole = 'editor'
     * @param string ...$extraRoles — variadic: middleware('role:editor,moderator') passes both.
     */
    public function handle(
        Request $request,
        Closure $next,
        string  $requiredRole,
        string  ...$extraRoles    // Capture any additional roles passed after a comma.
    ): Response {
        // Merge the first role and any extras into one array for a clean in_array check.
        $allowedRoles = [$requiredRole, ...$extraRoles];

        $currentUserRole = Auth::user()?->role; // ?-> safely returns null if not authenticated.

        if (!in_array($currentUserRole, $allowedRoles, strict: true)) {
            abort(403, "Access requires one of: " . implode(', ', $allowedRoles));
        }

        return $next($request);
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// REGISTRATION (bootstrap/app.php — Laravel 11+)
// ─────────────────────────────────────────────────────────────────────────────
// $middleware->alias([
//     'role' => \App\Http\Middleware\EnsureUserHasRole::class,
// ]);

// ─────────────────────────────────────────────────────────────────────────────
// USAGE — Chaining middleware on routes (routes/web.php)
// ─────────────────────────────────────────────────────────────────────────────
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\ArticleController;
use App\Http\Controllers\AnalyticsController;

// Chain: user must be logged in AND have a verified email AND have the 'editor' role.
Route::get('/articles/create', [ArticleController::class, 'create'])
    ->middleware(['auth', 'verified', 'role:editor'])
    ->name('articles.create');

// Multiple roles allowed — editor OR moderator can access analytics.
Route::get('/analytics', [AnalyticsController::class, 'index'])
    ->middleware(['auth', 'role:editor,moderator'])
    ->name('analytics.index');

// Route group with shared middleware — every route here needs auth + admin role.
Route::middleware(['auth', 'role:admin'])
    ->prefix('admin')
    ->name('admin.')
    ->group(function () {
        Route::get('/settings', fn() => view('admin.settings'))->name('settings');
        Route::get('/billing',  fn() => view('admin.billing'))->name('billing');
    });

<?php

// File: tests/Feature/Middleware/EnsureUserHasRoleTest.php
// Run: php artisan test --filter=EnsureUserHasRoleTest

namespace Tests\Feature\Middleware;

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class EnsureUserHasRoleTest extends TestCase
{
    use RefreshDatabase; // Resets the DB between tests — important for user creation.

    /** @test */
    public function admin_user_can_access_admin_dashboard(): void
    {
        // Arrange: create a user with the 'admin' role using a factory state.
        $adminUser = User::factory()->create(['role' => 'admin']);

        // Act: simulate the admin making a GET request, fully authenticated.
        $response = $this->actingAs($adminUser)->get('/admin/dashboard');

        // Assert: the request passed through middleware and hit the controller.
        $response->assertStatus(200);
    }

    /** @test */
    public function editor_user_is_forbidden_from_admin_dashboard(): void
    {
        // Arrange: a regular editor — NOT an admin.
        $editorUser = User::factory()->create(['role' => 'editor']);

        // Act + Assert: expect the middleware to block with 403.
        $this->actingAs($editorUser)
             ->get('/admin/dashboard')
             ->assertStatus(403);
    }

    /** @test */
    public function guest_is_redirected_to_login_from_admin_dashboard(): void
    {
        // No actingAs() — simulates an unauthenticated guest.
        $this->get('/admin/dashboard')
             ->assertRedirect('/login');
    }

    /** @test */
    public function middleware_allows_multiple_roles_when_configured(): void
    {
        // Arrange: a moderator hitting the analytics route which allows editor,moderator.
        $moderator = User::factory()->create(['role' => 'moderator']);

        $this->actingAs($moderator)
             ->get('/analytics')
             ->assertStatus(200); // Moderator is in the allowed list — should pass.
    }
}

<?php

// routes/web.php
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Auth\LoginController;
use App\Http\Controllers\DashboardController;

// Admin group with auth and role:admin middleware
Route::middleware(['auth', 'role:admin'])
    ->prefix('admin')
    ->group(function () {
        // This route will NOT have the 'auth' and 'role:admin' middleware applied
        Route::get('/public-info', function () {
            return 'Public admin info - no auth required';
        })->withoutMiddleware(['auth', 'role:admin']);

        // Other routes in the group still use the group middleware
        Route::get('/dashboard', [DashboardController::class, 'index']);
    });

// ─────────────────────────────────────────────────────────────────────────────
// withoutMiddleware() also works for individual middleware:
// Route::get('/some-route', ...)->withoutMiddleware('auth');
//
// ─────────────────────────────────────────────────────────────────────────────
// Middleware Priority in app/Http/Kernel.php (Laravel 10+):
//
// protected $middlewarePriority = [
//     \Illuminate\Session\Middleware\StartSession::class,
//     \Illuminate\View\Middleware\ShareErrorsFromSession::class,
//     \App\Http\Middleware\Authenticate::class,
//     \Illuminate\Routing\Middleware\SubstituteBindings::class,
//     // ...
// ];
//
// This forces StartSession to always run before Authenticate, even if the order in
the route middleware array is different.