UPDATE FOR LATER READERS: the Pipeline project was renamed to Relay shortly after announcement.

Taking our conversation from email to Github so that others can have some input...

On Jun 5, 2015, at 12:57, Woody Gilk [email protected] wrote:

What's your vision for PipelinePHP? Do you want to roll Pipeline into Spark and share collaboration on it, or are you thinking that Pipeline should be the nexus between Spark and Radar?

I see Pipeline as the nexus between the two, and (one hopes) a wide range of other middleware systems. The idea would be, again one hopes, for a collection of middleware packages to spring up that follow the same signature and expectations. Then Radar, and Spark, and whatever-else-comes can say they are Pipeline compliant.

We're nearly ready to start prototyping with Spark and would like to get this sorted out soon so that we can collaborate more closely and work on core ADR stuff together, rather than duplicating efforts.

/me nods

As far as core ADR stuff, Pipeline might provide a good non-project-specific nexus, or maybe not. There's a case for publishing separate package that is not attached to any particular project.

Regardless, the fact that the middleware dispatching is separated out means each project gets to its own .env setup (before Pipeline), container setup (which creates Pipeline and other objects), and middleware objects (which Pipeline executes). Those surrounding pieces are where the fun and preferences live.

You've already talked about this, but I'll reiterate. I think the remaining pieces for an ADR set of interfaces are:

• An Action handler signature. It strikes me that this ought to be "just another middleware." It takes $request, $response, $next, and returns a $response. As such, it might not need an interface per se, but it would need a set of expectations on how to pick the classes for the action. Information from the routing phase might be passed as ServerRequest attributes: e.g., ['adr:input' => 'InputClassName', 'adr:domain' => 'DomainClassName', 'adr:responder' => 'ResponderClassName']. Actions would expect those to be there, and to use them appropriately (whatever that means).
• I don't know that a common Route interface would be needed, so long as the Action-related specifics of the route can be passed through to a later Action handler. Tough to type hint with a standard middleware signature in place. Alternatively, an ActionDescriptor might be good, and it would carry the input/domain/responder information, possibly along with the means to create those objects for the Action. It would still have to be passed via the $request as an attribute, maybe "adr:descriptor".
• A common Input interface sounds good. __invoke(ServerRequest $request) would be just fine, which you have in place. The return would have to be an array of params suitable for call_user_func_array().
• I don't know that a common Domain interface is really needed. call_user_func_array($domain, $input($request)) seems to cover every possible case.
• A common Responder interface is a little tricky. Although I like the idea of __invoke($request, $response, $payload = null), I have to wonder about the Payload interface at that point. Do we require one, or do we just say "$payload is whatever comes back from your Domain"?

Actual implementations of these, might go well in their own projects. That would mean an interface-only package, and then separate projects that implement them according to the desires of the implementors.

(/me wipes brow)

None of that is set in stone, obviously, but it seems like a good start combined with your spark/adr work.

Over to you!

@mindplay-dk @elazar @renan @KorvinSzanto @shadowhand --

As noted in #17, we needed to modify the middleware interface signature, but it was a BC break, thus making a major version bump necessary.

The new BC-breaking middleware interface is now in the 2.x branch. I have added some other non-BC-breaking changes, such as the run() methods that Rasmus wanted, and a Last middleware class instead of an embedded closure. Please review and test the changes; now is your chance to speak your mind, or forever hold your peace!

@andersonamuller @badlamer @bradleyboy @byoigres @calvinfroedge @clickalicious @coderabbi @coldwinds @cwscribner @davidpersson @dbonner1987 @dolfelt @elazar @FallingBullets @ferceg @garrettw @gsahr @hkulekci @hmert @hossein- @jakejohns @jensscherbl @jessupdw @johnutzm @jpcercal @khanhicetea @KingCrunch @koriym @lifesign @lku @markstory @mcrumm @Meroje @mikedfunk @mkraemer @nikolay @ojhaujjwal @pqr @ronanguilloux @shameerc @shyuan @silentworks @texdc @tuupola @websoftwares @wsuff @xduh @ytake @zanderbaldwin

tl;dr: I'll be renaming "Pipeline" to "Relay" in the near future. Read on for details.

Naming is one of the two hard things in programming.*

A commenter on Reddit pointed out that Pipeline doesn't actually implement the "pipeline" design pattern. I did look up that pattern before settling on the name, but my cursory review was insufficient. It turns out that the libary implementation is not really close enough to the pattern to be called a pipeline proper. As such, there is reason to believe programmers familiar with the pattern will be confused and/or irritated by the name.

To avoid diffusing the term "pipeline", and to honor my own desire for common vocabulary (cough Facade cough), I'll be renaming the project to "Relay." I have discovered no existing software design pattern of that name, and no other PHP project of that name. It does seem to convey the underlying operation of the libary (each request is relayed to the next middleware, and each response is relayed back in turn).

