README.md

Yii Middleware Dispatcher

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

Requirements

• PHP 7.4 or higher.

Installation

The package could be installed with composer:

composer require yiisoft/middleware-dispatcher --prefer-dist

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),
    $eventDispatcher
);

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.

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. Last specified middleware will be executed first. For each middleware \Yiisoft\Middleware\Dispatcher\Event\BeforeMiddleware and \Yiisoft\Middleware\Dispatcher\Event\AfterMiddleware events are triggered.

Customizing definition syntax

Middleware definition syntax could be customized by providing your own MiddlewareFactoryInterface implementation:

use \Yiisoft\Middleware\Dispatcher\MiddlewareFactoryInterface;

class CoolMiddlewareFactory implements MiddlewareFactoryInterface
{
    private MiddlewareFactoryInterface $middlewareFactory;
    
    public function __construct(MiddlewareFactoryInterface $middlewareFactory) {
        $this->middlewareFactory = $middlewareFactory;
    }    

    public function create($middlewareDefinition): MiddlewareInterface
    {
        if (is_string($middlewareDefinition) && strpos($middlewareDefinition, '@') === 0) {
            return createMiddleware($middlewareDefinition);
        }
        
        $this->middlewareFactory->create($middlewareDefinition);
    }
}

Then it could be used like the following:

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

$dispatcher = new MiddlewareDispatcher(
    new CoolMiddlewareFactory(new MiddlewareFactory($diContainer)),
    $eventDispatcher
);

Testing

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

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

./vendor/bin/roave-infection-static-analysis-plugin

Static analysis

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

./vendor/bin/psalm

License

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

Follow updates