Merging develop to master in preparation for 1.4.0 release.

Author: weierophinney

CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
+## 1.4.0 - TBD
+
+### Added
+
+- [#219](https://github.com/zendframework/zend-diactoros/pull/219) adds two new
+  classes, `Zend\Diactoros\Request\ArraySerializer` and
+  `Zend\Diactoros\Response\ArraySerializer`. Each exposes the static methods
+  `toArray()` and `fromArray()`, allowing de/serialization of messages from and
+  to arrays.
+
+- [#236](https://github.com/zendframework/zend-diactoros/pull/236) adds two new
+  constants to the `Response` class: `MIN_STATUS_CODE_VALUE` and
+  `MAX_STATUS_CODE_VALUE`.
+
+### Changes
+
+- [#240](https://github.com/zendframework/zend-diactoros/pull/240) changes the
+  behavior of `ServerRequestFactory::fromGlobals()` when no `$cookies` argument
+  is present. Previously, it would use `$_COOKIES`; now, if a `Cookie` header is
+  present, it will parse and use that to populate the instance instead.
+
+  This change allows utilizing cookies that contain period characters (`.`) in
+  their names (PHP's built-in cookie handling renames these to replace `.` with
+  `_`, which can lead to synchronization issues with clients).
+
+- [#235](https://github.com/zendframework/zend-diactoros/pull/235) changes the
+  behavior of `Uri::__toString()` to better follow proscribed behavior in PSR-7.
+  In particular, prior to this release, if a scheme was missing but an authority
+  was present, the class was incorrectly returning a value that did not include
+  a `//` prefix. As of this release, it now does this correctly.
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.
+
 ## 1.3.11 - 2017-04-06
 
 ### Added

doc/book/serialization.md

@@ -1,5 +1,7 @@
 # Serialization
 
+## String
+
 At times, it's useful to either create a string representation of a message (serialization), or to
 cast a string or stream message to an object (deserialization). This package provides features for
 this in `Zend\Diactoros\Request\Serializer` and `Zend\Diactoros\Response\Serializer`; each provides
@@ -15,3 +17,43 @@ the following static methods:
 The deserialization methods (`from*()`) will raise exceptions if errors occur while parsing the
 message. The serialization methods (`toString()`) will raise exceptions if required data for
 serialization is not present in the message instance.
+
+## Array
+
+This package also provides features for array serialization using
+`Zend\Diactoros\Request\ArraySerializer` and `Zend\Diactoros\Response\ArraySerializer`; each provides
+the following static methods:
+
+- `fromArray(array $message)` will create either a `Request` or `Response` instance (based on the
+  serializer used) from the array message.
+- `toArray(Psr\Http\Message\RequestInterface|Psr\Http\Message\ResponseInterface $message)` will
+  create an array from the provided message.
+
+The deserialization methods (`fromArray()`) will raise exceptions if errors occur while parsing the
+message.
+
+### Example usage
+
+Array serialization can be usesful for log messages:
+
+```php
+class LoggerMiddleware
+{
+    /**
+     * @var \Psr\Log\LoggerInterface
+     */
+    protected $logger;
+
+    public function __invoke(ServerRequestInterface $request, ResponseInterface $response, callable $next)
+    {
+        $response = $next($request, $response);
+
+        $this->logger->debug('Request/Response', [
+            'request' => \Zend\Diactoros\Request\ArraySerializer::toArray($request),
+            'response' => \Zend\Diactoros\Response\ArraySerializer::toArray($response),
+        ]);
+
+        return $response;
+    }
+}
+```

doc/book/usage.md

@@ -87,6 +87,13 @@ $request = Zend\Diactoros\ServerRequestFactory::fromGlobals(
 );
 ```
 
+When no cookie array is supplied, `fromGlobals` will first try to parse the supplied `cookie` header
+before falling back to the `$_COOKIE` superglobal. This is done because PHP has some legacy handling
+for request parameters which were then registered as global variables. Due to this, cookies with a period
+in the name were renamed with underlines. By getting the cookies directly from the cookie header, you have
+access to the original cookies in the way you set them in your application and they are send by the user
+agent.
+
 ### Manipulating the response
 
 Use the response object to add headers and provide content for the response.  Writing to the body

src/Request/ArraySerializer.php

@@ -0,0 +1,85 @@
+<?php
+/**
+ * @see       http://github.com/zendframework/zend-diactoros for the canonical source repository
+ * @copyright Copyright (c) 2017 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\Request;
+
+use Psr\Http\Message\RequestInterface;
+use UnexpectedValueException;
+use Zend\Diactoros\Request;
+use Zend\Diactoros\Stream;
+
+/**
+ * Serialize or deserialize request messages to/from arrays.
+ *
+ * This class provides functionality for serializing a RequestInterface instance
+ * to an array, as well as the reverse operation of creating a Request instance
+ * from an array representing a message.
+ */
+final class ArraySerializer
+{
+    /**
+     * Serialize a request message to an array.
+     *
+     * @param RequestInterface $request
+     * @return array
+     */
+    public static function toArray(RequestInterface $request)
+    {
+        return [
+            'method'           => $request->getMethod(),
+            'request_target'   => $request->getRequestTarget(),
+            'uri'              => (string) $request->getUri(),
+            'protocol_version' => $request->getProtocolVersion(),
+            'headers'          => $request->getHeaders(),
+            'body'             => (string) $request->getBody(),
+        ];
+    }
+
+    /**
+     * Deserialize a request array to a request instance.
+     *
+     * @param array $serializedRequest
+     * @return Request
+     * @throws UnexpectedValueException when cannot deserialize response
+     */
+    public static function fromArray(array $serializedRequest)
+    {
+        try {
+            $uri             = self::getValueFromKey($serializedRequest, 'uri');
+            $method          = self::getValueFromKey($serializedRequest, 'method');
+            $body            = new Stream('php://memory', 'wb+');
+            $body->write(self::getValueFromKey($serializedRequest, 'body'));
+            $headers         = self::getValueFromKey($serializedRequest, 'headers');
+            $requestTarget   = self::getValueFromKey($serializedRequest, 'request_target');
+            $protocolVersion = self::getValueFromKey($serializedRequest, 'protocol_version');
+
+            return (new Request($uri, $method, $body, $headers))
+                ->withRequestTarget($requestTarget)
+                ->withProtocolVersion($protocolVersion);
+        } catch (\Exception $exception) {
+            throw new UnexpectedValueException('Cannot deserialize request', null, $exception);
+        }
+    }
+
+    /**
+     * @param array $data
+     * @param string $key
+     * @param string $message
+     * @return mixed
+     * @throws UnexpectedValueException
+     */
+    private static function getValueFromKey(array $data, $key, $message = null)
+    {
+        if (isset($data[$key])) {
+            return $data[$key];
+        }
+        if ($message === null) {
+            $message = sprintf('Missing "%s" key in serialized request', $key);
+        }
+        throw new UnexpectedValueException($message);
+    }
+}

src/Response.php

@@ -24,6 +24,9 @@ class Response implements ResponseInterface
 {
     use MessageTrait;
 
+    const MIN_STATUS_CODE_VALUE = 100;
+    const MAX_STATUS_CODE_VALUE = 599;
+
     /**
      * Map of standard HTTP status code/reason phrases
      *
@@ -159,21 +162,23 @@ public function withStatus($code, $reasonPhrase = '')
     }
 
     /**
-     * Validate a status code.
+     * Set a valid status code.
      *
-     * @param int|string $code
+     * @param int $code
      * @throws InvalidArgumentException on an invalid status code.
      */
     private function setStatusCode($code)
     {
         if (! is_numeric($code)
             || is_float($code)
-            || $code < 100
-            || $code >= 600
+            || $code < static::MIN_STATUS_CODE_VALUE
+            || $code > static::MAX_STATUS_CODE_VALUE
         ) {
             throw new InvalidArgumentException(sprintf(
-                'Invalid status code "%s"; must be an integer between 100 and 599, inclusive',
-                (is_scalar($code) ? $code : gettype($code))
+                'Invalid status code "%s"; must be an integer between %d and %d, inclusive',
+                (is_scalar($code) ? $code : gettype($code)),
+                static::MIN_STATUS_CODE_VALUE,
+                static::MAX_STATUS_CODE_VALUE
             ));
         }
         $this->statusCode = $code;

src/Response/ArraySerializer.php

@@ -0,0 +1,84 @@
+<?php
+/**
+ * @see       http://github.com/zendframework/zend-diactoros for the canonical source repository
+ * @copyright Copyright (c) 2017 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;
+use UnexpectedValueException;
+use Zend\Diactoros\Response;
+use Zend\Diactoros\Stream;
+
+/**
+ * Serialize or deserialize response messages to/from arrays.
+ *
+ * This class provides functionality for serializing a ResponseInterface instance
+ * to an array, as well as the reverse operation of creating a Response instance
+ * from an array representing a message.
+ */
+final class ArraySerializer
+{
+    /**
+     * Serialize a response message to an array.
+     *
+     * @param ResponseInterface $response
+     * @return array
+     */
+    public static function toArray(ResponseInterface $response)
+    {
+        return [
+            'status_code'      => $response->getStatusCode(),
+            'reason_phrase'    => $response->getReasonPhrase(),
+            'protocol_version' => $response->getProtocolVersion(),
+            'headers'          => $response->getHeaders(),
+            'body'             => (string) $response->getBody(),
+        ];
+    }
+
+    /**
+     * Deserialize a response array to a response instance.
+     *
+     * @param array $serializedResponse
+     * @return Response
+     * @throws UnexpectedValueException when cannot deserialize response
+     */
+    public static function fromArray(array $serializedResponse)
+    {
+        try {
+            $body = new Stream('php://memory', 'wb+');
+            $body->write(self::getValueFromKey($serializedResponse, 'body'));
+
+            $statusCode      = self::getValueFromKey($serializedResponse, 'status_code');
+            $headers         = self::getValueFromKey($serializedResponse, 'headers');
+            $protocolVersion = self::getValueFromKey($serializedResponse, 'protocol_version');
+            $reasonPhrase    = self::getValueFromKey($serializedResponse, 'reason_phrase');
+
+            return (new Response($body, $statusCode, $headers))
+                ->withProtocolVersion($protocolVersion)
+                ->withStatus($statusCode, $reasonPhrase);
+        } catch (\Exception $exception) {
+            throw new UnexpectedValueException('Cannot deserialize response', null, $exception);
+        }
+    }
+
+    /**
+     * @param array $data
+     * @param string $key
+     * @param string $message
+     * @return mixed
+     * @throws UnexpectedValueException
+     */
+    private static function getValueFromKey(array $data, $key, $message = null)
+    {
+        if (isset($data[$key])) {
+            return $data[$key];
+        }
+        if ($message === null) {
+            $message = sprintf('Missing "%s" key in serialized request', $key);
+        }
+        throw new UnexpectedValueException($message);
+    }
+}

src/Response/Serializer.php

@@ -37,7 +37,7 @@ public static function fromString($message)
      * Parse a response from a stream.
      *
      * @param StreamInterface $stream
-     * @return ResponseInterface
+     * @return Response
      * @throws InvalidArgumentException when the stream is not readable.
      * @throws UnexpectedValueException when errors occur parsing the message.
      */

src/ServerRequestFactory.php

@@ -60,6 +60,10 @@ public static function fromGlobals(
         $files   = static::normalizeFiles($files ?: $_FILES);
         $headers = static::marshalHeaders($server);
 
+        if (null === $cookies && array_key_exists('cookie', $headers)) {
+            $cookies = self::parseCookieHeader($headers['cookie']);
+        }
+
         return new ServerRequest(
             $server,
             $files,
@@ -485,4 +489,34 @@ private static function marshalProtocolVersion(array $server)
 
         return $matches['version'];
     }
+
+    /**
+     * Parse a cookie header according to RFC 6265.
+     *
+     * PHP will replace special characters in cookie names, which results in other cookies not being available due to
+     * overwriting. Thus, the server request should take the cookies from the request header instead.
+     *
+     * @param $cookieHeader
+     * @return array
+     */
+    private static function parseCookieHeader($cookieHeader)
+    {
+        preg_match_all('(
+            (?:^\\n?[ \t]*|;[ ])
+            (?P<name>[!#$%&\'*+-.0-9A-Z^_`a-z|~]+)
+            =
+            (?P<DQUOTE>"?)
+                (?P<value>[\x21\x23-\x2b\x2d-\x3a\x3c-\x5b\x5d-\x7e]*)
+            (?P=DQUOTE)
+            (?=\\n?[ \t]*$|;[ ])
+        )x', $cookieHeader, $matches, PREG_SET_ORDER);
+
+        $cookies = [];
+
+        foreach ($matches as $match) {
+            $cookies[$match['name']] = urldecode($match['value']);
+        }
+
+        return $cookies;
+    }
 }

src/Stream.php

@@ -19,7 +19,7 @@
 class Stream implements StreamInterface
 {
     /**
-     * @var resource
+     * @var resource|null
      */
     protected $resource;