Routing

Routing in Osumi Framework is managed by the ORoute class. It maps incoming HTTP requests (URLs) to specific Components that act as actions.

Routes are typically defined in PHP files located within the src/Routes/ directory. You can create multiple files in this folder to organize your routes logically (e.g., one file per module).

When a user accesses a URL, ORoute locates the path, resolves the effective Middleware pipeline, then instantiates the component and calls run(), passing a user-defined DTO, a generic ORequest, or no parameter depending on the component signature.

Defining Routes

To define a route, use the static methods of ORoute corresponding to the HTTP verbs: get(), post(), put(), or delete().

Basic Syntax

use Osumi\OsumiFramework\Routing\ORoute;
use Osumi\OsumiFramework\App\Module\Home\Index\IndexComponent;

ORoute::get('/', IndexComponent::class);

Route Parameters

Route methods such as get(), post(), put() and delete() accept:

• URL (string): The path to respond to.
• Component (string): The FQCN of the component to execute.
• Middlewares (array, optional): Middleware classes grouped by execution phase.
• Layout (string|null, optional): A specific layout component for the route.

Middlewares

Middlewares participate in the request lifecycle in three phases:

• before
• afterRender
• afterResponse

See /docs/en/concepts/middlewares.md for the complete Middleware lifecycle and result format.

Example:

use Osumi\OsumiFramework\App\Middleware\AuditMiddleware;
use Osumi\OsumiFramework\App\Middleware\LoginMiddleware;
use Osumi\OsumiFramework\App\Module\User\Profile\ProfileComponent;
use Osumi\OsumiFramework\Core\OMiddleware;
use Osumi\OsumiFramework\Routing\ORoute;

ORoute::post(
	'/profile',
	ProfileComponent::class,
	[
		OMiddleware::PHASE_BEFORE => [
			LoginMiddleware::class
		],
		OMiddleware::PHASE_AFTER_RESPONSE => [
			AuditMiddleware::class
		]
	]
);

Grouping Routes

Osumi Framework provides three ways to group routes that share common characteristics.

Middleware definitions assigned to route groups are accumulated with nested groups and with route-specific Middlewares.

Within each phase, execution order is:

global
↓
outer group
↓
inner group
↓
route

1. Prefixes

Use prefixes when multiple routes share the same URL start. Prefixes can be nested; each nested prefix is appended to the active prefix.

use Osumi\OsumiFramework\App\Middleware\AdminAuthMiddleware;
use Osumi\OsumiFramework\Core\OMiddleware;

ORoute::prefix(
	'/api',
	static function (): void {
		ORoute::get('/health', HealthComponent::class);

		ORoute::prefix(
			'/admin',
			static function (): void {
				ORoute::post('/login', LoginComponent::class);
				ORoute::get('/me', MeComponent::class);
			},
			[
				OMiddleware::PHASE_BEFORE => [
					AdminAuthMiddleware::class
				]
			]
		);
	}
);

This registers /api/health, /api/admin/login, and /api/admin/me.

2. Layouts

Use ORoute::layout() when multiple routes share the same visual structure.

ORoute::layout(
	MainLayoutComponent::class,
	static function (): void {
		ORoute::get('/home', HomeComponent::class);
		ORoute::get('/contact', ContactComponent::class);
	}
);

layout() can also receive Middleware definitions as its third argument.

3. Groups (Prefix + Layout)

ORoute::group() combines a prefix and a layout assignment. Groups can be nested with other groups or prefixes.

ORoute::group(
	'/admin',
	AdminLayoutComponent::class,
	static function (): void {
		ORoute::group(
			'/users',
			UserLayoutComponent::class,
			static function (): void {
				ORoute::get('/profile', ProfileComponent::class);
			}
		);
	}
);

The route above is registered at /admin/users/profile and uses UserLayoutComponent.

group() can receive Middleware definitions as its fourth argument.

URL Normalization

All static ORoute methods normalize URLs. Leading slashes are made consistent, repeated slashes are collapsed, and trailing slashes are removed except for the root URL /.

For example:

ORoute::prefix('/api/', static function (): void {
	ORoute::prefix('//admin///', static function (): void {
		ORoute::get('//users/', UsersComponent::class);
	});
});

This registers /api/admin/users.

Static Views

Use ORoute::view() to serve a static file or a simple template without a full action component.

ORoute::view('/about-us', 'about-us.html');

Static view routes can also receive Middleware definitions.

Parameters on Routes

URLs can define parameters using the :name syntax.

ORoute::get('/user/:id', UserComponent::class);
ORoute::get('/location/:name', LocationComponent::class);

A component using run(ORequest $req) can access them using methods such as getParamInt('id') or getParamString('name').

Summary of ORoute Methods

Best Practices

• Organize by file: Create different files in src/Routes/ for each module or functional area.
• Use Middlewares: Keep components clean by moving cross-cutting request/response logic to Middlewares.
• Use phase constants: Prefer OMiddleware::PHASE_* constants.
• Class constants: Use ::class notation for components, layouts and Middlewares.