yiisoft/middleware-dispatcher

PSR-15 middleware dispatcher

2.0.1 2022-02-14 14:10 UTC

This package is auto-updated.

Last update: 2022-05-22 09:32:10 UTC


README

68747470733a2f2f796969736f66742e6769746875622e696f2f646f63732f696d616765732f7969695f6c6f676f2e737667

Yii Middleware Dispatcher


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

The package is a PSR-15 middleware dispatcher. Given a set of middleware and a request instance, dispatcher executes it produces 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([
    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 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. First 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

Open Collective

Follow updates

Official website Twitter Telegram Facebook Slack