Deprecate Http subnamespace

doc/book/migration/to-v2.md

@@ -8,6 +8,55 @@ To help you prepare your code for version 2, version 1.3.0 provides several
 forwards compatibility features to assist you in the process. However, some
 changes will still require changes to your code following the 2.0 release.
 
+## Original request, response, and URI
+
+In the original 1.X releases, Stratigility would decorate the request and
+response instances with `Zend\Stratigility\Http\Request` and
+`Zend\Stratigility\Http\Response`, respectively. This was done originally to
+facilitate access to the incoming request in cases of nested layers, where the
+URI path may have been truncated (`Next` truncates matched paths when executing
+a layer if a path was provided when piping the middleware).
+
+Internally, prior to 1.3, only `Zend\Stratigility\FinalHandler` was still using
+this functionality:
+
+- It would query the original request to get the original URI when creating a
+  404 response message.
+- It passes the decorated request and response instances to `onerror` handlers.
+
+Starting with 1.3.0, we now deprecate these message decorators, and recommend
+against their usage.
+
+If you still need access to the original request, response, or URI instance, we
+recommend the following:
+
+- Pipe `Zend\Stratigility\Middleware\OriginalMessages` as the outermost layer of
+  your application. This will inject the following request attributes into
+  layers beneath it:
+    - `originalRequest`, mapping to the request provided to it at invocation.
+    - `originalResponse`, mapping to the response provided to it at invocation.
+    - `originalUri`, mapping to the URI composed by the request provided to it at
+      invocation.
+
+You can then access these values within other middleware:
+
+```php
+$originalRequest = $request->getAttribute('originalRequest');
+$originalResponse = $request->getAttribute('originalResponse');
+$originalUri = $request->getAttribute('originalUri');
+```
+
+Internally, starting with 1.3.0, we have updated the request decorator to add
+the `originalRequest` attribute, and the `FinalHandler` to check for this,
+instead of the decorated instance.
+
+Finally, if you are creating an `onerror` handler for the `FinalHandler`, update
+your typehints to refer to the PSR-7 request and response interfaces instead of
+the Stratigility decorators, if you aren't already.
+
+The `Zend\Stratigility\Http` classes, interfaces, and namespace will be removed
+in version 2.0.0.
+
 ## Error handling
 
 Prior to version 1.3, the recommended way to handle errors was via
@@ -95,3 +144,6 @@ The following classes, methods, and arguments are deprecated starting in version
 - The `$err` argument to `Zend\Stratigility\Next`'s `__invoke()` method.
   Starting in 1.3.0, if a non-null value is encountered, this method will now
   emit an `E_USER_DEPRECATED` notice, referencing this documentation.
+- `Zend\Stratigility\Http\Request` (class)
+- `Zend\Stratigility\Http\ResponseInterface` (interface)
+- `Zend\Stratigility\Http\Response` (class)

src/FinalHandler.php

@@ -121,7 +121,7 @@ public function setOriginalResponse(ResponseInterface $response = null)
      * @param mixed $error
      * @param RequestInterface $request Request instance.
      * @param ResponseInterface $response Response instance.
