Middleware en Laravel: qué es, cómo crearlo y cuándo usarlo

Piensa en middleware como capas alrededor de la aplicación

Imagina una solicitud:

GET /panel

Antes de ejecutar el controller, la solicitud puede atravesar varias capas.

Request
   ↓
Middleware A
   ↓
Middleware B
   ↓
Middleware C
   ↓
Route
   ↓
Controller
   ↓
Response

Cada middleware puede permitir que la petición continúe o interrumpir el recorrido.

Ejemplo: usuario no autenticado

GET /panel
   ↓
auth
   ↓
¿Usuario autenticado?
   ↓
NO
   ↓
No ejecutar PanelController

Esa capacidad evita repetir la misma comprobación dentro de cada controller.

Genera tu primer middleware personalizado

Artisan puede crear la estructura inicial.

php artisan make:middleware EnsureAccountIsActive

La clase quedará normalmente dentro de:

app/Http/Middleware/EnsureAccountIsActive.php

Podemos comprobar si la cuenta del usuario está activa.

<?php

namespace App\Http\Middleware;

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

final class EnsureAccountIsActive
{
    public function handle(
        Request $request,
        Closure $next
    ): Response {

        $user = $request->user();

        if (
            $user !== null
            &&
            ! $user->activo
        ) {
            abort(
                403,
                'La cuenta está desactivada.'
            );
        }

        return $next($request);
    }
}

El middleware comprueba una condición y, si puede continuar, entrega el request a la siguiente capa.

Puedes asignar una clase middleware directamente a una ruta

<?php

use App\Http\Middleware\EnsureAccountIsActive;
use Illuminate\Support\Facades\Route;

Route::get(
    '/panel',
    [PanelController::class, 'index']
)->middleware(
    EnsureAccountIsActive::class
);

También puedes asignar varias capas a la misma ruta.

Route::get(
    '/panel',
    [PanelController::class, 'index']
)->middleware([
    'auth',
    EnsureAccountIsActive::class
]);

Aquí primero necesitamos una identidad autenticada y después comprobamos el estado de esa cuenta.

Laravel ya proporciona aliases para necesidades frecuentes

Esto significa que no deberías recrear manualmente capacidades que Laravel ya proporciona de manera coherente.

auth responde a una pregunta sencilla: ¿hay una identidad autenticada?

Route::get(
    '/perfil',
    [PerfilController::class, 'show']
)->middleware('auth');

No deberías repetir dentro del controller:

if (! auth()->check()) {
    // ...
}

en cada método privado de la aplicación.

Middleware permite expresar esa condición en el límite HTTP.

El middleware can conecta el ciclo HTTP con las reglas de autorización

Supongamos que una ruta actualiza un proyecto.

Route::patch(
    '/proyectos/{proyecto}',
    [ProyectoController::class, 'update']
)->middleware(
    'can:update,proyecto'
);

Antes de ejecutar el controller, Laravel puede comprobar si el usuario está autorizado para realizar update sobre ese proyecto.

Esto enlaza middleware con Policies o las reglas de autorización correspondientes.

También puedes crear un grupo reutilizable de middleware

Si la combinación se utiliza en varias partes, puedes crear un grupo.

<?php

use App\Http\Middleware\EnsureAccountIsActive;
use App\Http\Middleware\EnsureCompanyIsSelected;
use Illuminate\Foundation\Configuration\Middleware;

->withMiddleware(
    function (Middleware $middleware): void {

        $middleware->appendToGroup(
            'account',
            [
                EnsureAccountIsActive::class,
                EnsureCompanyIsSelected::class
            ]
        );

    }
)

Después:

Route::middleware([
    'auth',
    'account'
])->group(function () {

    // Rutas privadas.

});

Esto puede resultar útil cuando varias capas representan una preocupación transversal común.

Los grupos web y api tienen responsabilidades diferentes

Las rutas web necesitan normalmente infraestructura relacionada con:

Las rutas de una API pueden tener necesidades distintas.

Laravel administra grupos predeterminados para esos contextos.

Un middleware puede ejecutar lógica tanto antes como después del controller

Antes

<?php

public function handle(
    Request $request,
    Closure $next
): Response {

    // Trabajo antes.

    return $next($request);
}

