Osumi Framework
es en eu v9.12.1 GitHub

Middlewares

Middlewares in Osumi Framework are reusable classes that participate in the HTTP request lifecycle.

They can run in three phases:

Typical uses include authentication, authorization, token validation, context loading, response transformation, headers, status codes, auditing and logging.

1. Middleware Structure

<?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 [];
	}
}

Application Middlewares are normally stored in src/Middleware/.

2. Phases

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

Traditional flow:

Routing
↓
before
↓
Component
↓
afterRender
↓
Layout
↓
afterResponse
↓
HTTP response

For streamed responses the layout is skipped and afterResponse completes before any stream bytes are sent.

before

Runs before component instantiation. Use it for authentication, authorization, validation, request blocking and context loading.

afterRender

For traditional responses it runs after component rendering and before layout processing. It can inspect or replace the body, add headers or change the status code.

For streamed responses it still runs, but there is no materialized body to replace.

afterResponse

This is the final phase before emission. It also runs after a before or afterRender stop.

3. Middleware Result

handle() must always return an array. An empty array means no changes.

Supported keys:

body

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

Returning body during a streamed response throws InvalidArgumentException, because the stream is not materialized as a string.

4. Accumulated Phase State

In addition to request data, $data includes accumulated pipeline state such as:

$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. Streamed Responses

When the component returns OStreamResponse:

$data['is_streaming_response'] === true

throughout afterRender and afterResponse.

Middlewares may still modify:

They cannot return body.

The framework emits no stream bytes until both phases finish. If a Middleware returns stop => true, the stream is discarded, normal response headers are restored and a traditional typed error response is generated.

Layouts are skipped for streamed responses.

6. Global Middlewares

Configure them in src/Middleware/Middlewares.php:

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

7. Route and Group Middlewares

Routes and prefix(), layout() and group() accept Middleware definitions.

Within each phase the order is:

global
↓
outer group
↓
inner group
↓
route

8. Context from ORequest

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

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

Missing context returns []; a missing property returns null.

9. Context from DTOs

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

middleware and middlewareProperty must be declared together. Middleware source does not fall back to client input.

10. Error State in afterResponse

After an earlier stop, afterResponse can inspect:

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

11. Best Practices