Yii Middleware Dispatcher
[](https://packagist.org/packages/yiisoft/middleware-dispatcher)
[](https://packagist.org/packages/yiisoft/middleware-dispatcher)
[](https://github.com/yiisoft/middleware-dispatcher/actions/workflows/build.yml)
[](https://codecov.io/gh/yiisoft/middleware-dispatcher)
[](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/middleware-dispatcher/master)
[](https://github.com/yiisoft/middleware-dispatcher/actions?query=workflow%3A%22static+analysis%22)
[](https://shepherd.dev/github/yiisoft/middleware-dispatcher)
[](https://shepherd.dev/github/yiisoft/middleware-dispatcher)
The package is a [PSR-15](https://www.php-fig.org/psr/psr-15/) middleware dispatcher. Given a set of middleware and a
request instance, dispatcher executes it and produces a response instance.
## Requirements
- PHP 8.1 - 8.5.
## Installation
The package could be installed with [Composer](https://getcomposer.org):
```shell
composer require yiisoft/middleware-dispatcher
```
## General usage
To use a dispatcher, you need to create it first:
```php
use Yiisoft\Middleware\Dispatcher\MiddlewareDispatcher;
use Yiisoft\Middleware\Dispatcher\MiddlewareFactory;
$dispatcher = new MiddlewareDispatcher(
new MiddlewareFactory($diContainer),
$eventDispatcher
);
```
In the above `$diContainer` is an instance of [PSR-11](https://www.php-fig.org/psr/psr-11/) `\Psr\Container\ContainerInterface`
and `$eventDispatcher` is an instance of [PSR-14](https://www.php-fig.org/psr/psr-14/) `Psr\EventDispatcher\EventDispatcherInterface`.
After dispatcher instance obtained, it should be fed with some middleware:
```php
$dispatcher = $dispatcher->withMiddlewares([
TeapotAccessChecker::class,
static function (): ResponseInterface {
return new Response(418);
},
]);
```
In the above we have used a callback. Overall the following options are available:
- A controller handler action in format `[TestController::class, 'index']`. `TestController` instance will be created and
`index()` method will be executed.
- A name of PSR-15 middleware class. The middleware instance will be obtained from container.
- A name of PSR-15 request handler class. The request handler instance will be obtained from container and executed.
- An identifier of container definition for PSR-15 middleware. The middleware instance will be obtained from container and executed.
- A name or instance of invokable class. If the name of invokable class is provided, the instance will be
obtained from container and executed.
- A function returning a middleware such as
```php
static function (): MiddlewareInterface {
return new TestMiddleware();
}
```
The middleware returned will be executed.
- A function returning a request handler such as
```php
static function (): RequestHandlerInterface {
return new SimpleRequestHandler();
}
```
The request handler returned will be executed.
- A callback `function(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface`.
- An array definition (see [syntax](https://github.com/yiisoft/definitions#arraydefinition)) of middleware:
```php
[
'class' => MyMiddleware::class,
'__construct()' => [
'someVar' => 42,
],
]
```
For handler action and callable typed parameters are automatically injected using dependency injection container.
Current request and handler could be obtained by type-hinting for `ServerRequestInterface` and `RequestHandlerInterface`.
After middleware set is defined, you can do the dispatching:
```php
$request = new ServerRequest('GET', '/teapot');
$response = $dispatcher->dispatch($request, $this->getRequestHandler());
```
Given a request dispatcher executes middleware in the set and produces response. First specified middleware will be
executed first. For each middleware
`\Yiisoft\Middleware\Dispatcher\Event\BeforeMiddleware` and `\Yiisoft\Middleware\Dispatcher\Event\AfterMiddleware`
events are triggered.
### Creating your own implementation of parameters resolver
Parameters resolver could be customized by providing your own `ParametersResolverInterface` implementation:
```php
use \Psr\Http\Message\ServerRequestInterface;
use \Yiisoft\Middleware\Dispatcher\ParametersResolverInterface;
class CoolParametersResolver implements ParametersResolverInterface
{
public function resolve(array $parameters, ServerRequestInterface $request): array
{
$resolvedParameters = [];
foreach ($parameters as $name => $parameter) {
if ($request->getAttribute($name) !== null) {
$resolvedParameters[$name] = $request->getAttribute($name)
}
}
return $resolvedParameters;
}
}
```
Then it could be used like the following:
```php
use Psr\Container\ContainerInterface;
use Yiisoft\Middleware\Dispatcher\MiddlewareDispatcher;
use Yiisoft\Middleware\Dispatcher\MiddlewareFactory;
use Yiisoft\Middleware\Dispatcher\ParametersResolverInterface;
/**
* @var ContainerInterface $container
* @var ParametersResolverInterface $resolver
* @var EventDispatcherInterface $eventDispatcher
*/
$dispatcher = new MiddlewareDispatcher(new MiddlewareFactory($container, $resolver), $eventDispatcher);
```
To combine several parameters' resolvers use `CompositeParametersResolver`:
```php
use Psr\Container\ContainerInterface;
use Psr\EventDispatcher\EventDispatcherInterface;
use Yiisoft\Middleware\Dispatcher\CompositeParametersResolver;
use Yiisoft\Middleware\Dispatcher\MiddlewareDispatcher;
use Yiisoft\Middleware\Dispatcher\MiddlewareFactory;
use Yiisoft\Middleware\Dispatcher\ParametersResolverInterface;
/**
* @var ContainerInterface $container
* @var ParametersResolverInterface $resolver1
* @var ParametersResolverInterface $resolver2
* @var EventDispatcherInterface $eventDispatcher
*/
$dispatcher = new MiddlewareDispatcher(
new MiddlewareFactory($container, new CompositeParametersResolver($resolver1, $resolver2)),
$eventDispatcher,
);
```
## Documentation
- [Internals](docs/internals.md)
If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
## License
The Yii Middleware Dispatcher is free software. It is released under the terms of the BSD License.
Please see [`LICENSE`](./LICENSE.md) for more information.
Maintained by [Yii Software](https://www.yiiframework.com/).
## Support the project
[](https://opencollective.com/yiisoft)
## Follow updates
[](https://www.yiiframework.com/)
[](https://twitter.com/yiiframework)
[](https://t.me/yii3en)
[](https://www.facebook.com/groups/yiitalk)
[](https://yiiframework.com/go/slack)