Después

<?php

public function handle(
    Request $request,
    Closure $next
): Response {

    $response = $next($request);

    // Trabajo después.

    return $response;
}

Observa la diferencia:

Middleware
    ↓
trabajo antes
    ↓
$next($request)
    ↓
Controller
    ↓
Response
    ↓
trabajo después
    ↓
Cliente

Esta estructura permite implementar preocupaciones relacionadas con entrada y salida del ciclo HTTP.

Un middleware también puede modificar la respuesta

Por ejemplo, puedes añadir un header relacionado con trazabilidad.

<?php

public function handle(
    Request $request,
    Closure $next
): Response {

    $response = $next($request);

    $response->headers->set(
        'X-App-Version',
        '1'
    );

    return $response;
}

Nuevamente, la cuestión importante es si esa tarea realmente pertenece a una preocupación transversal del ciclo HTTP.

throttle es otro buen ejemplo de una preocupación transversal

Un endpoint no debería necesitar implementar manualmente lógica repetida para contar solicitudes.

Puedes aplicar límites mediante middleware según la estrategia de la aplicación.

Route::post(
    '/contacto',
    [ContactoController::class, 'store']
)->middleware(
    'throttle:10,1'
);

Conceptualmente, una regla como esta limita el volumen aceptado dentro de una ventana determinada.

No todas las rutas deberían tener el mismo límite

Generar IA, intentar login, leer un catálogo y crear un pago tienen perfiles de riesgo y costo completamente diferentes.

auth:sanctum es middleware, pero Sanctum hace mucho más que una sola comprobación

En una API protegida puedes utilizar:

Route::get(
    '/usuario',
    function (Request $request) {

        return $request->user();

    }
)->middleware(
    'auth:sanctum'
);

El middleware determina si existe una identidad aceptada por ese guard.

Después siguen existiendo otras preguntas:

Puedes excluir middleware de rutas concretas dentro de determinados grupos

Imagina un grupo donde casi todas las páginas necesitan una condición, excepto una.

Route::middleware([
    EnsureAccountIsActive::class
])->group(function () {

    Route::get(
        '/panel',
        [PanelController::class, 'index']
    );

    Route::get(
        '/cuenta-bloqueada',
        [AccountController::class, 'blocked']
    )->withoutMiddleware([
        EnsureAccountIsActive::class
    ]);

});

Tiene sentido:

un usuario con cuenta bloqueada necesita poder ver precisamente la página que explica por qué está bloqueada.

¿Cómo decidir si una regla pertenece a middleware?

Hazte una pregunta:

¿Esta regla existe porque estamos procesando una solicitud HTTP o porque el negocio necesita realizar una operación concreta?

Buen candidato a middleware

¿Está autenticado?
¿Está verificado?
¿Está activa la cuenta?
¿Excedió el límite de requests?
¿Puede entrar a esta zona?

Mal candidato

Calcular total del pedido.
Crear una factura.
Aplicar descuentos.
Reservar inventario.
Procesar un pago.

Esas últimas operaciones representan casos de uso del negocio.

Meterlas dentro de middleware puede esconder el verdadero flujo de la aplicación.

Cada middleware añade trabajo al request

Una comprobación sencilla puede tener un costo mínimo.

Pero imagina un middleware que en cada request:

Si además es global, ese costo se replica en toda la aplicación.

Un middleware también puede recibir dependencias mediante el contenedor

No necesitas crear manualmente todas las clases que utiliza.

<?php

final class EnsureSubscriptionIsActive
{
    public function __construct(
        private SubscriptionService $subscriptions
    ) {}


    public function handle(
        Request $request,
        Closure $next
    ): Response {

        if (
            ! $this->subscriptions
                ->isActive(
                    $request->user()
                )
        ) {
            abort(403);
        }

        return $next($request);
    }
}

Esto permite que la capa HTTP delegue una comprobación especializada.

Pero cuida la dirección de dependencias

Si el middleware comienza a coordinar toda la aplicación, probablemente haya dejado de ser solamente una capa de entrada.

Los errores más comunes al usar middleware en Laravel

Middleware funciona mejor cuando protege el límite HTTP sin esconder el negocio