binsoul/net-http-dispatcher

Dispatcher using named parameters to invoke callables or methods of objects

net-http-dispatcher

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

This package allows to map arbitrary names to dispatchable objects using named parameters provided in a context array. Dispatchable objects are then invoked to return a response. They can be surrounded by middleware to alter the incoming request or the outgoing response., _(*2)

Install

Via composer:, _(*3)

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

## Responder

A responder can be a closure, an object with an __invoke method or an object with multiple methods. It can receive the request object, the context object or any value from the context as parameters and it has to return a response. 

The dispatcher resolves parameters via reflection. If a parameter cannot be resolved and is not optional an exception is thrown.

For example the responder "blog.edit" will receive the following parameters: 
``` php
$dispatcher->addResponder(
    'blog.edit',
    function ($id, RequestInterface $request, Context $context, $optional = 'foo')
    {
        // $id = 1
        // $request = object
        // $context = object
        // $optional = 'foo'

        return new Response(...);
    }
);

$dispatcher->handle($request, ['responder' => 'blog.edit', 'id' => 1]);

Middleware

Middleware can be a closure or an object with an __invoke method. It has to accept a request, a context and the next middleware as parameters and it has to return a response., <sub>(*5)</sub>

For example middleware may or may not perform the various optional processes: ``` php $middleware = function (RequestInterface $request, Context $context, callable $next) { // optionally return a response early if (...) { return new Response(...); }, <sub>(*6)</sub>

// optionally modify the request
$request = $request->withUri(..);

// optionally modify the context
$context = $context->withParameter(...);

// invoke the $next middleware
$response = $next($request, $context);

// optionally modify the response
$response = $response->withStatus(...);

// always return a response
return $response;

};, <sub>(*7)</sub>

## Dispatcher

A dispatcher uses the information provided by a context array to find a responder. The default keys are "responder" to indicate which responder should be invoked and "method" to indicate which method of the responder should be called.  

The used array keys can be configured. The following example maps the reponder to the array key "controller" and the method to "action": 
``` php
class BlogController
{
    public function index()
    {
        return new Response(...);
    }
}

$dispatcher->addResponder('blog', new BlogController());

$dispatcher->defineParameters('controller', 'action');

// will invoke BlogController->index()
$dispatcher->handle($request, ['controller' => 'blog', 'action' => 'index']); 

Responders can be registered either as closures or concrete objects or as strings. If a responder is registered as a string the provided factory is used to lazily build responders. ``` php $dispatcher->addResponder('blog', 'BlogResponder'); $dispatcher->setFactory($factory);, <sub>(*8)</sub>

// will call $factory->buildResponder('BlogResponder'); $dispatcher->handle($request, ['responder' => 'blog']);, <sub>(*9)</sub>

The same applies to registering middlewares.
``` php
$dispatcher->addMiddleware('AuthMiddleware')
$dispatcher->setFactory($factory);

// will call $factory->buildMiddleware('AuthMiddleware');
$dispatcher->handle($request, ['responder' => 'blog']); 

Middleware is added to an internal queue which surrounds the final call to the responder., <sub>(*10)</sub>

For example if the queue is build like: ``` php $dispatcher->addResponder('blog', 'BlogResponder');, <sub>(*11)</sub>

$dispatcher->addMiddleware('Foo'); $dispatcher->addMiddleware('Bar'); $dispatcher->addMiddleware('Baz');, <sub>(*12)</sub>

$dispatcher->handle($request, ['controller' => 'blog']);, <sub>(*13)</sub>

The request and response path through the middlewares will look like this:
``` text
Foo is 1st on the way in
    Bar is 2nd on the way in
        Baz is 3rd on the way in
            BlogResponder is invoked        
        Baz is 1st on the way out
    Bar is 2nd on the way out
Foo is 3rd on the way out

Testing

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

License

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