README

PLEASE USE phoole/middleware library instead

phossa2/middleware is another cool middleware runner library for PHP.

It requires PHP 5.4, supports PHP 7.0+ and HHVM. It is compliant with PSR-1, PSR-2, PSR-3, PSR-4, PSR-7 and the proposed PSR-5

Why another middleware runner ?

It was started to be a PSR-15 compatible middleware runner. But we don't like the single-pass approach of PSR-15. So it turns out to be a double-pass and PSR-15ish library.
Adopted nice feature of condition from woohoolabs/harmony. But we don't agree its tight-binding with dispatcher.
A couple of cool features unique to this library.

Installation

Install via the composer utility.

composer require "phossa2/middleware"

or add the following lines to your composer.json

{
    "require": {
       "phossa2/middleware": "2.*"
    }
}

Features

Able to use most of the double-pass middlewares out there.
Able to use a middleware queue (a group of middlewares) as a generic middleware in another(or the main) queue.
Able to conditionally execute a middleware or a sub queue base on a condition.
Able to branching into a subqueue and terminate when the subqueue finishes.

Usage

Create the middleware queue, then process all the middlewares.

use Phossa2\Middleware\Queue;
use Zend\Diactoros\Response;
use Zend\Diactoros\ServerRequestFactory;

// create middleware queue
$mws = new Queue([
    new LoggerMiddleware(),
    new DispatcherMiddleware()
]);

// process the queue
$response = $mws->process(ServerRequestFactory::fromGlobals(), new Response());

Or push middlewares to the queue after its instantiation,

$mws = (new Queue())
    ->push(new LoggerMiddleware())
    ->push(new DispatcherMiddleware());

Advanced

Compatibility with PSR-7 middlewares.

PSR-7 double-pass middleware with the following signature is supported,

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

function (
    RequestInterface $request,
    ResponseInterface $response,
    callable $next
) : ResponseInterface {
    // ...
}

Lots of middlewares out there then can be used without modification, such as psr7-middlewares.

Subqueue

Phossa2\Middleware\Queue implements the Phossa2\Middleware\Interfaces\MiddlewareInterface, so the queue itself can be used as a generic middleware.

// subqueue
$subQueue = new Queue([
    new ResponseTimeMiddleware(),
    new LoggingMiddleware(),
    // ...
]);

// main middleware queue
$mws = new Queue([
    $subQueue,
    new DispatcherMiddleware(),
    // ...
]);

$response = $mws->process(ServerRequestFactory::fromGlobals(), new Response());

Use of conditions

A condition is a callable with the signature of,

function (RequestInterface $request, ResponseInterface $response) : bool
{
    // ...
}

Or an instanceof Phossa2\Middleware\Interfaces\ConditionInterface.

A condition can be attached to a middleware or a subqueue. And the middleware will be executed only if the condition is evaluated to TRUE.

// add condition during instantiation
$mws = new Queue([
    [$subQueue, new DebugTurnedOnCondition()],
    new DispatcherMiddleware(),
]);

// or during the push
$mws->push(new AuthMiddleware(), new PathPrefixCondition('/user'));

Subqueue termination - branching

Sometimes, user wants the whole middleware processing terminate right after a subqueue finishes instead of continue processing the parent queue.

// use terminatable queue
$tQueue = new TerminateQueue([...]);

$mws = new Queue([
    [$tQueue, new SomeCondition()], // execute & terminate if condition true
    $mw2,
    $mw3,
    // ...
]);

$response = $mws->process($request, $response);

Change log

Please see CHANGELOG from more information.

Testing

$ composer test

Contributing

Please see CONTRIBUTE for more information.

Dependencies

PHP >= 5.4.0
phossa2/shared >= 2.0.21
A PSR-7 HTTP message implementation, such as zend-diactoros

License

MIT License

phossa2 / middleware

Maintainers

Details