README

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

Installation

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

composer require northwoods/router

Usage

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');

API

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.

Router::handle($request)

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.

Credits

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

northwoods / router

Maintainers

Details