> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Middleware

> Explicamos cómo usar los middleware de Laravel para filtrar y preprocesar solicitudes HTTP.

## ¿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](/es/csrf).

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

```mermaid theme={null}
flowchart TD
    A["Solicitud HTTP"] --> B["Middleware global<br>(se aplica a todas)"]
    B --> C["Middleware de ruta<br>(se aplica a rutas específicas)"]
    C --> D["Controlador / Closure"]
    D --> E["Se genera la respuesta"]
    E --> F["Middleware de ruta<br>(post-proceso)"]
    F --> G["Middleware global<br>(post-proceso)"]
    G --> H["Respuesta HTTP"]
```

## 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`.

```shell theme={null}
php artisan make:middleware EnsureTokenIsValid
```

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

```php theme={null}
<?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.

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

    return $next($request);
}
```

```php theme={null}
// 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`.

```php theme={null}
// 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.

```php theme={null}
use App\Http\Middleware\EnsureTokenIsValid;

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

Para aplicar varios middleware, pásalos como array.

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

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

```php theme={null}
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`.

```php theme={null}
// 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.

```php theme={null}
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`.

```php theme={null}
// 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.

```php theme={null}
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.

```php theme={null}
// 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 theme={null}
<?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 `:`.

```php theme={null}
use App\Http\Middleware\EnsureUserHasRole;

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

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

```php theme={null}
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.

```shell theme={null}
php artisan make:middleware RedirectIfNotAuthenticated
```

```php theme={null}
<?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.

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

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

## Próximos pasos

<Card title="Solicitud HTTP" icon="globe" href="/es/requests">
  Aprende a recibir datos de la solicitud en el controlador.
</Card>


## Related topics

- [Laravel AI SDK](/es/ai-sdk.md)
- [Laravel Folio](/es/folio.md)
- [Autenticación OAuth 2.0 - Google Sheets API for Laravel](/es/packages/laravel-google-sheets/oauth.md)
- [Laravel Pennant](/es/pennant.md)
- [Laravel Sentinel — Investigación del middleware de protección de rutas](/es/blog/sentinel-introduction.md)