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, runs filters, then instantiates the component and calls run(), passing a user defined DTO or a generic ORequest.

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

• URL (string): The path to respond to.
• Component (string): The FQCN (Fully Qualified Class Name) of the component to execute.
• Filters (array, optional): A list of filter classes to execute before the component.
• Layout (string, optional): A specific layout component for this route.

Filters

Filters are classes executed before the main component. They are commonly used for authentication (checking tokens), logging, or request validation.

Docs: /docs/en/concepts/filters.md

use Osumi\OsumiFramework\App\Filter\LoginFilter;
use Osumi\OsumiFramework\App\Module\User\Profile\ProfileComponent;

ORoute::post('/profile', ProfileComponent::class, [LoginFilter::class]);

Grouping Routes

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

1. Prefixes

Use prefixes when multiple routes share the same URL start (e.g., an API). Prefixes can be nested; each nested prefix is appended to the active prefix.

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

  ORoute::prefix('/admin', function(): void {
    ORoute::post('/login', LoginComponent::class);
    ORoute::get('/me', MeComponent::class, [AdminAuthFilter::class]);
  });
});

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

2. Layouts

Used when multiple routes share the same visual structure (header, footer, etc.).

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

3. Groups (Prefix + Layout)

Combines a prefix and layout assignment in a single block. Groups can be nested with other groups or prefixes; their URL prefixes accumulate, and each group applies its layout to the routes declared inside it.

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

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

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 /. This applies to get(), post(), put(), delete(), view(), group(), and prefix().

For example, nested prefixes with extra slashes:

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

Register the route at /api/admin/users.

Static Views

If you need to serve a static file or a simple template without the logic of a full action component, use ORoute::view().

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

Parameters on routes

URLs can be defined to have parameters on them using the :name syntax.

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

The method run(ORequest $req) of the component can then access that parameter 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 of your app.
• Use Filters: Keep your components clean by offloading authentication and validation logic to filters.
• Class Constants: Always use ::class notation for components and filters to benefit from IDE autocompletion and static analysis.