Middleware

Overview

Middleware provides a convenient mechanism for filtering HTTP requests entering your application. For example, Forge includes middleware that verifies the user is authenticated. If the user is not authenticated, the middleware will redirect them to the login page. However, if the user is authenticated, the middleware will allow the request to proceed further into the application.

Creating Middleware

To create a new middleware, implement the MiddlewareInterface. Each middleware must have a handle method that receives the request and a closure for the next middleware in the pipeline:

namespace App\Middleware;

use Forge\Core\Http\Request;
use Forge\Core\Http\Response;
use Forge\Core\Contracts\Middleware\MiddlewareInterface;

class CustomMiddleware implements MiddlewareInterface
{
    public function handle(Request $request, Closure $next): Response
    {
        // Perform actions before the request is handled
        
        $response = $next($request);
        
        // Perform actions after the request is handled
        
        return $response;
    }
}

Middleware Pipeline

Middleware executes in a pipeline, allowing multiple middleware to handle the request in sequence. Each middleware can either pass the request to the next middleware in the pipeline or terminate the request processing:

class LogRequestMiddleware implements MiddlewareInterface
{
    public function handle(Request $request, Closure $next): Response
    {
        Log::info('Incoming request', [
            'method' => $request->getMethod(),
            'uri' => $request->getUri()
        ]);

        return $next($request);
    }
}

Global Middleware

Global middleware runs on every HTTP request to your application. Register global middleware in your application's kernel:

// In app/Bootstrap/Kernel.php

protected array $middleware = [
    \App\Middleware\TrimStrings::class,
    \App\Middleware\ConvertEmptyStringsToNull::class,
];

Route Middleware

Route middleware can be assigned to specific routes or route groups:

// Single route middleware
$router->get('/profile', [ProfileController::class, 'show'])
    ->middleware(AuthMiddleware::class);

// Route group middleware
$router->group('/admin', function (RouterInterface $router) {
    $router->middleware([AuthMiddleware::class, AdminMiddleware::class]);
    
    $router->get('/dashboard', [AdminController::class, 'dashboard']);
    $router->get('/users', [AdminController::class, 'users']);
});

Core Middleware

Forge includes several core middleware components that handle common tasks:

// Session middleware
class SessionMiddleware implements MiddlewareInterface
{
    public function handle(Request $request, Closure $next): Response
    {
        if (!$request->hasSession()) {
            $request->setSession(new Session());
        }

        return $next($request);
    }
}

// CSRF protection middleware
class VerifyCsrfToken implements MiddlewareInterface
{
    public function handle(Request $request, Closure $next): Response
    {
        if ($this->isReading($request) || $this->tokensMatch($request)) {
            return $next($request);
        }

        throw new TokenMismatchException('CSRF token mismatch');
    }
}