atanvarno / router
FastRoute PSR-7 wrapper
Requires
- php: ^7.0
- fig/http-message-util: ^1.1.2
- nikic/fast-route: ^1.2.0
- psr/http-message: ^1.0.1
- psr/simple-cache: ^1.0.0
Requires (Dev)
- atanvarno/cache-apcu: ^0.1.1
- http-interop/http-factory-diactoros: 0.2.0
- phpunit/phpunit: ^6.0.8
This package is auto-updated.
Last update: 2024-10-08 22:39:38 UTC
README
A PSR-7 wrapper for FastRoute.
Requirements
PHP >= 7.0 is required, but the latest stable version of PHP is recommended.
Installation
$ composer require atanvarno/router:^0.2.0
Basic Usage
Two routers are provided:
SimpleRouter
and
CachedRouter
.
These both implement the
Router
interface.
Instantiation
// A simple, non-caching, router: use Atanvarno\Router\SimpleRouter; $router = new SimpleRouter(); // A caching router: use Atanvarno\Router\CachedRouter; $router = new CachedRouter();
By default, the GroupCountBased
FastRoute
driver is used. Other drivers may be specified in the router constructor
using the Router::DRIVER_*
constants.
See SimpleRouter::__construct() and CachedRouter::__construct().
Defining routes
Routes can be defined by using the add()
method, the addGroup()
method or
via constructor injection. There are also shortcut methods for every HTTP
method.
add()
$router->add($method, $pattern, $handler);
The $method
is an uppercase HTTP method string for which a certain route
should match. It is possible to specify multiple valid methods using an array.
There is a Router::METHOD_*
constant for each valid HTTP method.
By default the $pattern
uses a syntax where {foo}
specifies a placeholder
with name foo
and matching the regex [^/]+
. To adjust the pattern the
placeholder matches, you can specify a custom pattern by writing {bar:[0-9]+}
.
Custom patterns for route placeholders cannot use capturing groups. For example
{lang:(en|de)}
is not a valid placeholder, because ()
is a capturing group.
Instead you can use either {lang:en|de}
or {lang:(?:en|de)}
.
Furthermore parts of the route enclosed in [...]
are considered optional, so
that /foo[bar]
will match both /foo
and /foobar
. Optional parts are only
supported in a trailing position, not in the middle of a route.
The $handler
parameter does not necessarily have to be a callback, it could
also be a controller class name or any other kind of data you wish to associate
with the route. Atanvarno\Router only tells you which handler corresponds to
your request, how you interpret it is up to you.
add()
implements a fluent interface,
allowing multiple calls to be chained.
See Router::add().
addGroup()
You can specify routes inside of a group. All routes defined inside a group will have a common prefix.
For example, defining your routes as:
$router->addGroup( '/admin', [ [Router::METHOD_GET, '/user/{name}', 'handler'] [Router::METHOD_DELETE, '/user/{name}', 'handler'], ] );
Will have the same result as:
$router->add(Router::METHOD_GET, '/admin/user/{name}', 'handler') ->add(Router::METHOD_DELETE, '/admin/user/{name}', 'handler');
addGroup()
implements a fluent interface,
allowing multiple calls to be chained.
See Router::addGroup().
Constructor injection
Route information can be injected into the Router
instance constructor. This
parameter accepts an array of arrays containing $method
, $pattern
and
$handler
values, like a call to add()
.
This allows routes to be held in a separate configuration file that returns such an array:
<?php // routes.php use Atanvarno\Router\Router; return [ [Router::METHOD_GET, '/user[/{id:\d+}[/{name}]]', 'handler'], [Router::METHOD_PATCH, '/table/{tid}/{uid}/{data}', 'handler'], //... ];
<?php // main.php use Atanvarno\Router\{Router, SimpleRouter}; $router = new SimpleRouter(Router::DRIVER_GROUP_COUNT, include 'path/to/routes.php');
See SimpleRouter::__construct() and CachedRouter::__construct().
Shortcut methods
For all the valid HTTP request methods shortcut methods are available. For example:
$router->get('/get-route', 'get_handler') ->post('/post-route', 'post_handler'); // Is equivalent to: $router->add(Router::METHOD_GET, '/get-route', 'get_handler') ->add(Router::METHOD_POST, '/post-route', 'post_handler');
Shortcut methods implement a fluent interface, allowing multiple calls to be chained.
See Router.
Dispatching
A request is dispatched by calling the dispatch()
method. This method accepts
a PSR-7 RequestInterface
instance.
$request = //... define your PSR-7 request. $result = $router->dispatch($request);
Note that all URI paths are normalised so that they have no trailing slash and begin with a leading slash. All user supplied patterns are likewise normalised.
dispatch()
returns an array whose first element contains a status code. It is
one of FastRoute\Dispatcher::NOT_FOUND
,
FastRoute\Dispatcher::METHOD_NOT_ALLOWED
or FastRoute\Dispatcher::FOUND
.
For the method not allowed status the second array element contains a list of
HTTP methods allowed for the supplied request.
NOTE: The HTTP specification requires that a
405 Method Not Allowed
response include theAllow:
header to detail available methods for the requested resource. Applications using Router should use the second array element to add this header when relaying a 405 response.
For the found status the second array element is the handler that was associated with the route and the third array element is a dictionary of placeholder names to their values. For example:
// Routing against GET /user/atan/42 [FastRoute\Dispatcher::FOUND, 'handler0', ['name' => 'atan', 'id' => '42']]
See Router::dispatch()
.
Caching
Instead of using SimpleRouter
you can use CachedRouter
.
CachedRouter
requires a PSR-16 cache
object as a constructor parameter.
By default, CachedRouter
will take its dispatch data directly from the cache
and bypass and routes defined by add()
calls or constructor injection. Where
no dispatch data is available (for example on the first dispatch()
call or if
the cache data has expired) CachedRouter
will generate dispatch data from the
defined routes and store it in the cache.
If your route configuration has changed and you need to update the dispatch
data in the cache, call refreshCache()
.
See CachedRouter.
Exceptions
All exceptions thrown implement the interface RouterException
.
Rather than supply array
results, dispatch()
can instead throw exceptions
for not found and method not allowed results.
MethodNotAllowedException::getAllowed()
provides a list of allowed methods for the required Allow:
response header.
The package contains these exceptions:
A Note on HEAD Requests
The HTTP specification requires servers to support both GET and HEAD methods:
The methods GET and HEAD MUST be supported by all general-purpose servers
To avoid forcing users to manually register HEAD
routes for each resource we
fallback to matching an available GET
route for a given resource. Applications
MAY always specify their own HEAD
method route for a given resource to bypass
this behavior entirely.
Full API
See API.