The plan is to rename the Github organization from "pipelinephp" to "relayphp", the site from "pipelinephp.com" to "relayphp.com", the library from "Pipeline.Pipline" to "Relay.Relay", the underlying classes from Pipeline* to Relay*, and the composer pacakge from "pipeline/pipeline" to "relay/relay". All your existing Github forks and checkouts should continue to work, but you will need to update your composer.json files.

I expect to accomplish this later today or early tomorrow. I will update this issue when it's done.

My apologies for having done insuffient research in the first place, and for this ensuing hassle. Thank you for your patience with this early-stage project.

(* The others are cache-clearing and off-by-one errors.)

Since ->withAttribute and ->getAttribute only exist on \Psr\Http\Message\ServerRequestInterface which is immutable, important things that need to be passed through by a middleware might not be available on the way out. An example of this being an issue is maybe a cookie encrypting middleware:

class CookieEncryptor
{

    use CookieEncryptingTrait, CookieDecryptingTrait, CookieSerializingTrait;

    public function __invoke($request, $response)
    {
        // Before the router
        $cookies = $this->decryptedCookies($request);
        $request = $request->withAttribute('cookies', $cookies);

        $response = $next($request, $response);
        // After the router
        // $request and $cookies may have been replaced, but we have no way to know.
        return $response->withHeader('Set-cookie', $this->serializeCookies($this->encryptedCookies($cookies->getModified())));
    }

}

One way to fix this is to append a reversed version of the queue onto the queue before sending a request and response, but then the middleware has to maintain state and the recommended way of catching the response on the way out becomes confusing.

Thoughts?

The correct way to detect for objects that can be used as iterators is against the Traversable interface. This works for ArrayObject and any other objects that implement iterator interfaces.

http://php.net/traversable

Fixes #21

Currently, the __invoke() method of Relay use array_shift to get the next middleware from the queue. I think it should better to use next() to get the element without remove it, so the queue should be used multiple times:

$dispatcher = new Relay([$middleware1, $middleware2]);

$response = $dispatcher(new ServerRequest(), new Response());
$response2 = $dispatcher(new ServerRequest(), new Response());

Documentation suggests that $next is callable, but the $next is always a Runner instance, which doesn't implement __invoke

function (
    Request $request, // the request
    callable $next // the next middleware or handler
) : Response {
    // ...
}

Error handlers are middleware with an arity of four and can be invoked by adding a third argument to the $next call.

Invoking an error:

$next($request, $response, 'error occurred');

Middleware signature:

function($error, $request, $response, $next)

What's nice about error handlers is that when an error is invokved (via an exception, or a call to next with three arguments) you can go through the error handler queue and have a logger, maybe an error page render, etc.

Any plans on implementing something similar to Relay?

My understanding - with PSR-15, you have MiddlewareInterface and RequestHandlerInterface - both of which essentially are means to the same end - getting a Response instance back. In Relay, if you don't "cap" the end, you'll get an error. So in the documentation, there's this:

$queue[] = new FooMiddleware();
$queue[] = new BarMiddleware();
$queue[] = new BazMiddleware();
// ...
$queue[] = new ResponseFactoryMiddleware {
    return new Response();
};

My question - would it not be better to add support for RequestHandlerInterface items in the queue and not just MiddlewareInterface ones? So in Runner.php

if ($middleware instanceof MiddlewareInterface) {
   return $middleware->process($request, $this);
}

// this is what i propose we add, too:
if ($middleware instanceof RequestHandlerInterface) {
   return $middleware->handle($request);
}

This way, you can add a definitive end to your queue, or even pass off to an entirely different Relay queue thanks to Relay implementing RequestHandlerInterface...

It's not a wild change and sure, I could typically wrap what I need in an open-ended Middleware. It feels though that adding the above would avoid such workarounds whilst supporting the rest of PSR-15 and allowing you to cap things off properly.

Hello :)

One side-effect of middleware stacks seems to be very long exception stacks when something goes wrong. I heard a term 'trampolining' as a way to reduce this issue and thought it might be a good feature request. I think, basically, the technique unwinds the stack periodically. I guess this would mean a large change to the way middlewares are dispatched because you'd not be able to just call middleware A which then calls B which then calls C etc. Instead you'd have to use a loop or similar.

Something to ponder, maybe?

Robert

(This comes from https://github.com/oscarotero/psr7-middlewares/issues/34)

It should be great to have the posibility of using the dispatcher as a middleware of other dispatcher. Example:

use Relay\Runner;

$group = new Runner([
    new Middleware1(),
    new Middleware2(),
]);

$dispatcher = new Runner([
    $group,
    new Middleware3()
]);