Rename $handler to $next

[andersonamuller]

I think it reads and expresses better the concept.

interface MiddlewareInterface
{
    /**
     * Process an incoming server request and return a response, optionally delegating
     * response creation to a handler.
     *
     * @param ServerRequestInterface $request
     * @param RequestHandlerInterface $next
     *
     * @return ResponseInterface
     */
    public function process(ServerRequestInterface $request, RequestHandlerInterface $next);
}

class AwesomeMiddleware implements MiddlewareInterface
{
    /**
     * {@inheritdoc}
     */
    public function process(ServerRequestInterface $request, RequestHandlerInterface $next) 
    {
        $response = $next->handle($request);

        return $response->withHeader('X-Awesome', 'true');
    }
}

[shadowhand]

What if the $next is not a pointer to another middleware?

[andersonamuller]

In the context of the AwesomeMiddleware class you can never know if it is THE final handler of the request or another middleware, but you can always know that it is the NEXT thing to handle the request.

[shadowhand]

Doesn't that argument cut both ways? You know the $handler is going to generate a response aka "handle the request" so why should it be called $next?

[andersonamuller]

No, because the next may be a middleware, and by the middleware contract it may just process the request.

[shadowhand]

The type is RequestHandler $handler. Whether or not that handler calls a middleware is completely irrelevant.

[andersonamuller]

So, again, in the context of middleware with the type RequestHandler you know you can call the handle method in the next handler of the request. Calling the variable the same as the type doesn't always make it more clear. In the post by ircmaxell that originate the current changes, it's called frame. It's a suggestion, to me it reads better, I opened the issue to see if it resonates with more people.

$response = $next->handle($request);

VS

$response = $handler->handle($request);

[mnapoli]

I opened the issue to see if it resonates with more people.

👍 It does with me.

Using the generic $handler name may have theoretical value but it's unhelpful in practice. And practice trumps theory. For the record I also disagree that it's theoretically better, but maybe I'm wrong on that. But on the "practice" side I'm convinced that $next is the better option.

$next is very important in middlewares, that's how I explain the pattern every single time. With PSR-15 I started to wonder whether I should update my slides or workshop to use $handler instead of $next, but in the end I didn't.

$handler is not helpful, $next makes more sense in real life.

[danizord]

IMHO the issue with $next name is that it may confuse people thinking that it is the next middleware itself, while this is not true. It is a RequestHandler (often a middleware dispatcher) that may or not call the next middleware internally.

[shadowhand]

Since the FIG repository is the place where this needs to be changed first, can you open a PR there? That would be a better venue for continued discussion. Thanks!