Updated to php-fig/fig-standards@476606bb

Author: weierophinney

src/IncomingRequestInterface.php

@@ -6,9 +6,9 @@
  * An incoming (server-side) HTTP request.
  *
  * This interface further describes a server-side request and provides
- * accessors and mutators around common request data, such as query
+ * accessors and mutators around common request data, including query
  * string arguments, body parameters, upload file metadata, cookies, and
- * matched routing parameters.
+ * arbitrary attributes derived from the request by the application.
  */
 interface IncomingRequestInterface extends RequestInterface
 {
@@ -18,13 +18,10 @@ interface IncomingRequestInterface extends RequestInterface
      * Retrieves cookies sent by the client to the server.
      *
      * The assumption is these are injected during instantiation, typically
-     * from PHP's $_COOKIE superglobal, and should remain immutable over the
-     * course of the incoming request.
+     * from PHP's $_COOKIE superglobal. The data IS NOT REQUIRED to come from
+     * $_COOKIE, but MUST be compatible with the structure of $_COOKIE.
      *
-     * The return value can be either an array or an object that acts like
-     * an array (e.g., implements ArrayAccess, or an ArrayObject).
-     *
-     * @return array|\ArrayAccess
+     * @return array
      */
     public function getCookieParams();
 
@@ -35,28 +32,28 @@ public function getCookieParams();
      * libraries that implement additional security practices, such as
      * encrypting or hashing cookie values; in such cases, they will read
      * the original value, filter them, and re-inject into the incoming
-     * request..
-     *
-     * The value provided should be an array or array-like object
-     * (e.g., implements ArrayAccess, or an ArrayObject).
+     * request.
      *
-     * @param array|\ArrayAccess $cookies Cookie values/structs
+     * The value provided MUST be compatible with the structure of $_COOKIE.
      *
+     * @param array $cookies Cookie values
      * @return void
+     * @throws \InvalidArgumentException For invalid cookie parameters.
      */
-    public function setCookieParams($cookies);
+    public function setCookieParams(array $cookies);
 
     /**
      * Retrieve query string arguments.
      *
      * Retrieves the deserialized query string arguments, if any.
      *
-     * The assumption is these are injected during instantiation, typically
-     * from PHP's $_GET superglobal, and should remain immutable over the
-     * course of the incoming request.
-     *
-     * The return value can be either an array or an object that acts like
-     * an array (e.g., implements ArrayAccess, or an ArrayObject).
+     * These values SHOULD remain immutable over the course of the incoming
+     * request. They MAY be injected during instantiation, such as from PHP's
+     * $_GET superglobal, or MAY be derived from some other value such as the
+     * URI. In cases where the arguments are parsed from the URI, the data
+     * MUST be compatible with what PHP's `parse_str()` would return for
+     * purposes of how duplicate query parameters are handled, and how nested
+     * sets are handled.
      *
      * @return array
      */
@@ -65,15 +62,12 @@ public function getQueryParams();
     /**
      * Retrieve the upload file metadata.
      *
-     * This method should return file upload metadata in the same structure
+     * This method MUST return file upload metadata in the same structure
      * as PHP's $_FILES superglobal.
      *
-     * The assumption is these are injected during instantiation, typically
-     * from PHP's $_FILES superglobal, and should remain immutable over the
-     * course of the incoming request.
-     *
-     * The return value can be either an array or an object that acts like
-     * an array (e.g., implements ArrayAccess, or an ArrayObject).
+     * These values SHOULD remain immutable over the course of the incoming
+     * request. They MAY be injected during instantiation, such as from PHP's
+     * $_FILES superglobal, or MAY be derived from other sources.
      *
      * @return array Upload file(s) metadata, if any.
      */
@@ -82,56 +76,51 @@ public function getFileParams();
     /**
      * Retrieve any parameters provided in the request body.
      *
-     * If the request body can be deserialized, and if the deserialized values
-     * can be represented as an array or object, this method can be used to
-     * retrieve them.
+     * If the request body can be deserialized to an array, this method MAY be
+     * used to retrieve them. These MAY be injected during instantiation from
+     * PHP's $_POST superglobal. The data IS NOT REQUIRED to come from $_POST,
+     * but MUST be an array.
      *
-     * In other cases, the parent getBody() method should be used to retrieve
-     * the body content.
+     * In cases where the request content cannot be coerced to an array, the
+     * parent getBody() method should be used to retrieve the body content.
      *
-     * @return array|object The deserialized body parameters, if any. These may
-     *                      be either an array or an object, though an array or
-     *                      array-like object is recommended.
+     * @return array The deserialized body parameters, if any.
      */
     public function getBodyParams();
 
     /**
      * Set the request body parameters.
      *
-     * If the body content can be deserialized, the values obtained may then
-     * be injected into the response using this method. This method will
-     * typically be invoked by a factory marshaling request parameters.
-     *
-     * @param array|object $values The deserialized body parameters, if any.
-     *                             These may be either an array or an object,
-     *                             though an array or array-like object is
-     *                             recommended.
+     * If the body content can be deserialized to an array, the values obtained
+     * MAY then be injected into the response using this method. This method
+     * will typically be invoked by a factory marshaling request parameters.
      *
+     * @param array $values The deserialized body parameters, if any.
      * @return void
+     * @throws \InvalidArgumentException For $values that cannot be accepted.
      */
-    public function setBodyParams($values);
+    public function setBodyParams(array $values);
 
     /**
-     * Retrieve parameters matched during routing.
+     * Retrieve attributes derived from the request.
      *
      * If a router or similar is used to match against the path and/or request,
-     * this method can be used to retrieve the results, so long as those
-     * results can be represented as an array or array-like object.
+     * this method MAY be used to retrieve the results, so long as those
+     * results can be represented as an array.
      *
-     * @return array|\ArrayAccess Path parameters matched by routing
+     * @return array Attributes derived from the request.
      */
-    public function getPathParams();
+    public function getAttributes();
 
     /**
-     * Set parameters discovered by matching that path
+     * Set attributes derived from the request
      *
      * If a router or similar is used to match against the path and/or request,
-     * this method can be used to inject the request with the results, so long
-     * as those results can be represented as an array or array-like object.
-     *
-     * @param array|\ArrayAccess $values Path parameters matched by routing
+     * this method MAY be used to inject the request with the results, so long
+     * as those results can be represented as an array.
      *
+     * @param array $attributes Attributes derived from the request.
      * @return void
      */
-    public function setPathParams(array $values);
+    public function setAttributes(array $attributes);
 }

