Merge branch 'feature/final-handler-deprecation' into develop

Close #66

.travis.yml

@@ -6,6 +6,7 @@ cache:
   directories:
     - $HOME/.composer/cache
     - $HOME/.local
+    - vendor
     - zf-mkdoc-theme
 
 env:
@@ -18,8 +19,6 @@ env:
 
 matrix:
   include:
-    - php: 5.4
-    - php: 5.5
     - php: 5.6
       env:
         - EXECUTE_CS_CHECK=true
@@ -30,9 +29,12 @@ matrix:
   allow_failures:
     - php: hhvm
 
-before_script:
-  - composer self-update
-  - composer install --prefer-source
+before_install:
+  - travis_retry composer self-update
+
+install:
+  - travis_retry composer install
+  - composer show --installed
 
 script:
   - composer test

CHANGELOG.md

@@ -10,11 +10,61 @@ details.
 
 ### Added
 
-- Nothing.
+- [#66](https://github.com/zendframework/zend-stratigility/pull/66) adds a new
+  class, `Zend\Stratigility\Middleware\NotFoundHandler`. This class may be piped
+  into an application at an innermost layer; when invoked, it will return a 404
+  plain text response.
+
+- [#66](https://github.com/zendframework/zend-stratigility/pull/66) adds a new
+  class, `Zend\Stratigility\Middleware\ErrorHandler`. This class may be piped
+  into an application, typically at the outermost or one of the outermost
+  layers. When invoked, it does the following:
+
+  - Creates a PHP error handler that will re-throw PHP errors as
+    `ErrorExceptions`.
+  - Dispatches to the next layer.
+  - If the next layer does not return a response, it raises a new
+    `MissingResponseException`.
+  - Catches all exceptions from calling the next layer, and passes them to an
+    error response generator to return an error response.
+
+  A default error response generator is provided, which will return a 5XX series
+  response in plain text. You may provide a callable generator to the
+  constructor in order to customize the response generated; please refer to the
+  documentation for details.
+
+- [#66](https://github.com/zendframework/zend-stratigility/pull/66) adds a new
+  class, `Zend\Stratigility\NoopFinalHandler`. This class may be provided as the
+  `$out` argument to a `MiddlewarePipe`, or as the final handler to
+  `Zend\Diactoros\Server::listen()` (in which case it will be passed to the
+  middleware you invoke as the application). This handler returns the response
+  provided to it verbatim.
 
 ### Deprecated
 
-- Nothing.
+- [#66](https://github.com/zendframework/zend-stratigility/pull/66) deprecates
+  the `Zend\Stratigility\FinalHandler` class. We now recommend using the
+  `NoopFinalHandler`, along with the `ErrorHandler` and `NotFoundHandler`
+  middleware (or equivalents) to provide a more fine-grained, flexible, error
+  handling solution for your applications.
+
+- [#66](https://github.com/zendframework/zend-stratigility/pull/66) deprecates
+  the `Zend\Stratigility\Dispatch` class. This class is used internally by
+  `Next`, and deprecation should not affect the majority of users.
+
+- [#66](https://github.com/zendframework/zend-stratigility/pull/66) deprecates
+  `Zend\Stratigility\ErrorMiddlewareInterface`. We recommend instead using
+  exceptions, along with the `ErrorHandler`, to provide error handling for your
+  application.
+
+- [#66](https://github.com/zendframework/zend-stratigility/pull/66) updates
+  `Zend\Stratigility\MiddlewarePipe::__invoke()` to emit a deprecation notice if
+  no `$out` argument is provided, as version 2 will require it.
+
+- [#66](https://github.com/zendframework/zend-stratigility/pull/66) updates
+  `Zend\Stratigility\Next::__invoke()` to emit a deprecation notice if
+  a non-null `$err` argument is provided; middleware should raise an exception,
+  instead of invoking middleware implementing `ErrorMiddlewareInterface`.
 
 ### Removed
 

composer.json

@@ -20,14 +20,14 @@
     }
   },
   "require": {
-    "php": "^5.4.8 || ^7.0",
-    "psr/http-message": "~1.0.0",
-    "zendframework/zend-escaper": "~2.3"
+    "php": "^5.6 || ^7.0",
+    "psr/http-message": "^1.0",
+    "zendframework/zend-escaper": "^2.3"
   },
   "require-dev": {
-    "zendframework/zend-diactoros": "~1.0",
+    "zendframework/zend-diactoros": "^1.0",
     "phpunit/phpunit": "^4.7 || ^5.5",
-    "squizlabs/php_codesniffer": "^2.3.1"
+    "squizlabs/php_codesniffer": "^2.6.2"
   },
   "suggest": {
     "psr/http-message-implementation": "Please install a psr/http-message-implementation to consume Stratigility; e.g., zendframework/zend-diactoros"

doc/book/api.md

@@ -14,7 +14,7 @@ class MiddlewarePipe implements MiddlewareInterface
     public function __invoke(
         Psr\Http\Message\ServerRequestInterface $request = null,
         Psr\Http\Message\ResponseInterface $response = null,
-        callable $out = null
+        callable $out
     ) :  Psr\Http\Message\ResponseInterface;
 }
 ```
@@ -31,18 +31,25 @@ Middleware is executed in the order in which it is piped to the `MiddlewarePipe`
 exhausted (`MiddlewarePipe` passes the `$response` instance it receives to `FinalHandler` as well,
 so that the latter can determine if the response it receives is new).
 
+> ### $out is no longer optional
+>
+> Starting in version 1.3.0, we now raise a deprecation notice if no argument is
+> passed for `$out`; starting in version 2.0.0, the argument will be required.
+> Always pass a `Next` instance, a `Zend\Stratigility\NoopFinalHandler`
+> instance, or a custom callback; we no longer recommend the `FinalHandler`
+> implementation.
+
 The callable should use the same signature as `Next()`:
 
 ```php
 function (
     Psr\Http\Message\ServerRequestInterface $request,
-    Psr\Http\Message\ResponseInterface $response,
-    $err = null
+    Psr\Http\Message\ResponseInterface $response
 ) : Psr\Http\Message\ResponseInterface
 ```
 
-Internally, `MiddlewarePipe` creates an instance of `Zend\Stratigility\Next`, feeding it its queue,
-executes it, and returns a response.
+Internally, `MiddlewarePipe` creates an instance of `Zend\Stratigility\Next`,
+feeding it its queue, executes it, and returns a response.
 
 ## Next
 
@@ -60,8 +67,7 @@ class Next
 {
     public function __invoke(
         Psr\Http\Message\ServerRequestInterface $request,
-        Psr\Http\Message\ResponseInterface $response,
-        $err = null
+        Psr\Http\Message\ResponseInterface $response
     ) : Psr\Http\Message\ResponseInterface;
 }
 ```
@@ -70,6 +76,13 @@ You should **always** either capture or return the return value of `$next()` whe
 application. The expected return value is a response instance, but if it is not, you may want to
 return the response provided to you.
 
+> ### $err argument
+>
+> Technically, `Next::__invoke()` accepts a third, optional argument, `$err`.
+> However, as of version 1.3.0, this argument is deprecated, and usage will
+> raise a deprecation notice during runtime. We will be removing the argument
+> entirely starting with version 2.0.0.
+
 As examples:
 
 ### Providing an altered request:
@@ -150,12 +163,12 @@ And, if not calling `$next()`, returning the response instance:
 return $response;
 ```
 
-The `FinalHandler` implementation will check the `$response` instance passed when invoking it
-against the instance passed during instantiation, and, if different, return it. As such, `return
-$next(/* ... */)` is the recommended workflow.
-
 ### Raising an error condition
 
+- Deprecated as of 1.3.0; please use exceptions and a error handling middleware
+  such as the [ErrorHandler](error-handlers.md#handling-php-errors-and-exceptions) 
+  to handle error conditions in your application instead.
+
 To raise an error condition, pass a non-null value as the third argument to `$next()`:
 
 ```php
@@ -171,6 +184,9 @@ function ($request, $response, $next)
 
 ## FinalHandler
 
+- Deprecated starting with 1.3.0. Use `Zend\Stratigility\NoopFinalHandler` or a
+  custom handler guaranteed to return a response instead.
+
 `Zend\Stratigility\FinalHandler` is a default implementation of middleware to execute when the stack
 exhausts itself. It expects three arguments when invoked: a request instance, a response instance,
 and an error condition (or `null` for no error). It returns a response.

doc/book/creating-middleware.md

@@ -1,14 +1,15 @@
 # Creating Middleware
 
-To create middleware, write a callable capable of receiving minimally PSR-7 ServerRequest and Response
-objects, and optionally a callback to call the next in the chain.  In your middleware, you can handle
-as much or as little of the request as you want, including delegating to other middleware. If your
-middleware accepts a third argument, `$next`, it can allow further processing or return handling to
-the parent middleware by calling it.
+To create middleware, write a callable capable of receiving minimally PSR-7
+ServerRequest and Response objects, and a callback to call the next middleware
+in the chain. In your middleware, you can handle as much or as little of the
+request as you want, including delegating to other middleware. By accepting the
+third argument, `$next`, it can allow further processing via invoking that
+argument, or return handling to the parent middleware by returning a response.
 
-As an example, consider the following middleware which will use an external router to map the
-incoming request path to a handler; if unable to map the request, it returns processing to the next
-middleware.
+As an example, consider the following middleware which will use an external
+router to map the incoming request path to a handler; if unable to map the
+request, it returns processing to the next middleware.
 
 ```php
 function ($req, $res, $next) use ($router) {
@@ -41,14 +42,21 @@ In all cases, if you wish to implement typehinting, the signature is:
 function (
     Psr\Http\Message\ServerRequestInterface $request,
     Psr\Http\Message\ResponseInterface $response,
-    callable $next = null
+    callable $next
 ) : Psr\Http\Message\ResponseInterface
 ```
 
-The implementation Stratigility offers also allows you to write specialized error handler
-middleware. The signature is the same as for normal middleware, except that it expects an additional
-argument prepended to the signature, `$error`.  (Alternately, you can implement
-`Zend\Stratigility\ErrorMiddlewareInterface`.) The signature is:
+### Legacy error middleware
+
+- Deprecated since 1.3.0; to be removed in version 2.0.0. Please use the the
+  `NotFoundHandler` and `ErrorHandler` detailed in the
+  [error handling chapter](error-handlers.md), or equivalents.
+
+The implementation Stratigility offers also allows you to write specialized
+error handler middleware. The signature is the same as for normal middleware,
+except that it expects an additional argument prepended to the signature,
+`$error`.  (Alternately, you can implement `Zend\Stratigility\ErrorMiddlewareInterface`.)
+The signature is:
 
 ```php
 function (