Middleware

¿Qué es un middleware?

Un middleware es un mecanismo para inspeccionar y filtrar las solicitudes HTTP que llegan a la aplicación. Permite intercalar lógica antes o después de que la solicitud llegue al controlador. Por ejemplo, Laravel incluye un middleware de autenticación. Si el usuario no está autenticado, redirige a la pantalla de login; si lo está, deja pasar la solicitud sin más. Además de la autenticación, puedes crear middleware para tareas como logging, protección CSRF o limitación de tasa. Para los detalles de la protección CSRF en Laravel 13, consulta Protección CSRF.

El middleware definido por el usuario se coloca habitualmente en el directorio app/Http/Middleware.

Middleware integrados

Laravel proporciona por defecto dos grupos de middleware: web y api. routes/web.php recibe automáticamente el grupo web y routes/api.php el grupo api.

Grupo `web`
`EncryptCookies`
`AddQueuedCookiesToResponse`
`StartSession`
`ShareErrorsFromSession`
`PreventRequestForgery` (protección CSRF)
`SubstituteBindings`

Los middleware más utilizados tienen alias, que permiten referirse a ellos con un nombre corto.

Alias	Middleware
`auth`	`Illuminate\Auth\Middleware\Authenticate`
`guest`	`Illuminate\Auth\Middleware\RedirectIfAuthenticated`
`verified`	`Illuminate\Auth\Middleware\EnsureEmailIsVerified`
`throttle`	`Illuminate\Routing\Middleware\ThrottleRequests`

Crear un middleware

Crea un middleware con el comando Artisan make:middleware.

php artisan make:middleware EnsureTokenIsValid

Se genera app/Http/Middleware/EnsureTokenIsValid.php. Escribe la lógica de procesamiento en el método handle.

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureTokenIsValid
{
    /**
     * Procesa la solicitud entrante
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->input('token') !== 'my-secret-token') {
            return redirect('/home');
        }

        return $next($request);
    }
}

Al llamar a $next($request), la solicitud pasa al siguiente paso. Si no se cumple la condición, detén la solicitud devolviendo un redirect o una respuesta.

Procesamiento antes/después

El middleware puede ejecutar lógica antes o después de la solicitud.

// Antes de la solicitud
public function handle(Request $request, Closure $next): Response
{
    // Aquí va el pre-proceso

    return $next($request);
}

// Después de la respuesta
public function handle(Request $request, Closure $next): Response
{
    $response = $next($request);

    // Aquí va el post-proceso

    return $response;
}

Registrar middleware

Middleware global

Para ejecutarlo en todas las solicitudes, añádelo a la pila global en withMiddleware de bootstrap/app.php.

// bootstrap/app.php
use App\Http\Middleware\EnsureTokenIsValid;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->append(EnsureTokenIsValid::class);
    });

append lo añade al final. Para añadirlo al principio usa prepend.

Aplicar a rutas

Para aplicarlo solo a ciertas rutas, usa el método middleware en la definición.

use App\Http\Middleware\EnsureTokenIsValid;

Route::get('/profile', function () {
    // ...
})->middleware(EnsureTokenIsValid::class);

Para aplicar varios middleware, pásalos como array.

Route::get('/', function () {
    // ...
})->middleware([First::class, Second::class]);

Para excluir un middleware en una ruta concreta, usa withoutMiddleware.

use App\Http\Middleware\EnsureTokenIsValid;

Route::middleware([EnsureTokenIsValid::class])->group(function () {
    Route::get('/', function () {
        // A esta ruta se le aplica el middleware
    });

    Route::get('/profile', function () {
        // A esta ruta se le excluye el middleware
    })->withoutMiddleware([EnsureTokenIsValid::class]);
});

Alias de middleware

Puedes definir alias cortos para nombres de clase largos, en bootstrap/app.php.

// bootstrap/app.php
use App\Http\Middleware\EnsureUserIsSubscribed;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->alias([
            'subscribed' => EnsureUserIsSubscribed::class,
        ]);
    });

Aplícalo a la ruta con el alias.

Route::get('/profile', function () {
    // ...
})->middleware('subscribed');

Grupos de middleware

Agrupar varios middleware bajo una clave facilita su aplicación a las rutas. En bootstrap/app.php usa appendToGroup o prependToGroup.

// bootstrap/app.php
use App\Http\Middleware\First;
use App\Http\Middleware\Second;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->appendToGroup('group-name', [
            First::class,
            Second::class,
        ]);
    });

Los grupos se aplican como un middleware normal.

Route::get('/', function () {
    // ...
})->middleware('group-name');

Route::middleware(['group-name'])->group(function () {
    // ...
});

Para añadir middleware a los grupos existentes web o api hay métodos específicos.

// bootstrap/app.php
use App\Http\Middleware\EnsureUserIsSubscribed;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->web(append: [
            EnsureUserIsSubscribed::class,
        ]);
    });

Parámetros de middleware

Los middleware pueden recibir parámetros. Añade los parámetros al método handle después del argumento $next.

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureUserHasRole
{
    public function handle(Request $request, Closure $next, string $role): Response
    {
        if (! $request->user()->hasRole($role)) {
            return redirect('/home');
        }

        return $next($request);
    }
}

En la ruta, separa el nombre del middleware y sus parámetros con :.

use App\Http\Middleware\EnsureUserHasRole;

Route::put('/post/{id}', function (string $id) {
    // ...
})->middleware(EnsureUserHasRole::class.':editor');

Con varios parámetros, sepáralos con comas.

Route::put('/post/{id}', function (string $id) {
    // ...
})->middleware(EnsureUserHasRole::class.':editor,publisher');

Ejemplo práctico: middleware de comprobación de autenticación

Ejemplo sencillo que redirige a los usuarios no autenticados.

php artisan make:middleware RedirectIfNotAuthenticated

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class RedirectIfNotAuthenticated
{
    public function handle(Request $request, Closure $next): Response
    {
        if (! $request->user()) {
            return redirect('/login');
        }

        return $next($request);
    }
}

Aplícalo a la ruta.

Route::get('/dashboard', function () {
    return view('dashboard');
})->middleware(RedirectIfNotAuthenticated::class);

Laravel incluye el middleware auth para autenticación. Antes de crear el tuyo, comprueba si un middleware existente cumple tus requisitos.

Próximos pasos

Solicitud HTTP

Aprende a recibir datos de la solicitud en el controlador.

Introducción

Conceptos básicos

Manejo de solicitudes

Base de datos

Autenticación

Helpers y comunicación externa

Pruebas y despliegue

Asistencia de desarrollo con IA

¿Qué es un middleware?

Middleware integrados

Crear un middleware

Procesamiento antes/después

Registrar middleware

Middleware global

Aplicar a rutas

Alias de middleware

Grupos de middleware

Parámetros de middleware

Ejemplo práctico: middleware de comprobación de autenticación

Próximos pasos

Solicitud HTTP

​¿Qué es un middleware?

​Middleware integrados

​Crear un middleware

​Procesamiento antes/después

​Registrar middleware

​Middleware global

​Aplicar a rutas

​Alias de middleware

​Grupos de middleware

​Parámetros de middleware

​Ejemplo práctico: middleware de comprobación de autenticación

​Próximos pasos

Solicitud HTTP

¿Qué es un middleware?

Middleware integrados

Crear un middleware

Procesamiento antes/después

Registrar middleware

Middleware global

Aplicar a rutas

Alias de middleware

Grupos de middleware

Parámetros de middleware

Ejemplo práctico: middleware de comprobación de autenticación

Próximos pasos