src/MessageInterface.php

@@ -4,7 +4,11 @@
 
 /**
  * HTTP messages consist of requests from a client to a server and responses
- * from a server to a client.
+ * from a server to a client. This interface defines the methods common to
+ * each.
+ *
+ * @link http://www.ietf.org/rfc/rfc7230.txt
+ * @link http://www.ietf.org/rfc/rfc7231.txt
  */
 interface MessageInterface
 {
@@ -24,7 +28,6 @@ public function getProtocolVersion();
      * "1.1", "1.0").
      *
      * @param string $version HTTP protocol version
-     *
      * @return void
      */
     public function setProtocolVersion($version);
@@ -43,9 +46,7 @@ public function getBody();
      * remove the existing body.
      *
      * @param StreamableInterface|null $body Body.
-     *
      * @return void
-     *
      * @throws \InvalidArgumentException When the body is not valid.
      */
     public function setBody(StreamableInterface $body = null);
@@ -61,15 +62,22 @@ public function setBody(StreamableInterface $body = null);
      *         echo $name . ": " . implode(", ", $values);
      *     }
      *
-     * @return array Returns an associative array of the message's headers.
+     *     // Emit headers iteratively:
+     *     foreach ($message->getHeaders() as $name => $values) {
+     *         foreach ($values as $value) {
+     *             header(sprintf('%s: %s', $name, $value), false);
+     *         }
+     *     }
+     *
+     * @return array Returns an associative array of the message's headers. Each
+     *     key MUST be a header name, and each value MUST be an array of strings.
      */
     public function getHeaders();
 
     /**
      * Checks if a header exists by the given case-insensitive name.
      *
      * @param string $header Case-insensitive header name.
-     *
      * @return bool Returns true if any header names match the given header
      *     name using a case-insensitive string comparison. Returns false if
      *     no matching header name is found in the message.
@@ -84,7 +92,6 @@ public function hasHeader($header);
      * a comma.
      *
      * @param string $header Case-insensitive header name.
-     *
      * @return string
      */
     public function getHeader($header);
