Extract (private) functionality of ServerRequestFactory to functions

[weierophinney]

This patch serves as an alternative to #306. It extracts a number of methods from ServerRequestFactory into dedicated functions, allowing them to be used to derive ServerRequest artifacts.

tl;dr: This patch removes all private methods of ServerRequestFactory, and adds the following functions under the Zend\Diactoros namespace:

• 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)

The full set of changes include:

• $_SERVER normalization:
  • ADDS Zend\Diactoros\normalizeServer(array $server, callable $apacheRequestHeaderCallback = null) : array) for preparing the SAPI params to include the Authorization header; this is mainly done to ensure it is extracted properly under Apache.
  • DEPRECATES ServerRequestFactory::normalizeServer(), and has it proxy to normalizeServer(); it is no longer used internally.
• Header marshaling:
  • ADDS Zend\Diactoros\marshalHeadersFromSapi(array $server) : array for marshaling HTTP request headers from the SAPI $_SERVER array.
  • DEPRECATES ServerRequestFactory::marshalHeaders(), and has it proxy to marshalHeadersFromSapi(); the method is no longer used internally.
• Protocol version detection:
  • ADDS Zend\Diactoros\marshalProtocolVersionFromSapi(array $server) : string
  • REMOVES ServerRequestFactory::marshalProtocolVersion()
• Method detection:
  • ADDS Zend\Diactoros\marshalMethodFromSapi(array $server) : string
• URI marshaling:
  • ADDS:
  • Zend\Diactoros\marshalUriFromSapi(array $server, array $headers) : Uri for marshaling a Uri instance from the SAPI parameters and/or HTTP request headers. The function inlines the logic from each of ServerRequestFactory::getHeader(), ServerRequestFactory::marshalHostAndPortFromHeaders(), ServerRequestFactory::marshalHostAndPortFromHeader(), ServerRequestFactory::marshalRequestUri(), ServerRequestFactory::marshalUrifromServer(), and ServerRequestFactory::stripQueryString().
  • DEPRECATES:
  • ServerRequestFactory::getHeader(), and has it proxy to getHeaderFromArray().
  • ServerRequestFactory::marshalHostAndPortFromHeaders(), and has it proxy to `marshalHostAndPort(). It is no longer used internally.
  • ServerRequestFactory::marshalRequestUri(), and has it proxy to marshalRequestPath(). The method is no longer used internally.
  • ServerRequestFactory::marshalUriFromServer(), and has it proxy to marshalUriFromSapi() The method is no longer used internally.
  • ServerRequestFactory::stripQueryString(). The method is no longer used internally.
  • REMOVES:
  • ServerRequestFactory::marshalHostAndPortFromHeader()
  • ServerRequestFactory::marshalIpv6HostAndPort()
• Cookie header parsing:
  • CREATES Zend\Diactoros\parseCookieHeader(string $cookieHeader) : array
  • REMOVES ServerRequestFactory::parseCookieHeader()
• Uploaded file creation:
  • CREATES:
  • Zend\Diactoros\createUploadedFile(array $spec) : UploadedFile
  • Zend\Diactoros\normalizeUploadedFiles(array $files) : UploadedFileInterface[]
  • REMOVES:
  • ServerRequestFactory::createUploadedFileFromSpec() (was private previously; logic now in createUploadedFile())
  • ServerRequestFactory::normalizeNestedFileSpec() (was private previously; logic now incorporated in normalizeUploadedFiles())
  • DEPRECATES:
  • ServerRequestFactory::normalizeFiles(); the method is no longer used internally, and now proxies to normalizeUploadedFiles().

[weierophinney]

Outstanding questions:

• I have some new function use the FromSapi() suffix, while others do not. Add it to those that do not, or remove it from those that do?
• I use the prefix normalize with two functions that aggregate UploadedFileInterface instances; would it be better to use the marshal prefix as I do elsewhere?

[Moln]

A function suggestion.

https://github.com/zendframework/zend-diactoros/blob/1.7.2/src/ServerRequestFactory.php#L393-L399

public static function stripQueryString($path)
{
        if (($qpos = strpos($path, '?')) !== false) {
            return substr($path, 0, $qpos);
        }
        return $path;
}

There can be simpler code.

public static function stripQueryString($path)
{
        return explode('?', $path, 2)[0];
}

[weierophinney]

Thanks, @Moln ; incorporated both in that method, as well as the inlined version in marshalUriFromSapi().

[weierophinney]

I've made the following changes at this time:

• Consolidated all URI generation functions into a single Zend\Diactoros\marshalUriFromSapi() function; this allowed removing each of getHeaderFromArray(), marshalHostandPort(), and marshalIpv6HostAndPort().
• Renamed the protocol version detection function to Zend\Diactoros\marshalProtocolVersionFromSapi().
• Added a method detection function, Zend\Diactoros\marshalMethodFromSapi(array $server) : string.
• Consolidated the upload file normalization functions into Zend\Diactoros\normalizeUploadedFiles(); createUploadedFile() was kept, as it has standalone use cases.

I've also updated ServerRequestFactory to follow all changes.

At this point, I think this is ready for final review.