binsoul/net-http-router

Web router implementation for PSR-7 requests

net-http-router

![Software License][ico-license] , _(*1)

This package provides a web router implementation for PSR-7 requests. It uses matchers to extract information from the given request and returns a route object., _(*2)

Your application can use the information provided by the matching route to dispatch it. A dispatcher is not provided by this package., _(*3)

Install

Via composer:, _(*4)

``` bash $ composer require binsoul/net-http-router, <sub>(*5)</sub>

## Matcher

A matcher can be a closure, an object with an __invoke method or an object implementing the Matcher interface.

If a matcher decides that the route was found it can optionally set an response:

``` php
$router->addMatcher(
    function (Route $route)
    {
        if ($route->getMissingPath() == '/hello') {
            $route->found(new Response('Hello world!'));
        }
    }
);

$route = $router->match($request); // http:/domain/hello
if ($route->hasResponse()) {
    echo $route->getResponse(); // Hello world!
}

StaticMatcher

The StaticMatcher matches simple paths and sets the provided route parameters of a match., <sub>(*6)</sub>

The following example: ``` php $router->addMatcher( new StaticMatcher( [ '/blog' => ['responder' => 'Blog'] ] ) );, <sub>(*7)</sub>

$route = $router->match($request); // http://domain/blog var_export($route->getData());, <sub>(*8)</sub>

would output:
``` text
array('responder' => 'Blog',)

RegexMatcher

The RegexMatcher matches arbitrary regular expressions. Named capture group are set as parameters of the route., <sub>(*9)</sub>

The following example: ``` php $router->addMatcher( new RegexMatcher( [ '/edit/(?[0-9]+)' => ['responder' => 'Edit'] ] ) );, <sub>(*10)</sub>

$route = $router->match($request); // http://domain/edit/1 var_export($route->getData());, <sub>(*11)</sub>

would output:
``` text
array('id' => 1, 'responder' => 'Edit',)

ParameterMatcher

The ParameterMatcher matches paths with parameter placeholders., <sub>(*12)</sub>

Placeholders can be defined in the following format: ``` text [prefix+][name][=format[(length)]][?], <sub>(*13)</sub>

- Prefix: Any number of characters except "]" and "+" followed by a single "+".
- Name: A single character followed by characters, numbers or "_".
- Format: "=" followed by a defined format name optionally followed a length definition.
- Length: A single number or a number range enclosed in parenthesis.
- Marker: If the definition ends with a single "?" the parameter is optional.

For example the path:
``` text
/[year=number(4)][/+month=number(1-2)?]/[name].html

would match: ``` text /2015/09/article.html /2015/9/article.html /2015/article.html, <sub>(*14)</sub>

Found placeholders are set as parameters of the route. The following example:
``` php
$router->addMatcher(
    new ParameterMatcher(
        [
            '/[year]/[month]/[name].html' => ['responder' => 'Blog']
        ]
    )
);

$route = $router->match($request); // http://domain/2015/09/article.html
var_export($route->getData());  

would output: ``` text array('year' => '2015', 'month' => '09', 'name' => 'article', 'responder' => 'Blog',), <sub>(*15)</sub>

### NamespaceMatcher

The NamespaceMatcher allows to group other matchers under a common path prefix:

The following definition:
``` php
$matcher = new NamespaceMatcher(
    '/admin',
    [
        new StaticMatcher(
            [
                '/' => ['responder' => 'Home'],
                '/list' => ['responder' => 'List'],
            ]
        ),
        new RegexMatcher(
            [
                '/edit/(?<id>[0-9]+)' => ['responder' => 'Edit'],
            ]
        ),
    ]
);

would match: ``` text /admin/ /admin/list /admin/edit/1, <sub>(*16)</sub>

## Router

Matchers can be registered either as closures or concrete objects or as strings. If a matcher is registered as a string the provided factory is used to lazily build the matcher object.
``` php
$router->addMatcher('AccountMatcher');
$router->setFactory($factory);

// will call $factory->buildMatcher('AccountMatcher');
$router->match($request); 

Matchers are added to an internal queue which will be processed by the default router in the order they were added to the queue., <sub>(*17)</sub>

For example if the queue is build like: ``` php $router->addMatcher('Foo'); // matches /foo $router->addMatcher('Bar'); // matches /bar $router->addMatcher('Baz'); // matches /baz, <sub>(*18)</sub>

$router->match($request); // http://domain/foo/bar/baz, <sub>(*19)</sub>

The route object will change like this:
``` text
Foo is called with missing path = '/foo/bar/baz'    and matched path = ''
Bar is called with missing path = '/bar/baz'        and matched path = '/foo'
Baz is called with missing path = '/baz'            and matched path = '/foo/bar'

Testing

bash $ composer test, <sub>(*20)</sub>

License

The MIT License (MIT). Please see License File for more information., <sub>(*21)</sub>