Stacks are middlewares too

[schnittstabil]

This is a consistent continuation of #2 and allows reusing Stack as ServerMiddlewareInterface in other Middleware containers:

// I've used the splat operator:
$stack = new Stack($middlewareOne, $middlewareTwo);

$middlewares = [
   // …
   new AwesomePsrMiddleware(),
   // …
   $stack,
   // …
];

// some foreign stack container:
$foreign = new MiddlewareContainer($middlewares, …);
$foreign->dispatch($request);

See #6 for deatils.

[shadowhand]

I think I prefer the idea that a stack can also be a middleware. That allows for mixing of different dispatching systems (if they also follow the same methodology) and allows mixing groups of middleware that may be packaged together.

However, the order of middleware is sometimes important and this may cause surprises. I need to think about it some more.

Any thoughts @equip/contributors ?

[shadowhand]

This is not correct. The default should not be a delegate, because this is perfectly acceptable for $default:

$default = [$responseFactory, 'createResponse'];

[shadowhand]

You lost this, which destroys the ability to ensure type safety of middleware added by the constructor.

[shadowhand]

Again, this is not right. The default is not a delegate.

[schnittstabil]

However, the order of middleware is sometimes important and this may cause surprises.

That is true, but not in this case. A container manages a group of middlewares, thus the order is only important within that container. For middleware stacks, where middlewares are called from last to first, it works like that:

$stack = new Stack(...[
    $middleware5,
    $middleware4,
    new Stack(...[
        $middleware3,
        $middleware2,
    ]),
    $middleware1,
    $middleware0,
]);

If one mixes containers, e.g. with pipes, where middlewares are called from first to last, we get:

$stack = new Pipe(...[
    $middleware0,
    $middleware1,
    new Stack(...[
        $middleware3,
        $middleware2,
    ]),
    $middleware4,
    $middleware5,
]);

It looks confusing, but it is the expected behavior. The order within the pipe and stack is correct according to their semantics.

[schnittstabil]

@shadowhand: lgtm – ready for review.

[schnittstabil]

But I just realized, that the Equip\Dispatch\Stack is actually a Pipe, not a Stack!

[shadowhand]

Typo: nextContanierDelegate should be nextContainerDelegate

[shadowhand]

I'm not really sure about this change. What does splat buy us here? From a syntax standpoint, it is more to type out. From a functionality standpoint, all it does it splat and unsplat the arguments, which consumes ticks unnecessarily.

[shadowhand]

Okay, we're getting off track here. I want to see two changes, made as separate PRs:

• move $default to the constructor as the first argument
• implement ServerMiddlewareInterface in Stack

[schnittstabil]

Ah, I see – but that doesn't make sense in my opinion, e.g:

$inner = new Stack($default1, ...$middleware);

$outer = new Stack($default2, ...[
    // …
    $inner,
    $nextMiddleware,
    // …
]);

$outer->dispatch($request);

It is not only because we have to create two $default functions/instances. It is also confusing, because it is not obvious, which $default will be called. $default1, $default2 or both?

Instead I suggest:

$inner = new Stack(...$middleware);

$outer = new Stack(...[
    // …
    $inner,
    $nextMiddleware,
    // …
]);

$outer->dispatch($request, $default);

Thus, I think it is more obvious that $inner delegates the request to $outer, which delegates the request to $nextMiddleware.

Of course, in last version the splat became useless…

[shadowhand]

Equip\Dispatch\Stack is actually a Pipe, not a Stack!

A totally valid point. Let's address that after #3 and #4 are finished.

[shadowhand]

Okay cool. I'm going to take this as-is and then make some tweaks. Will make PR for you to check out.