Merge branch 'feature/deprecations'

Close #429

Author: weierophinney

CHANGELOG.md

@@ -2,6 +2,58 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
+## 1.1.0 - TBD
+
+### Added
+
+- [#429](https://github.com/zendframework/zend-expressive/pull/429) adds
+  `Zend\Expressive\Application::getDefaultDelegate()` as a
+  forwards-compatibility measure for the upcoming version 2.0.0. Currently,
+  it proxies to `getFinalHandler()`.
+
+### Changed
+
+- [#429](https://github.com/zendframework/zend-expressive/pull/429) updates the
+  minimum supported zend-stratigility version to 1.3.3.
+
+### Deprecated
+
+- [#429](https://github.com/zendframework/zend-expressive/pull/429) deprecates
+  the following methods and classes:
+  - `Zend\Expressive\Application::pipeErrorHandler()`; use the
+    `raise_throwables` flag and standard middleware to handle errors instead.
+  - `Zend\Expressive\Application::routeMiddleware()`; this is extracted to a
+    dedicated middleware class for 2.0.
+  - `Zend\Expressive\Application::dispatchMiddleware()`; this is extracted to a
+    dedicated middleware class for 2.0.
+  - `Zend\Expressive\Application::getFinalHandler()` (this patch provides `getDefaultDelegate()` as a forwards-compatibility measure)
+  - `Zend\Expressive\Container\Exception\InvalidArgumentException`; this will be removed
+    in 2.0.0, and places where it was used will instead throw
+    `Zend\Expressive\Exception\InvalidArgumentException`.
+  - `Zend\Expressive\Container\Exception\NotFoundException`; this exception is
+    never thrown at this point.
+  - `Zend\Expressive\Container\TemplatedErrorHandlerFactory`
+  - `Zend\Expressive\Container\WhoopsErrorHandlerFactory`
+  - `Zend\Expressive\ErrorMiddlewarePipe`; Stratigility 1.3 deprecates its
+    `Zend\Stratigility\ErrorMiddlewareInterface`, and removes it in version 2.0.
+    use the `raise_throwables` flag and standard middleware to handle errors
+    instead.
+  - `Zend\Expressive\TemplatedErrorHandler`; the "final handler" concept is
+    retired in Expressive 2.0, and replaced with default delegates (classes
+    implementing `Interop\Http\ServerMiddleware\DelegateInterface` that will be
+    executed when the internal pipeline is exhausted, in order to guarantee a
+    response). If you are using custom final handlers, you will need to rewrite
+    them when adopting Expressive 2.0.
+  - `Zend\Expressive\WhoopsErrorHandler`
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.
+
 ## 1.0.6 - 2017-01-09
 
 ### Added

composer.json

@@ -22,7 +22,7 @@
         "zendframework/zend-diactoros": "^1.1",
         "zendframework/zend-expressive-router": "^1.1",
         "zendframework/zend-expressive-template": "^1.0.1",
-        "zendframework/zend-stratigility": ">=1.1.0 < 1.3.0 || >=1.3.1 <2.0.0"
+        "zendframework/zend-stratigility": "^1.3.3"
     },
     "require-dev": {
         "filp/whoops": "^1.1 || ^2.0",

composer.lock

@@ -335,6 +335,13 @@ public function pipe($path, $middleware = null)
      * Once middleware detection and wrapping (if necessary) is complete,
      * proxies to pipe().
      *
+     * @deprecated since 1.1.0; to remove in 2.0.0. Stratigility v1-style
+     *     "error middleware" (middleware with four arguments, the first of which
+     *     being an error) was deprecated in Stratigility 1.3, and support
+     *     removed in Stratigility 2.0. You can start using standard middleware
+     *     for error handling by calling `raiseThrowables()` on the `Application`
+     *     instance, and piping such middleware in an outer layer of your application.
+     *     For an example, {@see Zend\Stratigility\Middleware\ErrorHandler}.
      * @param string|callable $path Either a URI path prefix, or middleware.
      * @param null|string|callable $middleware Middleware
      * @return self
@@ -410,6 +417,11 @@ public function pipeRouteResultObserverMiddleware()
      * Allow header, and `$next()` is called with its `$error` argument set
      * to the value `405` (invoking the next error middleware).
      *
+     * @deprecated since 1.1.0; to remove in 2.0.0. This method is extracted to
+     *     its own dedicated middleware class starting in 2.0.0. If you are
+     *     manually piping this method into your application or middleware
+     *     pipelines, or overriding the method, you will need to update your
+     *     code when migrating to 2.0.
      * @param  ServerRequestInterface $request
      * @param  ResponseInterface $response
      * @param  callable $next
@@ -453,6 +465,11 @@ public function routeMiddleware(ServerRequestInterface $request, ResponseInterfa
      * Finally, it attempts to marshal the middleware, and dispatches it when
      * complete, return the response.
      *
+     * @deprecated since 1.1.0; to remove in 2.0.0. This method is extracted to
+     *     its own dedicated middleware class starting in 2.0.0. If you are
+     *     manually piping this method into your application or middleware
+     *     pipelines, or overriding the method, you will need to update your
+     *     code when migrating to 2.0.
      * @param ServerRequestInterface $request
      * @param ResponseInterface $response
      * @param callable $next
@@ -598,6 +615,9 @@ public function getContainer()
     /**
      * Return the final handler to use during `run()` if the stack is exhausted.
      *
+     * @deprecated since 1.1.0; renamed to `getDefaultDelegate()` in version
+     *     2.0.0. If you are consuming this method, please update your code to call
+     *     getDefaultDelegate() instead.
      * @param null|ResponseInterface $response Response instance with which to seed the
      *     FinalHandler; used to determine if the response passed to the handler
      *     represents the original or final response state.
@@ -618,6 +638,20 @@ public function getFinalHandler(ResponseInterface $response = null)
         return $this->finalHandler;
     }
 
+    /**
+     * Return the default delegate to use during `run()` when the stack is exhausted.
+     *
+     * Provided as a forwards compatibility measure with version 2, and proxies
+     * to getFinalHandler(); please note that it does not accept any arguments,
+     * nor pass them on to that method.
+     *
+     * @return callable|null
+     */
+    public function getDefaultDelegate()
+    {
+        return $this->getFinalHandler();
+    }
+
     /**
      * Retrieve an emitter to use during run().
      *

src/Application.php

@@ -9,6 +9,12 @@
 
 use Interop\Container\Exception\ContainerException;
 
+/**
+ * @deprecated since 1.1.0; to remove in 2.0.0. This exception is currently
+ *     thrown by `Zend\Expressive\Container\ApplicationFactory`; starting
+ *     in 2.0.0, that factory will instead throw
+ *     `Zend\Expressive\Exception\InvalidArgumentException`.
+ */
 class InvalidArgumentException extends \InvalidArgumentException implements
     ContainerException,
     ExceptionInterface

src/Container/Exception/InvalidArgumentException.php

@@ -12,6 +12,9 @@
 
 /**
  * Exception indicating a service was not found in the container.
+ *
+ * @deprecated since 1.1.0; to remove in 2.0.0. This exception is not thrown
+ *     by any classes within Expressive at this time.
  */
 class NotFoundException extends RuntimeException implements
     ExceptionInterface,

src/Container/Exception/NotFoundException.php

@@ -38,6 +38,13 @@
  * </code>
  *
  * If any of the keys are missing, default values will be used.
+ *
+ * @deprecated since 1.1.0, to be removed in 2.0.0. The "final handler" concept
+ *     will be replaced with a "default delegate", which will be an
+ *     implementation of Interop\Http\ServerMiddleware\DelegateInterface that
+ *     returns a canned response. Expressive will provide tools to migrate your
+ *     code to use default delegates for 2.0; you will only need to manually
+ *     change your code if you are extending this class.
  */
 class TemplatedErrorHandlerFactory
 {

src/Container/TemplatedErrorHandlerFactory.php

@@ -60,6 +60,13 @@
  * </code>
  *
  * All values are booleans; omission of any implies boolean false.
+ *
+ * @deprecated since 1.1.0, to be removed in 2.0.0. The "final handler" concept
+ *     will be replaced with a "default delegate", which will be an
+ *     implementation of Interop\Http\ServerMiddleware\DelegateInterface that
+ *     returns a canned response. Expressive will provide tools to migrate your
+ *     code to use default delegates for 2.0; you will only need to manually
+ *     change your code if you are extending this class.
  */
 class WhoopsErrorHandlerFactory
 {

src/Container/WhoopsErrorHandlerFactory.php

@@ -28,6 +28,14 @@
  * It is not implemented as an extension of MiddlewarePipe, as that class
  * implements the MiddlewareInterface, which prevents its use as error
  * middleware.
+ *
+ * @deprecated since 1.1.0; to remove in 2.0.0. Stratigility 1.3 deprecates the
+ *     concept of "error middleware" (middleware accepting exactly four arguments
+ *     the first of which being an error) in favor of using standard middleware
+ *     for error handling; you can use `Zend\Stratigility\ErrorHandler` either
+ *     directly or as an example of how to implement such middleware. If you are
+ *     using Stratigility 1.3, you can enable such error handling by calling
+ *     `raiseThrowables()` on your `Application` instance.
  */
 class ErrorMiddlewarePipe
 {

src/ErrorMiddlewarePipe.php

@@ -18,6 +18,13 @@
  * Provides the optional ability to render a template for each of 404 and
  * general error conditions. If no template renderer is provided, returns
  * empty responses with appropriate status codes.
+ *
+ * @deprecated since 1.1.0, to be removed in 2.0.0. The "final handler" concept
+ *     will be replaced with a "default delegate", which will be an
+ *     implementation of Interop\Http\ServerMiddleware\DelegateInterface that
+ *     returns a canned response. Expressive will provide tools to migrate your
+ *     code to use default delegates for 2.0; you will only need to manually
+ *     change your code if you are extending this class.
  */
 class TemplatedErrorHandler
 {