Osumi Framework
es en eu v9.12.1 GitHub

Middlewares

Los Middlewares de Osumi Framework son clases reutilizables que participan en el ciclo de vida de una petición HTTP.

Pueden ejecutarse en tres fases:

Se usan habitualmente para autenticación, autorización, validación de tokens, carga de contexto, modificación de respuestas, cabeceras, códigos de estado, auditoría y logging.

1. Estructura de un Middleware

<?php

declare(strict_types=1);

namespace Osumi\OsumiFramework\App\Middleware;

final class ExampleMiddleware {
	/**
	 * Handle a middleware execution phase.
	 *
	 * @param string $phase Current middleware phase.
	 * @param array<string, mixed> $data Current middleware pipeline data.
	 *
	 * @return array<string, mixed> Middleware result.
	 */
	public static function handle(
		string $phase,
		array $data
	): array {
		return [];
	}
}

Los Middlewares de aplicación se almacenan normalmente en src/Middleware/.

2. Fases

OMiddleware::PHASE_BEFORE
OMiddleware::PHASE_AFTER_RENDER
OMiddleware::PHASE_AFTER_RESPONSE

Flujo tradicional:

Routing
↓
before
↓
Componente
↓
afterRender
↓
Layout
↓
afterResponse
↓
Respuesta HTTP

En una respuesta streaming se omite el layout y afterResponse termina antes de comenzar a enviar bytes.

before

Se ejecuta antes de instanciar el componente. Es la fase adecuada para autenticación, autorización, validación, bloqueo de peticiones y carga de contexto.

afterRender

En respuestas tradicionales se ejecuta después de renderizar el componente y antes del layout. Puede inspeccionar o sustituir el cuerpo, añadir cabeceras o cambiar el código de estado.

En respuestas streaming también se ejecuta, pero todavía no existe un cuerpo materializado que pueda sustituirse.

afterResponse

Es la última fase antes de emitir la respuesta. También se ejecuta cuando before o afterRender han detenido el pipeline.

3. Resultado de un Middleware

handle() siempre debe devolver un array. Un array vacío significa que no hay cambios.

Claves admitidas:

context

return [
	'context' => [
		'id' => 42,
		'role' => 'admin'
	]
];

LoginMiddleware publica bajo el nombre Login.

body

return [
	'body' => 'Modified response'
];

En una respuesta streaming devolver body produce InvalidArgumentException, porque el stream no se materializa como string.

headers

return [
	'headers' => [
		'X-Request-Id' => 'abc123'
	]
];

status_code

return [
	'status_code' => 201
];

stop

return [
	'stop' => true,
	'status_code' => 403,
	'message' => 'Forbidden'
];

Si faltan los datos opcionales, status_code usa 500 y message usa Middleware stopped execution..

4. Estado acumulado de la fase

Además de los datos de la petición, $data incluye el estado acumulado del pipeline, entre otros:

$data['context']
$data['component_body']
$data['final_body']
$data['response_headers']
$data['status_code']
$data['is_streaming_response']
$data['is_error']
$data['error_phase']
$data['error_status_code']
$data['error_message']

5. Respuestas streaming

Cuando el componente devuelve OStreamResponse:

$data['is_streaming_response'] === true

durante afterRender y afterResponse.

Los Middlewares pueden seguir modificando:

No pueden devolver body.

El framework no envía ningún byte del stream hasta que ambas fases han terminado. Si un Middleware devuelve stop => true, el stream se descarta, se restauran las cabeceras normales y se genera una respuesta de error tradicional.

Los layouts se omiten para respuestas streaming.

6. Middlewares globales

Se configuran en src/Middleware/Middlewares.php:

OMiddleware::setGlobal([
	OMiddleware::PHASE_BEFORE => [],
	OMiddleware::PHASE_AFTER_RENDER => [],
	OMiddleware::PHASE_AFTER_RESPONSE => []
]);

7. Middlewares de ruta y grupo

Las rutas y prefix(), layout() y group() aceptan definiciones de Middlewares.

Dentro de cada fase el orden es:

global
↓
grupo exterior
↓
grupo interior
↓
ruta

8. Contexto desde ORequest

$login = $req->getMiddleware(
	'Login'
);

$id = $req->getMiddlewareValue(
	'Login',
	'id'
);

Un contexto inexistente devuelve [] y una propiedad inexistente devuelve null.

9. Contexto desde DTOs

#[ODTOField(
	required: true,
	middleware: 'Login',
	middlewareProperty: 'id'
)]
public ?int $idUser = null;

middleware y middlewareProperty deben definirse juntos. El origen Middleware no usa como alternativa los datos del cliente.

10. Estado de error en afterResponse

Después de un stop anterior, afterResponse puede consultar:

$data['is_error']
$data['error_phase']
$data['error_status_code']
$data['error_message']

11. Buenas prácticas