Skip to content
Fast router for PSR-15 request handlers
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Northwoods Router

Build Status Code Quality Code Coverage Latest Stable Version Total Downloads License

A FastRoute based router designed to be used with PSR-15 middleware.


The best way to install and use this package is with composer:

composer require northwoods/router


The router implements MiddlewareInterface and can be used with any middleware dispatcher, such as Broker.

use Northwoods\Router\Router;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

$router = new Router();
$router->get('user.list', '/users', $userList);
$router->get('user.detail', '/users/{id:\d+}', $userDetail);
$router->post('user.create', '/users', $userCreate);

assert($router instanceof Psr\Http\Server\MiddlewareInterface);

This is the preferred usage of the router, as it ensures that the request is properly set up for the route handler. Generally the router should be the last middleware in the stack.

If you prefer to use the router without middleware, the router also implements RequestHandlerInterface and can be used directly:

/** @var ServerRequestInterface */
$request = /* create server request */;

/** @var ResponseInterface */
$response = $router->handle($request);

Route Handlers

All route handlers MUST implement the RequestHandlerInterface interface:

namespace Acme;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

class UserListHandler implements RequestHandlerInterface
    public function handle(ServerRequestInterface $request): ResponseInterface
        /** @var array */
        $users = /* load from database, etc */;

        return new Response(200, ['content-type' => 'application-json'], json_encode($users));

If it is preferable to lazy load handlers, the lazy-middleware package can be used:

use Northwoods\Middleware\LazyHandlerFactory;

/** @var LazyHandlerFactory */
$lazyHandler = /* create the factory */;

$router->post('user.create', '/users', $lazyHandler->defer(CreateUserHandler::class));

Reverse Routing

Reverse routing enables generating URIs from routes:

$uri = $router->uri('user.detail', ['id' => 100]);

assert($uri === '/users/100');


Router::add($name, $route);

Add a fully constructed route.

Router::get($name, $pattern, $handler)

Add a route that works for HTTP GET requests.

Router::post($name, $pattern, $handler)

Add a route that works for HTTP POST requests.

Router::put($name, $pattern, $handler)

Add a route that works for HTTP PUT requests.

Router::patch($name, $pattern, $handler)

Add a route that works for HTTP PATCH requests.

Router::delete($name, $pattern, $handler)

Add a route that works for HTTP DELETE requests.

Router::head($name, $pattern, $handler)

Add a route that works for HTTP HEAD requests.

Router::options($name, $pattern, $handler)

Add a route that works for HTTP OPTIONS requests.

Router::process($request, $handler)

Dispatch routing as a middleware.

If no route is found, the $handler will be used to generate the response.


Dispatch routing for a request.

If no route is found, a response with a HTTP 404 status will be returned.

If a route is found, but it does not allow the request method, a response with a HTTP 405 will be returned.


Borrows some ideas from zend-expressive-fastroute for handling reverse routing.

You can’t perform that action at this time.