Chimera - routing
![Total Downloads]
![Latest Stable Version]
![Unstable Version], (*1)
![Build Status]
![Code Coverage], (*2)
The term Chimera (_/kɪˈmɪərə/_ or /kaɪˈmɪərə/) has come to describe any
mythical or fictional animal with parts taken from various animals, or to
describe anything composed of very disparate parts, or perceived as wildly
imaginative, implausible, or dazzling., (*3)
There are many many amazing libraries in the PHP community and with the creation
and adoption of the PSRs we don't necessarily need to rely on full stack
frameworks to create a complex and well designed software. Choosing which
components to use and plugging them together can sometimes be a little
challenging., (*4)
The goal of this set of packages is to make it easier to do that (without
compromising the quality), allowing you to focus on the behaviour of your
software., (*5)
This particular package provides PSR-15 middleware and reusable request
handlers that help you to expose command and query handlers using HTTP as the
web mechanism., (*6)
Installation
You probably won't depend directly on this package, but it is available on Packagist, and can be installed it using Composer:, (*7)
composer require chimera/routing
PHP Configuration
In order to make sure that we're dealing with the correct data, we're using assert(),
which is a very interesting feature in PHP but not often used. The nice thing
about assert() is that we can (and should) disable it in production mode so
that we don't have useless statements., (*8)
So, for production mode, we recommend you to set zend.assertions to -1 in your php.ini.
For development you should leave zend.assertions as 1 and set assert.exception to 1, which
will make PHP throw an AssertionError
when things go wrong., (*9)
Check the documentation for more information: https://secure.php.net/manual/en/function.assert.php, (*10)
Components
Extension points
The packages that extend this library should implement two basic interfaces, they're
used to abstract how each routing library works:, (*11)
-
Chimera\Routing\RouteParamsExtractor: returns the list of parameters
of the matched route
-
Chimera\Routing\UriGenerator: generate routes based on the given
arguments
This middleware uses an implementation of Chimera\Routing\RouteParamsExtractor
to put the parameters of the matched route in a standard attribute, so that other components
can retrieve them., (*12)
Request handlers
-
Chimera\Handler\CreateAndFetch: executes a command to create a
resource and immediately a query, returning an unformatted response with the
query result and location header - intended to be used to handle POST
requests
-
Chimera\Handler\CreateOnly: executes a command to create a resource,
returning an empty response with the location header - intended to be used to
handle POST requests (variation of the previous one but can also be used
in asynchronous APIs)
-
Chimera\Handler\ExecuteAndFetch: executes a command to modify a
resource and immediately a query, returning an unformatted response with the
query result - intended to be used to handle PUT or PATCH requests
-
Chimera\Handler\ExecuteOnly: executes a command to modify or remove
a resource, returning an empty response - intended to be used to
handle PUT, PATCH, or DELETE requests (can also be used in
asynchronous APIs)
-
Chimera\Handler\FetchOnly: executes a query to fetch a resource,
returning an unformatted response with the query result - intended to be used
to handle GET requests
Usage
Middleware pipeline
As mentioned above content negotiation is not a responsibility of the request
handlers. It's expected that you configure lcobucci/content-negotiation-middleware
to process such task and it should be put in the very beginning of the pipeline,
so that it can process any unformatted response., (*13)
The Chimera\Routing\RouteParamsExtractor middleware should be put
right after the middleware responsible for matching routes (which changes for
each implementation)., (*14)
So a middleware pipeline in a Zend Expressive v3 application
would look like this - considering that all services are properly configured in
the DI container:, (*15)
<?php
declare(strict_types=1);
use Chimera\Routing\RouteParamsExtraction;
use Lcobucci\ContentNegotiation\ContentTypeMiddleware;
use Psr\Container\ContainerInterface;
use Zend\Expressive\Application;
use Zend\Expressive\Handler\NotFoundHandler;
use Zend\Expressive\Helper\BodyParams;
use Zend\Expressive\Helper\ServerUrlMiddleware;
use Zend\Expressive\Helper\UrlHelperMiddleware;
use Zend\Expressive\MiddlewareFactory;
use Zend\Expressive\Router\Middleware\DispatchMiddleware;
use Zend\Expressive\Router\Middleware\ImplicitHeadMiddleware;
use Zend\Expressive\Router\Middleware\ImplicitOptionsMiddleware;
use Zend\Expressive\Router\Middleware\MethodNotAllowedMiddleware;
use Zend\Expressive\Router\Middleware\RouteMiddleware;
use Zend\Stratigility\Middleware\ErrorHandler;
return function (Application $app, MiddlewareFactory $factory, ContainerInterface $container) : void {
$app->pipe(ErrorHandler::class);
$app->pipe(ServerUrlMiddleware::class);
// Handles content negotiation, ensuring that the response format is the best one
// according to what was requested via the `Accept` header
$app->pipe(ContentTypeMiddleware::class);
$app->pipe(RouteMiddleware::class);
// Puts the matched arguments in a standard place (must be executed after the
// `Zend\Expressive\Router\Middleware\RouteMiddleware` middleware, otherwise
// matched routed info is not available)
$app->pipe(RouteParamsExtraction::class);
// It's quite important to add this one to the list, so that we ensure
// that the request body is properly parsed and can be retrieved via
// `ServerRequestInterface#getParsedBody()` - used by the `HttpRequest` input
$app->pipe(BodyParams::class);
$app->pipe(ImplicitHeadMiddleware::class);
$app->pipe(ImplicitOptionsMiddleware::class);
$app->pipe(MethodNotAllowedMiddleware::class);
$app->pipe(UrlHelperMiddleware::class);
$app->pipe(DispatchMiddleware::class);
$app->pipe(NotFoundHandler::class);
};
Routes
The main idea of this package is to move your application's behaviour to the
command and query handlers, which allows them to be reused by different delivery
mechanism. This means that the logic of the request handlers are pretty much
reusable, therefore you end up having less code to maintain., (*16)
Considering that you have configured the command and query buses with the correct
handlers and also that you have mapped the instances of the request handlers in your
dependency injection container, you just need to configure the PSR-15 router to add
the handlers to the correct endpoint., (*17)
In a Zend Expressive v3 application
the config/routes.php would look like this:, (*18)
<?php
declare(strict_types=1);
use Psr\Container\ContainerInterface;
use Zend\Expressive\Application;
use Zend\Expressive\MiddlewareFactory;
/**
* Considering you have the following services in your DI container:
*
* - `album.list` => new FetchOnly(
* new ExecuteQuery(**query bus**, **message creation strategy**, MyApi\FetchAlbumList::class),
* ResponseInterface::class
* );
* - `album.find_one` => new FetchOnly(
* new ExecuteQuery(**query bus**, **message creation strategy**, MyApi\FindAlbum::class),
* ResponseInterface::class
* );
* - `album.create` => new CreateOnly(
* new ExecuteCommand(**command bus**, **message creation strategy**, MyApi\CreateAlbum::class),
* ResponseInterface::class,
* 'album.find_one',
* UriGenerator::class,
* IdentifierGenerator::class,
* 201
* );
* - `album.update_album` => new ExecuteAndFetch(
* new ExecuteCommand(**command bus**, **message creation strategy**, MyApi\UpdateAlbum::class),
* new ExecuteQuery(**query bus**, **message creation strategy**, MyApi\FindAlbum::class),
* ResponseInterface::class
* );
*/
return function (Application $app, MiddlewareFactory $factory, ContainerInterface $container) : void {
$app->get('/album', 'album.list', 'album.list');
$app->post('/album', 'album.create', 'album.create');
$app->get('/album/{id}', 'album.find_one', 'album.find_one');
$app->patch('/album/{id}', 'album.update_album', 'album.update_album');
};
License
MIT, see LICENSE., (*19)
Wallogit.com
