README

adagio/middleware library allows to implement middlewares with various data types easily.

Installation

Install Composer and run the following command to get the latest version:

composer require adagio/middleware

Quick start

todo.

Middlewares principles

A middleware signature MUST include the input data, the output data to hydrate and the next middleware to call.
A middleware MUST return a valid output data.
A middle ware CAN process data before or after calling the next midleware.
The very last middleware "hidden in the stack" just returns the output data.

Transition to middlewares

Imagine you want to add a middleware pipeline to an existing image-editing library.

Here is the way you can do it without middlewares:

// I want to solarize, rotate, unblur and then sepia my image (parameters are 
// voluntarily omitted for clarity).
$image = (new SepiaFilter)
    ->filter((new UnblurFilter)
    ->filter((new RotateFilter)
    ->filter((new SolarizedFilter)
    ->filter(new Image('/path/to/image')))));

Problems are:

you have to declare the pipeline backward
big parenthesis mess
you cannot declare a pipeline to use on other images later

With adagio/middleware, you can do it easily:

use Adagio\Middleware\Stack;

$pipe = new Stack([
    new SolarizedFilter,
    new RotateFilter,
    new UnblurFilter,
    new SepiaFilter,
]);

$image = $stack(new Image('/path/to/image'));

Filters have just to respect the following signature convention:

function (Image $image, callable $next): Image
{
    // Maybe do something with $image
    
    $resultingImage = $next($image);
    
    // Maybe do something with $resultingImage
    
    return $resultingImage;
}

Each filter must pass the $image to the $next element of the pipe and can modify it before of after passing it.

Filters can be any callable respecting the given signature.

More complex example: DB query processing

Middlewares are even more useful when the given and the returned objects are different. Think about a SQL query processor with the following signature:

function (SqlQuery $query, ResultSet $resultSet, callable $next): ResultSet

You can then provide a caching middleware:

final class QueryCache
{
    // ...

    public function __invoke(SqlQuery $query, ResultSet $resultSet, callable $next): ResultSet
    {
        // If the query is already in cache, return the ResultSet and don't 
        // trigger the rest of the middleware stack
        if ($this->resultSetCache->hasQuery($query)) {
            return $this->resultSetCache->getFromQuery($query);
        }

        $finalResultSet = $next($query, $resultSet);

        $this->resultSetCache->add($query, $finalResultSet);

        return $finalResultSet;
    }
}

You can also provide a middleware that translates from a SQL standard to another, a SQL validator, a client-side cluster/shard solution, a logger, a performance monitor, ...

adagio / middleware

Maintainers