Proposal to remove request, response decorators from zend-stratigility v2.

readme.md

[zend-stratigility] RFC: Remove request, response decorators

Currently, we have a Zend\Stratigility\Http namespace that contains:

• Request, a decorator for PSR-7 requests that provides access to the original request instance at server invocation.
• ResponseInterface, which provides the methods write(), end(), and isComplete().
• Response, which decorates a PSR-7 response to provide access to the original response instance at server invocation, and implements the above ResponseInterface.

These are used internally specifically in the FinalHandler, but nowhere else. If the proposal to remove the FinalHandler and error middleware is approved, there is no longer an internal use case for them.

Middleware that might have used the ability to access the original request/response can instead be rewritten to accept these via setters, and such applications can then have middleware that executes in the outermost (or a relatively outer) layer in order to inject the instance(s):

function ($request, $response, $next) use ($middlewaresNeedingOriginals) {
    array_walk($middlewaresNeedingOriginals, function ($middleware) use ($request, $response) {
        // You could also test for interface or implemented methods before invocation:
        $middleware->setOriginalRequest($request);
        $middleware->setOriginalResponse($response);
    });
    return $next($request, $response);
}

Regarding usage of write() and end(): using these features locks developers into Stratigility; using these methods makes middleware non-portable. As such, deprecating it would encourage developers to write portable middleware.

Additionally, it will simplify the internals of MiddlewarePipe, as two methods (used to decorate incoming request/response instances) can be removed.

Target release is 2.0.

We would need to do the following in the 1.X series:

• Mark the various classes in the Zend\Stratigility\Http namespace as deprecated.
• Mark the new methods in Zend\Stratigility\Http\Request and Response as deprecated (may not be necessary, if the class is marked as such), or raise E_USER_DEPRECATED errors when they are invoked, indicating users should not rely on them. (The one issue with this latter approach is that FinalHandler calls on getOriginalRequest() currently.)