Deprecate emitters and the Server class

Per zendframework#295, these classes have equivalents or 1:1 mappings via the package zendframework/zend-httphandlerrunner. As such, they are deprecated for the 1.8.0 release, to be removed in version 2.0.
weierophinney · May 29, 2018 · 0c0aa89 · 0c0aa89
1 parent 047987b
commit 0c0aa89
Show file tree

Hide file tree

Showing 9 changed files with 48 additions and 11 deletions.
diff --git a/doc/book/api.md b/doc/book/api.md
@@ -177,6 +177,13 @@ In most cases, you will only use the methods defined in the `UploadedFileInterfa
 
 ## Server
 
+> ### Deprecated
+>
+> The class `Zend\Diactoros\Server` is deprecated as of the 1.8.0 release. We
+> recommend using the class `Zend\HttpHandlerRunner\RequestHandlerRunner` via
+> the package [zendframework/zend-httphandlerrunner](https://docs.zendframework.com/zend-httphandlerrunner)
+> instead.
+
 `Zend\Diactoros\Server` represents a server capable of executing a callback. It has four methods:
 
 ```php

diff --git a/doc/book/emitting-responses.md b/doc/book/emitting-responses.md
@@ -1,5 +1,12 @@
 # Emitting responses
 
+> ## Deprecated
+>
+> Emitters are deprecated from Diactoros starting with version 1.8.0. The
+> functionality is now available for any PSR-7 implementation via the package
+> [zendframework/zend-httphandlerrunner](https://docs.zendframework.com/zend-httphandlerrunner).
+> We suggest using that functionality instead.
+
 If you are using a non-SAPI PHP implementation and wish to use the `Server` class, or if you do not
 want to use the `Server` implementation but want to emit a response, this package provides an
 interface, `Zend\Diactoros\Response\EmitterInterface`, defining a method `emit()` for emitting the

diff --git a/doc/book/overview.md b/doc/book/overview.md
@@ -6,7 +6,6 @@ well as a "server" implementation similar to [node's http.Server](http://nodejs.
 
 This package exists:
 
-- to provide a proof-of-concept of the accepted PSR HTTP message interfaces with relation to
-  server-side applications.
-- to provide a node-like paradigm for PHP front controllers.
+- to provide an implementation of [PSR-7 HTTP message interfaces](https://www.php-fig.org/psr/psr-7)
+- with relation to server-side applications.
 - to provide a common methodology for marshaling a request from the server environment.
diff --git a/doc/book/usage.md b/doc/book/usage.md
@@ -118,6 +118,13 @@ $response = $response
 
 ### "Serving" an application
 
+> ### Deprecated
+>
+> The class `Zend\Diactoros\Server` is deprecated as of the 1.8.0 release. We
+> recommend using the class `Zend\HttpHandlerRunner\RequestHandlerRunner` via
+> the package [zendframework/zend-httphandlerrunner](https://docs.zendframework.com/zend-httphandlerrunner)
+> instead.
+
 `Zend\Diactoros\Server` mimics a portion of the API of node's `http.Server` class. It invokes a
 callback, passing it an `ServerRequest`, an `Response`, and optionally a callback to use for
 incomplete/unhandled requests.

diff --git a/src/Response/EmitterInterface.php b/src/Response/EmitterInterface.php
@@ -1,16 +1,18 @@
 <?php
 /**
- * Zend Framework (http://framework.zend.com/)
- *
- * @see       http://github.com/zendframework/zend-diactoros for the canonical source repository
- * @copyright Copyright (c) 2015-2016 Zend Technologies USA Inc. (http://www.zend.com)
+ * @see       https://github.com/zendframework/zend-diactoros for the canonical source repository
+ * @copyright Copyright (c) 2015-2018 Zend Technologies USA Inc. (https://www.zend.com)
  * @license   https://github.com/zendframework/zend-diactoros/blob/master/LICENSE.md New BSD License
  */
 
 namespace Zend\Diactoros\Response;
 
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * @deprecated since 1.8.0. The package zendframework/zend-httphandlerrunner
+ *     now provides this functionality.
+ */
 interface EmitterInterface
 {
     /**

diff --git a/src/Response/SapiEmitter.php b/src/Response/SapiEmitter.php
@@ -1,14 +1,18 @@
 <?php
 /**
  * @see       https://github.com/zendframework/zend-diactoros for the canonical source repository
- * @copyright Copyright (c) 2015-2017 Zend Technologies USA Inc. (http://www.zend.com)
+ * @copyright Copyright (c) 2015-2018 Zend Technologies USA Inc. (http://www.zend.com)
  * @license   https://github.com/zendframework/zend-diactoros/blob/master/LICENSE.md New BSD License
  */
 
 namespace Zend\Diactoros\Response;
 
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * @deprecated since 1.8.0. The package zendframework/zend-httphandlerrunner
+ *     now provides this functionality.
+ */
 class SapiEmitter implements EmitterInterface
 {
     use SapiEmitterTrait;

diff --git a/src/Response/SapiEmitterTrait.php b/src/Response/SapiEmitterTrait.php
@@ -1,7 +1,7 @@
 <?php
 /**
  * @see       https://github.com/zendframework/zend-diactoros for the canonical source repository
- * @copyright Copyright (c) 2015-2017 Zend Technologies USA Inc. (http://www.zend.com)
+ * @copyright Copyright (c) 2015-2018 Zend Technologies USA Inc. (http://www.zend.com)
  * @license   https://github.com/zendframework/zend-diactoros/blob/master/LICENSE.md New BSD License
  */
 
@@ -16,6 +16,10 @@
 use function str_replace;
 use function ucwords;
 
+/**
+ * @deprecated since 1.8.0. The package zendframework/zend-httphandlerrunner
+ *     now provides this functionality.
+ */
 trait SapiEmitterTrait
 {
     /**

diff --git a/src/Response/SapiStreamEmitter.php b/src/Response/SapiStreamEmitter.php
@@ -1,7 +1,7 @@
 <?php
 /**
  * @see       https://github.com/zendframework/zend-diactoros for the canonical source repository
- * @copyright Copyright (c) 2015-2017 Zend Technologies USA Inc. (http://www.zend.com)
+ * @copyright Copyright (c) 2015-2018 Zend Technologies USA Inc. (http://www.zend.com)
  * @license   https://github.com/zendframework/zend-diactoros/blob/master/LICENSE.md New BSD License
  */
 
@@ -14,6 +14,10 @@
 use function strlen;
 use function substr;
 
+/**
+ * @deprecated since 1.8.0. The package zendframework/zend-httphandlerrunner
+ *     now provides this functionality.
+ */
 class SapiStreamEmitter implements EmitterInterface
 {
     use SapiEmitterTrait;

diff --git a/src/Server.php b/src/Server.php
@@ -1,7 +1,7 @@
 <?php
 /**
  * @see       https://github.com/zendframework/zend-diactoros for the canonical source repository
- * @copyright Copyright (c) 2015-2017 Zend Technologies USA Inc. (http://www.zend.com)
+ * @copyright Copyright (c) 2015-2018 Zend Technologies USA Inc. (http://www.zend.com)
  * @license   https://github.com/zendframework/zend-diactoros/blob/master/LICENSE.md New BSD License
  */
 
@@ -18,6 +18,9 @@
  *
  * Given a callback, takes an incoming request, dispatches it to the
  * callback, and then sends a response.
+ *
+ * @deprecated since 1.8.0. We recommend using the `RequestHandlerRunner` class
+ *     from the zendframework/zend-httphandlerrunner package instead.
  */
 class Server
 {