Merging develop to master in preparation for 1.8.0 release.

CHANGELOG.md

@@ -2,19 +2,74 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
-## 1.7.3 - TBD
+## 1.8.0 - 2018-06-27
 
 ### Added
 
-- Nothing.
+- [#307](https://github.com/zendframework/zend-diactoros/pull/307) adds the following functions under the `Zend\Diactoros` namespace, each of
+  which may be used to derive artifacts from SAPI supergloabls for the purposes
+  of generating a `ServerRequest` instance:
+  - `normalizeServer(array $server, callable $apacheRequestHeaderCallback = null) : array`
+    (main purpose is to aggregate the `Authorization` header in the SAPI params
+    when under Apache)
+  - `marshalProtocolVersionFromSapi(array $server) : string`
+  - `marshalMethodFromSapi(array $server) : string`
+  - `marshalUriFromSapi(array $server, array $headers) : Uri`
+  - `marshalHeadersFromSapi(array $server) : array`
+  - `parseCookieHeader(string $header) : array`
+  - `createUploadedFile(array $spec) : UploadedFile` (creates the instance from
+    a normal `$_FILES` entry)
+  - `normalizeUploadedFiles(array $files) : UploadedFileInterface[]` (traverses
+    a potentially nested array of uploaded file instances and/or `$_FILES`
+    entries, including those aggregated under mod_php, php-fpm, and php-cgi in
+    order to create a flat array of `UploadedFileInterface` instances to use in a
+    request)
 
 ### Changed
 
 - Nothing.
 
 ### Deprecated
 
-- Nothing.
+- [#307](https://github.com/zendframework/zend-diactoros/pull/307) deprecates `ServerRequestFactory::normalizeServer()`; the method is
+  no longer used internally, and users should instead use `Zend\Diactoros\normalizeServer()`,
+  to which it proxies.
+
+- [#307](https://github.com/zendframework/zend-diactoros/pull/307) deprecates `ServerRequestFactory::marshalHeaders()`; the method is
+  no longer used internally, and users should instead use `Zend\Diactoros\marshalHeadersFromSapi()`,
+  to which it proxies.
+
+- [#307](https://github.com/zendframework/zend-diactoros/pull/307) deprecates `ServerRequestFactory::marshalUriFromServer()`; the method
+  is no longer used internally. Users should use `marshalUriFromSapi()` instead.
+
+- [#307](https://github.com/zendframework/zend-diactoros/pull/307) deprecates `ServerRequestFactory::marshalRequestUri()`. the method is no longer
+  used internally, and currently proxies to `marshalUriFromSapi()`, pulling the
+  discovered path from the `Uri` instance returned by that function. Users
+  should use `marshalUriFromSapi()` instead.
+
+- [#307](https://github.com/zendframework/zend-diactoros/pull/307) deprecates `ServerRequestFactory::marshalHostAndPortFromHeaders()`; the method
+  is no longer used internally, and currently proxies to `marshalUriFromSapi()`,
+  pulling the discovered host and port from the `Uri` instance returned by that
+  function. Users should use `marshalUriFromSapi()` instead.
+
+- [#307](https://github.com/zendframework/zend-diactoros/pull/307) deprecates `ServerRequestFactory::getHeader()`; the method is no longer
+  used internally. Users should copy and paste the functionality into their own
+  applications if needed, or rely on headers from a fully-populated `Uri`
+  instance instead.
+
+- [#307](https://github.com/zendframework/zend-diactoros/pull/307) deprecates `ServerRequestFactory::stripQueryString()`; the method is no longer
+  used internally, and users can mimic the functionality via the expression
+  `$path = explode('?', $path, 2)[0];`.
+
+- [#307](https://github.com/zendframework/zend-diactoros/pull/307) deprecates `ServerRequestFactory::normalizeFiles()`; the functionality
+  is no longer used internally, and users can use `normalizeUploadedFiles()` as
+  a replacement.
+
+- [#303](https://github.com/zendframework/zend-diactoros/pull/303) deprecates `Zend\Diactoros\Response\EmitterInterface` and its various implementations. These are now provided via the
+  [zendframework/zend-httphandlerrunner](https://docs.zendframework.com/zend-httphandlerrunner) package as 1:1 substitutions.
+
+- [#303](https://github.com/zendframework/zend-diactoros/pull/303) deprecates the `Zend\Diactoros\Server` class. Users are directed to the `RequestHandlerRunner` class from the
+  [zendframework/zend-httphandlerrunner](https://docs.zendframework.com/zend-httphandlerrunner) package as an alternative.
 
 ### Removed
 

composer.json

@@ -18,8 +18,8 @@
   },
   "extra": {
     "branch-alias": {
-      "dev-master": "1.7.x-dev",
-      "dev-develop": "1.8.x-dev",
+      "dev-master": "1.8.x-dev",
+      "dev-develop": "1.9.x-dev",
       "dev-release-2.0": "2.0.x-dev"
     }
   },
@@ -37,6 +37,16 @@
     "psr/http-message-implementation": "1.0"
   },
   "autoload": {
+    "files": [
+        "src/functions/create_uploaded_file.php",
+        "src/functions/marshal_headers_from_sapi.php",
+        "src/functions/marshal_method_from_sapi.php",
+        "src/functions/marshal_protocol_version_from_sapi.php",
+        "src/functions/marshal_uri_from_sapi.php",
+        "src/functions/normalize_server.php",
+        "src/functions/normalize_uploaded_files.php",
+        "src/functions/parse_cookie_header.php"
+    ],
     "psr-4": {
       "Zend\\Diactoros\\": "src/"
     }

doc/book/api.md

@@ -128,6 +128,31 @@ $request = RequestFactory::fromGlobals(
 );
 ```
 
+### ServerRequestFactory helper functions
+
+- Since 1.8.0
+
+In order to create the various artifacts required by a `ServerRequest` instance,
+Diactoros also provides a number of functions under the `Zend\Diactoros`
+namespace for introspecting the SAPI `$_SERVER` parameters, headers, `$_FILES`,
+and even the `Cookie` header. These include:
+
+- `Zend\Diactoros\normalizeServer(array $server, callable $apacheRequestHeaderCallback = null) : array`
+  (its main purpose is to aggregate the `Authorization` header in the SAPI params
+  when under Apache)
+- `Zend\Diactoros\marshalProtocolVersionFromSapi(array $server) : string`
+- `Zend\Diactoros\marshalMethodFromSapi(array $server) : string`
+- `Zend\Diactoros\marshalUriFromSapi(array $server, array $headers) : Uri`
+- `Zend\Diactoros\marshalHeadersFromSapi(array $server) : array`
+- `Zend\Diactoros\parseCookieHeader(string $header) : array`
+- `Zend\Diactoros\createUploadedFile(array $spec) : UploadedFile` (creates the
+  instance from a normal `$_FILES` entry)
+- `Zend\Diactoros\normalizeUploadedFiles(array $files) : UploadedFileInterface[]`
+  (traverses a potentially nested array of uploaded file instances and/or
+  `$_FILES` entries, including those aggregated under mod_php, php-fpm, and
+  php-cgi in order to create a flat array of `UploadedFileInterface` instances
+  to use in a request)
+
 ## URI
 
 `Zend\Diactoros\Uri` is an implementation of
@@ -177,6 +202,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

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

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.

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.

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
 {
     /**

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;

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
 {
     /**

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;

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
 {