-     * @return Http\Response
+     * @return ResponseInterface
      */
     private function handleError($error, RequestInterface $request, ResponseInterface $response)
     {
@@ -148,7 +148,7 @@ private function handleError($error, RequestInterface $request, ResponseInterfac
      *
      * @param RequestInterface $request Request instance.
      * @param ResponseInterface $response Response instance.
-     * @return Http\Response
+     * @return ResponseInterface
      */
     private function create404(RequestInterface $request, ResponseInterface $response)
     {
@@ -204,11 +204,14 @@ private function createDevelopmentErrorMessage($error)
      * If the request is not an Http\Request, casts it to one prior to invoking
      * the error handler.
      *
+     * If the response is not an Http\Response, casts it to one prior to invoking
+     * the error handler.
+     *
      * @param mixed $error
      * @param RequestInterface $request
-     * @param Http\Response $response
+     * @param ResponseInterface $response
      */
-    private function triggerError($error, RequestInterface $request, Http\Response $response)
+    private function triggerError($error, RequestInterface $request, ResponseInterface $response)
     {
         if (! isset($this->options['onerror'])
             || ! is_callable($this->options['onerror'])
@@ -220,7 +223,7 @@ private function triggerError($error, RequestInterface $request, Http\Response $
         $onError(
             $error,
             ($request instanceof Http\Request) ? $request : new Http\Request($request),
-            $response
+            ($response instanceof Http\Response) ? $response : new Http\Response($response)
         );
     }
 
@@ -235,8 +238,7 @@ private function triggerError($error, RequestInterface $request, Http\Response $
      */
     private function getUriFromRequest(RequestInterface $request)
     {
-        if ($request instanceof Http\Request) {
-            $original = $request->getOriginalRequest();
+        if (false !== ($original = $request->getAttribute('originalRequest', false))) {
             return $original->getUri();
         }
 
@@ -246,20 +248,13 @@ private function getUriFromRequest(RequestInterface $request)
     /**
      * Write the given message to the response and mark it complete.
      *
-     * If the message is an Http\Response decorator, call and return its
-     * `end()` method; otherwise, decorate the response and `end()` it.
-     *
      * @param ResponseInterface $response
      * @param string $message
-     * @return Http\Response
+     * @return ResponseInterface
      */
     private function completeResponse(ResponseInterface $response, $message)
     {
-        if ($response instanceof Http\Response) {
-            return $response->write($message);
-        }
-
-        $response = new Http\Response($response);
-        return $response->write($message);
+        $response->getBody()->write($message);
+        return $response;
     }
 }

src/Http/Request.php

@@ -18,6 +18,10 @@
  *
  * Decorates the PSR incoming request interface to add the ability to
  * manipulate arbitrary instance members.
+ *
+ * @deprecated since 1.3.0; to be removed with 2.0.0. Track the original
+ *     request via a request attribute or via a service instead; you can
+ *     use Zend\Stratigility\Middleware\OriginalMessages to do so.
  */
 class Request implements ServerRequestInterface
 {
@@ -50,7 +54,9 @@ public function __construct(
         }
 
         $this->originalRequest = $originalRequest;
-        $this->psrRequest      = $decoratedRequest->withAttribute('originalUri', $originalRequest->getUri());
+        $this->psrRequest      = $decoratedRequest
+            ->withAttribute('originalUri', $originalRequest->getUri())
+            ->withAttribute('originalRequest', $originalRequest);
     }
 
     /**
@@ -60,6 +66,16 @@ public function __construct(
      */
     public function getCurrentRequest()
     {
+        trigger_error(sprintf(
+            '%s is now deprecated. The request passed to your method is the current '
+            . 'request now. %s will no longer be available starting in Stratigility 2.0.0. '
+            . 'Please see https://docs.zendframework.com/migration/to-v2/#original-request-response-and-uri '
+            . 'for full details.',
+            __CLASS__,
+            \Zend\Stratigility\Middleware\OriginalMessages::class,
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         return $this->psrRequest;
     }
 
@@ -70,6 +86,17 @@ public function getCurrentRequest()
      */
     public function getOriginalRequest()
     {
+        trigger_error(sprintf(
+            '%s is now deprecated. Please register %s as your outermost middleware, '
+            . 'and pull the original request via the request "originalRequest" '
+            . 'attribute. %s will no longer be available starting in Stratigility 2.0.0. '
+            . 'Please see https://docs.zendframework.com/migration/to-v2/#original-request-response-and-uri '
+            . 'for full details.',
+            __CLASS__,
+            \Zend\Stratigility\Middleware\OriginalMessages::class,
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         return $this->originalRequest;
     }
 

src/Http/Response.php

@@ -18,6 +18,11 @@
  *
  * Adds in write, end, and isComplete from RequestInterface in order
  * to provide a common interface for all PSR HTTP implementations.
+ *
+ * @deprecated since 1.3.0; to be removed with 2.0.0. Track the original
+ *     response via a request attribute or via a service instead; you
+ *     can use Zend\Stratigility\Middleware\OriginalMessages to do so. We
+ *     recommend that you use only the methods defined in PSR-7.
  */
 class Response implements
     PsrResponseInterface,
@@ -48,6 +53,16 @@ public function __construct(PsrResponseInterface $response)
      */
     public function getOriginalResponse()
     {
+        trigger_error(sprintf(
+            '%s is now deprecated. Please register %s as your outermost middleware, '
+            . 'and pull the original response via the request "originalResponse" '
+            . 'attribute. %s will no longer be available starting in Stratigility 2.0.0. '
+            . 'Please see https://docs.zendframework.com/migration/to-v2/#original-request-response-and-uri '
+            . 'for full details.',
+            __CLASS__,
+            \Zend\Stratigility\Middleware\OriginalMessages::class,
+            __METHOD__
+        ), E_USER_DEPRECATED);
         return $this->psrResponse;
     }
 
@@ -62,6 +77,15 @@ public function getOriginalResponse()
      */
     public function write($data)
     {
+        trigger_error(sprintf(
+            '%s is now deprecated; use $response->getBody()->write(). '
+            . '%s will no longer be available starting in Stratigility 2.0.0. '
+            . 'Please see https://docs.zendframework.com/migration/to-v2/#deprecated-functionality '
+            . 'for full details.',
+            __CLASS__,
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         if ($this->complete) {
             throw $this->responseIsAlreadyCompleted(__METHOD__);
         }
@@ -84,6 +108,15 @@ public function write($data)
      */
     public function end($data = null)
     {
+        trigger_error(sprintf(
+            '%s is now deprecated; use $response->getBody()->write(). '
+            . '%s will no longer be available starting in Stratigility 2.0.0. '
+            . 'Please see https://docs.zendframework.com/migration/to-v2/#deprecated-functionality '
+            . 'for full details.',
+            __CLASS__,
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         if ($this->complete) {
             return $this;
         }
@@ -106,6 +139,15 @@ public function end($data = null)
      */
     public function isComplete()
     {
+        trigger_error(sprintf(
+            '%s is now deprecated; use $response->getBody()->write(). '
+            . '%s will no longer be available starting in Stratigility 2.0.0. '
+            . 'Please see https://docs.zendframework.com/migration/to-v2/#deprecated-functionality '
+            . 'for full details.',
+            __CLASS__,
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         return $this->complete;
     }
 

src/Http/ResponseInterface.php

@@ -17,6 +17,9 @@
  * - Write to the content
  * - End the response (mark it complete)
  * - Determine if the response is complete
+ *
+ * @deprecated since 1.3.0; to be removed with 2.0.0. Do not use the methods
+ *     defined in this interface; use only those defined in PSR-7.
  */
 interface ResponseInterface
 {

src/Middleware/OriginalMessages.php

@@ -0,0 +1,52 @@
+<?php
+/**
+ * @link      http://github.com/zendframework/zend-stratigility for the canonical source repository
+ * @copyright Copyright (c) 2016 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Stratigility\Middleware;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Zend\Stratigility\MiddlewareInterface;
+
+/**
+ * Inject attributes containing the original request, response, and URI instances.
+ *
+ * This middleware will add request attributes as follows:
+ *
+ * - "originalRequest", representing the request provided to this middleware.
+ * - "originalResponse", representing the response provided to this middleware.
+ * - "originalUri", representing the URI composed by the request provided to
+ *   this middleware.
+ *
+ * These can then be reference later, for tasks such as:
+ *
+ * - Determining the base path when generating a URI (as layers may receive
+ *   URIs stripping path segments).
+ * - Determining if changes to the response have occurred.
+ * - Providing prototypes for factories.
+ */
+class OriginalMessages implements MiddlewareInterface
+{
+    /**
+     * @param ServerRequestInterface $request
+     * @param ResponseInterface $response
+     * @param null|callable $next
+     * @return ResponseInterface
+     */
+    public function __invoke(ServerRequestInterface $request, ResponseInterface $response, callable $next = null)
+    {
+        if (! $next) {
+            return $response;
+        }
+
+        $request = $request
+            ->withAttribute('originalUri', $request->getUri())
+            ->withAttribute('originalRequest', $request)
+            ->withAttribute('originalResponse', $response);
+
+        return $next($request, $response);
+    }
+}