celemas/router

PSR-7/PSR-15 router and dispatcher

0.2.0 2026-05-02 16:53 UTC

Requires

• php: ^8.5
• duon/wire: v0.5.0
• psr/container: ^2.0
• psr/http-message: ^1.1 || ^2.0
• psr/http-message-implementation: ^1.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0

Requires (Dev)

• duon/dev: ^3.0
• laminas/laminas-diactoros: ^3.3

MIT

• Ernst

README

A PSR-7/PSR-15 compatible router and view dispatcher.

Using your PSR-7 request and response factory:

<?php

use Celemas\Router\Dispatcher;
use Celemas\Router\Router;
use Celemas\Router\RoutingHandler;

$router = new Router();
$router->get('/{name}', function (string $name) use ($responseFactory) {
	$response = $responseFactory->createResponse();
	$response->getBody()->write("<h1>{$name}</h1>");

	return $response;
});

$handler = new RoutingHandler($router, new Dispatcher());
$response = $handler->handle($request);

Routes

Define routes directly or inside callback groups. Configure groups only inside the group callback. Groups apply their prefix, name prefix, middleware, Before handlers, After handlers, and controller to every route in the group, even when those settings are declared after the route lines in the callback.

use Celemas\Router\Group;

$router->get('/health', [HealthController::class, 'show'], 'health');
$router->map(['GET', 'POST'], '/login', [AuthController::class, 'login'], 'login');
$router->any('/webhook', $webhook, 'webhook');

$router->group('/albums', function (Group $albums) use ($auth): void {
	$albums->get('', 'index', 'albums.index');
	$albums->get('/{id:\d+}', 'show', 'albums.show');
	$albums->post('', 'create', 'albums.create');

	$albums->middleware($auth);
	$albums->controller(AlbumController::class);
});

Preferred route actions are callables and controller method arrays:

$router->get('/status', fn() => $response);
$router->get('/albums', [AlbumController::class, 'index']);

Inside a controller group, use bare method names:

$router->group('/admin', function (Group $admin): void {
	$admin->controller(AdminController::class);
	$admin->get('', 'index', 'admin.index');
});

Dispatching

RoutingHandler implements PSR-15 RequestHandlerInterface. It matches the request through the router and dispatches the matched route through the dispatcher.

Routing exceptions bubble by default. Catch NotFoundException for 404 responses and MethodNotAllowedException for 405 responses.

Use the low-level match API when you need route inspection before dispatching:

$match = $router->match($request);
$response = (new Dispatcher())->dispatch($request, $match);

Middleware and handlers run in this order:

1. Dispatcher middleware
2. Route middleware
3. View middleware attributes
4. Before handlers immediately before the view
5. View execution
6. After handlers for rendering or response changes

Use PSR middleware for cross-cutting request/response behavior. Use Before for final request changes before the view. Use After to render arbitrary view data or modify a response.

URL generation

Use named routes through the router. Generated URLs include the router prefix and fail fast when path params are missing, unknown, or do not match route constraints.

$router = new Router('/cms');
$router->get('/albums/{id:\d+}', $view, 'albums.show');

$url = $router->url(
	'albums.show',
	['id' => 13],
	query: ['tab' => 'tracks'],
);
// /cms/albums/13?tab=tracks

Static assets stay separate from named routes:

$router->addStatic('/assets', __DIR__ . '/public/assets', 'assets');

$css = $router->asset('assets', 'app.css', bust: true);

License

This project is licensed under the MIT license.