PSR-15 middleware dispatcher

5.0.0 2023-01-09 06:24 UTC

This package is auto-updated.

Last update: 2023-01-09 11:31:21 UTC



Yii Middleware Dispatcher

Latest Stable Version Total Downloads Build status Scrutinizer Code Quality Code Coverage Mutation testing badge static analysis type-coverage psalm-level

The package is a PSR-15 middleware dispatcher. Given a set of middleware and a request instance, dispatcher executes it produces a response instance.


  • PHP 8.0 or higher.


The package could be installed with composer:

composer require yiisoft/middleware-dispatcher

General usage

To use a dispatcher, you need to create it first:

use Yiisoft\Middleware\Dispatcher\MiddlewareDispatcher;
use Yiisoft\Middleware\Dispatcher\MiddlewareFactory;

$dispatcher = new MiddlewareDispatcher(
    new MiddlewareFactory($diContainer),

In the above $diContainer is an instance of PSR-11 \Psr\Container\ContainerInterface and $eventDispatcher is an instance of PSR-14 Psr\EventDispatcher\EventDispatcherInterface.

After dispatcher instance obtained, it should be fed with some middleware:

$dispatcher = $dispatcher->withMiddlewares([
    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 function returning a middleware such as
    static function (): MiddlewareInterface {
        return new TestMiddleware();
    The middleware returned will be executed.
  • A callback function(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface.
  • An array definition (see syntax) of middleware:
        '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:

$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:

use \Psr\Http\Message\ServerRequestInterface;
use \Yiisoft\Middleware\Dispatcher\ParametersResolverInterface;

class CoolParametersResolver implements ParametersResolverInterface
    public function resolve(array $parameters, ServerRequestInterface $request): MiddlewareInterface
        $resolvedParameters = [];
        foreach ($parameters as $parameter) {
            if ($request->getAttribute($parameter->getName()) !== null) {
                $resolvedParameters[$parameter->getName()] = $request->getAttribute($parameter->getName())
        return $resolvedParameters;

Then it could be used like the following:

use Yiisoft\Middleware\Dispatcher\MiddlewareDispatcher;
use Yiisoft\Middleware\Dispatcher\MiddlewareFactory;

$dispatcher = new MiddlewareDispatcher(
    new MiddlewareFactory($diContainer, new CoolParametersResolver()),


Unit testing

The package is tested with PHPUnit. To run tests:


Mutation testing

The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:


Static analysis

The code is statically analyzed with Psalm. To run static analysis:



The Yii Middleware Dispatcher is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Open Collective

Follow updates

Official website Twitter Telegram Facebook Slack