@@ -93,7 +100,6 @@ public function getHeader($header);
      * Retrieves a header by the given case-insensitive name as an array of strings.
      *
      * @param string $header Case-insensitive header name.
-     *
      * @return string[]
      */
     public function getHeaderAsArray($header);
@@ -106,64 +112,29 @@ public function getHeaderAsArray($header);
      * or an array of strings.
      *
      * @param string $header Header name
-     * @param string|string[]|object|object[] $value Header value(s). Values may 
-     *                                               be objects as long as they
-     *                                               can be cast to strings.
-     *
+     * @param string|string[] $value Header value(s).
      * @return void
+     * @throws \InvalidArgumentException for invalid header names or values.
      */
     public function setHeader($header, $value);
 
-    /**
-     * Sets headers, replacing any headers that have already been set on the message.
-     *
-     * The array keys MUST be a string. Each array value MUST be either a string
-     * or object, or array of strings and/or objects; any object used as a
-     * header value MUST be able to be cast to a string.
-     *
-     * @param array $headers Headers to set.
-     *
-     * @return void
-     */
-    public function setHeaders(array $headers);
-
     /**
      * Appends a header value for the specified header.
      *
      * Existing values for the specified header will be maintained. The new
-     * value will be appended to the existing list.
+     * value(s) will be appended to the existing list.
      *
      * @param string $header Header name to add
-     * @param string|object $value Value of the header; object is allowed if it
-     *                             can be cast to a string.
-     *
+     * @param string|string[] $value Header value(s).
      * @return void
+     * @throws \InvalidArgumentException for invalid header names or values.
      */
     public function addHeader($header, $value);
 
-    /**
-     * Merges in an associative array of headers.
-     *
-     * Each array key MUST be a string representing the case-insensitive name
-     * of a header. Each value MUST be either a string or object, or array of
-     * strings and/or objects; any object used as a header value MUST be able
-     * to be cast to a string.
-     *
-     * For each value, the value is appended to any existing header of the same
-     * name, or, if a header does not already exist by the given name, then the
-     * header is added.
-     *
-     * @param array $headers Associative array of headers to add to the message
-     *
-     * @return void
-     */
-    public function addHeaders(array $headers);
-
     /**
      * Remove a specific header by case-insensitive name.
      *
      * @param string $header HTTP header to remove
-     *
      * @return void
      */
     public function removeHeader($header);

src/RequestInterface.php

@@ -3,39 +3,40 @@
 namespace Psr\Http\Message;
 
 /**
- * A HTTP request message.
- * @link http://tools.ietf.org/html/rfc2616#section-5
+ * An HTTP request message.
+ *
+ * @link http://tools.ietf.org/html/rfc7230#section-3
  */
 interface RequestInterface extends MessageInterface
 {
     /**
-     * Gets the HTTP method of the request.
+     * Retrieves the HTTP method of the request.
      *
      * @return string Returns the request method.
      */
     public function getMethod();
 
     /**
-     * Sets the method to be performed on the resource identified by the Request-URI.
+     * Sets the HTTP method to be performed on the resource identified by the
+     * Request-URI.
      *
      * While HTTP method names are typically all uppercase characters, HTTP
      * method names are case-sensitive and thus implementations SHOULD NOT
      * modify the given string.
      *
      * @param string $method Case-insensitive method.
-     *
      * @return void
+     * @throws \InvalidArgumentException for invalid HTTP methods.
      */
     public function setMethod($method);
 
     /**
-     * Gets the absolute request URL.
+     * Retrieves the absolute request URL.
      *
+     * @link http://tools.ietf.org/html/rfc3986#section-4.3
      * @return string|object Returns the URL as a string, or an object that
      *    implements the `__toString()` method. The URL must be an absolute URI
      *    as specified in RFC 3986.
-     *
-     * @link http://tools.ietf.org/html/rfc3986#section-4.3
      */
     public function getUrl();
 
@@ -46,12 +47,10 @@ public function getUrl();
      * `__toString()` method. The URL must be an absolute URI as specified
      * in RFC 3986.
      *
+     * @link http://tools.ietf.org/html/rfc3986#section-4.3
      * @param string|object $url Request URL.
-     *
      * @return void
-     *
      * @throws \InvalidArgumentException If the URL is invalid.
-     * @link http://tools.ietf.org/html/rfc3986#section-4.3
      */
     public function setUrl($url);
 }