Download the PHP package bitexpert/adroit without Composer

bitexpert/adroit

This package provides a PSR-7 compatible ADR middleware.

Installation

The preferred way of installing bitexpert/adroit is through Composer. Simply add bitexpert/adroit as a dependency:

Usage

The configure the \bitExpert\Adroit\AdroitMiddleware middleware you need provide an array of \bitExpert\Adroit\Action\Resolver\ActionResolver, an array of \bitExpert\Adroit\Responder\Resolver\ResponderResolver and a action request attribute telling adroit where to look for the action identifier.

ActionResolver

As the name implies ActionResolvers are responsible for resolving an action class instance from the so-called actionToken. The actionToken is basically used to identify a route. Adroit comes with a default implementation of an ActionResolver which uses any container-interop compatible DI container as a backend.

Of course you may implement your own ActionResolvers using the (\bitExpert\Adroit\Action\ActionResolver) interface.

ResponderResolver

Similar to the ActionResolvers the ResponderResolvers are responsible for resolving an responder class instance from the $type defined in the DomainPayload instance. Adroit comes with a default implementation of an ResponderResolver (\bitExpert\Adroit\Responder\Resolver\ContainerAwareResponderResolver) which uses any container-interop compatible DI container as a backend.

Of course you may implement your own ResponderResolvers using the ResponderResolver interface.

(Domain)Payload

You may define your own payload class(es) by implementing the \bitExpert\Adroit\Domain\Payload interface. This gives you the opportunity to freely define the payload according to your needs. This example implementation will be used in the documentation as follows:

Actions

In case you want to implement your own action logic (who does not want that?) you may use any callable following the signature of the Action interface or create your own Action class and implement the interface.

Action classes are allowed to either return an object which implements the Payload interface or an PSR-7 response object implementing the \Psr\Http\Message\ResponseInterface interface. By default you should aim to return a Payload object. The PSR-7 response might come in handy when you have to deal with file downloads where you most likely not want to read the file in your action class, push the content to the responder just to to write it to the response message body.

Responders

Responders have to return a PSR-7 response object. Responders are not forced to implement the Responder interface so you may use Closures as well but implementing the interface is recommended:

Usage

Since Adroit provides a handy set of middlewares to achieve ADR you simply have to configure your ActionResolver(s) and ResponderResolver(s). For the following example we use the ArrayContainer of bitexpert/specialist which are configured using an array of mappings between the action identifier and the action and the domain payload type to the appropriate responder:

As you can see, you also may use simple callables as actions and responders.

Adroit itself does not depend on a concrete PSR-7 implementation which means you should be able to use it in your set-up without running into problems. Just for the unit tests Adroit depends on zendframework/zend-diactoros as a PSR-7 implementation.

Middleware hooks

Adroit provides several hooks to be as flexible as a standard middleware pipe while implementing the ADR paradigm.

You may use the following hooks to manipulate things in between the execution of the middlewares needed for ADR itself:

These hooks allow great flexibility but with great flexibility also comes great responsibility ;-) Please note that the hooks are named "before" and so are to implement the middlewares:

Of course you may implement it different, but that would not hit the "before" in the hook name. Please be aware of that!

Routing

To avoid external dependencies we removed routing from Adroit since this may be achieved by using any routing mechanism you like. You just need to ensure that action identifying value will be set to a request attribute of your choice and tell the ActionMiddleware where to look for it.

License

Adroit is released under the Apache 2.0 license.