Merge c5b2634 into 26efe24

CHANGELOG.md

@@ -6,14 +6,65 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### 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
 
+- [#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.
 

composer.json

@@ -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