README

Lightweight PSR-friendly routing for Horizom applications, built on top of FastRoute.

The package provides:

• HTTP route registration for all common verbs
• Group prefixes, middleware and attributes
• Resource-style route generation
• Redirect and permanent redirect helpers
• PSR-11 container based handler resolution
• Lazy handler resolution for lower bootstrap cost
• PSR-15 compatible request dispatching

Requirements

• PHP 8.0+
• A PSR-11 container

Installation

composer require horizom/routing

Quick Start

Use RouterFactory when you want eager handler resolution, or RouterLazyFactory when handlers should be resolved only when a route is matched.

<?php

declare(strict_types=1);

use Horizom\Routing\RouterFactory;
use Nyholm\Psr7\ServerRequest;
use Psr\Container\ContainerInterface;

$container = /* PSR-11 container */;

$router = (new RouterFactory())->create($container);

$router->get('/users/{id}', App\Http\Controllers\UserController::class . '@show');

$request = new ServerRequest('GET', '/users/42');
$response = $router->getRouter()->handle($request);

Registering Routes

The router supports the usual HTTP verbs plus map() and any().

$router->get('/health', App\Http\Controllers\HealthController::class . '@show');
$router->post('/users', App\Http\Controllers\UserController::class . '@store');
$router->map(['GET', 'POST'], '/search', App\Http\Controllers\SearchController::class . '@handle');
$router->any('/webhook', App\Http\Controllers\WebhookController::class . '@handle');

Supported handler styles:

• Controller::class . '@method'
• InvokableController::class
• [Controller::class, 'method']
• Closures returning a Psr\Http\Message\ResponseInterface

Route Groups

Groups let you share a common prefix and route metadata.

$router->group([
    'prefix' => '/api',
    'namespace' => 'App\\Http\\Controllers\\Api\\',
    'middleware' => ['auth'],
    'attributes' => ['version' => 'v1'],
], function ($router): void {
    $router->get('/users', 'UserController@index');
    $router->get('/users/{id}', 'UserController@show');
});

Group metadata is applied to every route created inside the callback.

Resource Routes

resource() generates the conventional CRUD endpoints for a controller.

$router->resource('/posts', App\Http\Controllers\PostController::class);

Generated route names:

• posts.index
• posts.create
• posts.store
• posts.show
• posts.edit
• posts.update
• posts.destroy

You can limit the generated endpoints with only or except.

$router->resource('/posts', App\Http\Controllers\PostController::class, [
    'only' => ['index', 'show'],
]);

$router->resource('/posts', App\Http\Controllers\PostController::class, [
    'except' => ['destroy'],
]);

To register multiple resources at once:

$router->resources([
    '/posts' => App\Http\Controllers\PostController::class,
    '/comments' => App\Http\Controllers\CommentController::class,
]);

Redirects

$router->redirect('/old-path', '/new-path');
$router->redirectPermanently('/legacy', '/canonical');

Factories

RouterFactory

RouterFactory builds a router with eager handler resolution.

$router = (new RouterFactory())->create($container);

RouterLazyFactory

RouterLazyFactory defers handler resolution until route compilation/matching.

use Horizom\Routing\RouterLazyFactory;

$router = (new RouterLazyFactory())->create($container);

Error Handling

RouterHandler throws typed exceptions for common routing failures:

• Horizom\Routing\Exceptions\NotFoundException with code 404
• Horizom\Routing\Exceptions\MethodNotAllowedException with code 405

MethodNotAllowedException::getAllowedMethods() returns the HTTP methods accepted by the matched route.

Testing And Validation

Run the package checks with:

vendor/bin/phpstan analyse src tests --level=9
vendor/bin/phpunit --testdox

The test suite covers route registration, resource filtering, group metadata, redirects, factories, lazy resolution, invocation, dispatching and exception behavior.

Notes

• Route handlers must declare a non-null ResponseInterface return type.
• Route definitions become immutable once compiled.
• Middleware entries must be strings or Psr\Http\Server\MiddlewareInterface implementations.

License

MIT. See LICENSE.md.