API

The api documentation is broken up into 2 parts: Middleware documentation and Middleware Stack documentation.

Middleware Functions

Closure compose(array $mws, Context $ctx = null, $link_class = Link::class)

Composes a set of middleware into a handler.

<?php

$handler = mw\compose([
    function($a, $b, $next) {
        return $a . $b;
    },
    function($a, $b, $next) {
        return $next($a . 'b', $b . 'd');
    }
]);

$res = $handler('a', 'c');
assert($res === 'abcd');

The middleware stack passed in is executed in LIFO order. So the last middleware will be executed first, and the first middleware will be executed last.

After composing the stack of middleware, the resulting handler will share the same signature as the middleware except that it won’t have the $next.

$ctx will default to Context\StdContext if none is supplied, and it will be the context that is passed to the start link (see: Avanced Usage for more details).

$link_class is the class that will be constructed for the middleware link. It must be or extend Krak\Mw\Link (see: Avanced Usage for more details).

Closure composer(Context $ctx, $link_class = Link::class)

Creates a composer function that accepts a set of middleware and composes a handler.

<?php

$compose = mw\composer();
$handler = $compose([
    mw1(),
    mw2()
]);

Closure guardedComposer($composer, $msg)

Creates a composer that will automatically append a guard middleware with the given message when composing.

$compose = mw\composer();
$compose = mw\guardedComposer($compose, 'No result was returned.');
$handler = $compose([]);
$handler();
// A NoResultException will be thrown with the `No result was returned.` message
Closure group(array $mws)

Creates a new middleware composed as one from a middleware stack.

Internally, this calls the compose function, so the same behaviors will apply to this function.

<?php

/** some middleware that will append values to the parameter */
function appendMw($c) {
    return function($s, $next) use ($c) {
        return $next($s . $c);
    };
}

$handler = mw\compose([
    function($s) { return $s; },
    append('d'),
    mw\group([
        append('c'),
        append('b'),
    ]),
    append('a'),
]);

$res = $handler('');
assert($res === 'abcd');

On the surface, this doesn’t seemv very useful, but the ability group middleware into one allows you to then apply other middleware onto a group.

For example, you can do something like:

$grouped = mw\group([
    // ...
]);
mw\filter($grouped, $predicate);

In this example, we just filted an entire group of middleware

Closure lazy(callable $mw_gen)

Lazily creates and executes middleware when it’s executed. Useful if the middleware needs to be generated from a container or if it has expensive dependencies that you only want initialized if the middleware is going to be executed.

<?php

$mw = lazy(function() {
    return expensiveMw($expensive_service_that_was_just_created);
});

The expensive service won’t be created until the $mw is actually executed

Closure filter(callable $mw, callable $predicate)

Either applies the middleware or skips it depending on the result of the predicate. This if very useful for building conditional middleware.

<?php

$mw = function() { return 2; };
$handler = mw\compose([
    function() { return 1; },
    mw\filter($mw, function($v) {
        return $v == 4;
    })
]);
assert($handler(5) == 1 && $handler(4) == 2);

In this example, the stack of middleware always returns 1, however, the filtered middleware gets executed if the value is 4, and in that case, it returns 2 instead.

Invoke Functions

Closure containerAwareInvoke(Psr\Container\ContainerInterface $c, $invoke = ‘call_user_func’)
invokes middleware while checking if the mw is a service defined in the psr container.
Closure methodInvoke(string $method_name, $allow_callable = true, $invoke = ‘call_user_func’)
This will convert the middleware into a callable array like [$obj, $method_name] and invoke it. The $allow_callable parameter will allow the stack to either invoke objects with the given method or invoke callables. If you want to only allow objects with that method to be invokable, then set $allow_callable to false.

Stack Functions

Stack stack(array $entries = [])

Creates a Stack instance. This is an alias of the Stack::__construct

<?php

$stack = mw\stack([
    $mw1,
    $mw2
])->unshift($mw0);

Utility Functions

array splitArgs(array $args)

Splits arguments between the parameters and middleware.

<?php

use Krak\Mw

function middleware() {
    return function(...$args) {
        list($args, $next) = Mw\splitArgs($args);
        return $next(...$args);
    };
}

class Stack

The stack presents a mutable interface into a stack of middleware. Middleware can be added with a name and priority. Only one middleware with a given name may exist. Middleware that are last in the stack will be executed first once the stack is composed.

__construct(array $entries = [])
Creates the stack and will fill it with the given entries.
Stack fill($entries)
Pushes each entry onto the stack in the order defined.
Stack push($mw, $sort = 0, $name = null)
Pushes a new middleware on the stack. The sort determines the priority of the middleware. Middleware pushed at the same priority will be pushed on like a stack.
Stack unshift($mw, $sort = 0, $name = null)
Similar to push except it prepends the stack at the beginning.
Stack on($name, $mw, $sort = 0)
Simply an alias of push; however, the argument order lends it nicer for adding/replacing named middleware.
Stack before($name, $mw, $mw_name = null)
Inserts a middleware right before the given middleware.
Stack after($name, $mw, $mw_name = null)
Inserts a middleware right after the given middleware.
array shift($sort = 0)
Shifts the stack at the priority given by taking an element from the front/bottom of the stack. The shifted stack entry is returned as a tuple.
array pop($sort = 0)
Pops the stack at the priority given be taking an element from the back/top of the stack. The popped stack entry is returned as a tuple.
array remove($name)
Removes a named middleware. The removed middleware is returned as a tuple.
bool has($name)
Returns true if a named middleware exists in the stack
array get($name)
Returns a 3-tuple of an entry like so: [$entry, $sort, $name]. This will throw an exception if no entry is found.
Stack toTop($name)
Moves the given entry to the top of its stack to be executed first.
Stack toBottom($name)
Moves the given entry to the bottom of its stack to be executed last.
array toArray()
Normalizes the stack into an array of middleware that can be used with mw\compose
mixed __invoke(...$params)
Allows the middleware stack to be used as middleware itself.

interface Context

Represents the middleware context utilized by the internal system.

getInvoke()
Returns the invoker configured for this context.

class Context\StdContext implements Context

The default context for the mw system. It simply holds the a value to the invoker for custom invocation.

__construct($invoke = ‘call_user_func’)

class Context\ContainerContext implements Context

Provides psr container integeration by allowing the context to act like a psr container and it provides container invocation by default.

View the Container Middleware for example on this.

__construct(ContainerInterface $container, $invoke = null)
The psr container and an optional invoker if you don’t want to use the containerAwareInvoke