Merge pull request #38 from weierophinney/feature/post-draft-2

Bring interfaces up-to-date with php-fig/fig-standards@b740164

Author: Paul M. Jones

src/MessageInterface.php

@@ -9,7 +9,7 @@
  *
  * Messages are considered immutable; all methods that might change state MUST
  * be implemented such that they retain the internal state of the current
- * message and return a new instance that contains the changed state.
+ * message and return an instance that contains the changed state.
  *
  * @link http://www.ietf.org/rfc/rfc7230.txt
  * @link http://www.ietf.org/rfc/rfc7231.txt
@@ -26,13 +26,13 @@ interface MessageInterface
     public function getProtocolVersion();
 
     /**
-     * Create a new instance with the specified HTTP protocol version.
+     * Return an instance with the specified HTTP protocol version.
      *
      * The version string MUST contain only the HTTP version number (e.g.,
      * "1.1", "1.0").
      *
      * This method MUST be implemented in such a way as to retain the
-     * immutability of the message, and MUST return a new instance that has the
+     * immutability of the message, and MUST return an instance that has the
      * new protocol version.
      *
      * @param string $version HTTP protocol version
@@ -41,7 +41,7 @@ public function getProtocolVersion();
     public function withProtocolVersion($version);
 
     /**
-     * Retrieves all message headers.
+     * Retrieves all message header values.
      *
      * The keys represent the header name as it will be sent over the wire, and
      * each value is an array of strings associated with the header.
@@ -62,7 +62,8 @@ public function withProtocolVersion($version);
      * exact case in which headers were originally specified.
      *
      * @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.
+     *     key MUST be a header name, and each value MUST be an array of strings
+     *     for that header.
      */
     public function getHeaders();
 
@@ -77,44 +78,52 @@ public function getHeaders();
     public function hasHeader($name);
 
     /**
-     * Retrieve a header by the given case-insensitive name, as a string.
+     * Retrieves a message header value by the given case-insensitive name.
      *
-     * This method returns all of the header values of the given
-     * case-insensitive header name as a string concatenated together using
-     * a comma.
+     * This method returns an array of all the header values of the given
+     * case-insensitive header name.
      *
-     * NOTE: Not all header values may be appropriately represented using
-     * comma concatenation. For such headers, use getHeaderLines() instead
-     * and supply your own delimiter when concatenating.
-     * 
-     * If the header did not appear in the message, this method should return
-     * a null value.
+     * If the header does not appear in the message, this method MUST return an
+     * empty array.
      *
      * @param string $name Case-insensitive header field name.
-     * @return string|null
+     * @return string[] An array of string values as provided for the given
+     *    header. If the header does not appear in the message, this method MUST
+     *    return an empty array.
      */
     public function getHeader($name);
 
     /**
-     * Retrieves a header by the given case-insensitive name as an array of strings.
-     * 
-     * If the header did not appear in the message, this method should return an
-     * empty array.
+     * Retrieves the line for a single header, with the header values as a
+     * comma-separated string.
+     *
+     * This method returns all of the header values of the given
+     * case-insensitive header name as a string concatenated together using
+     * a comma.
+     *
+     * NOTE: Not all header values may be appropriately represented using
+     * comma concatenation. For such headers, use getHeader() instead
+     * and supply your own delimiter when concatenating.
+     *
+     * If the header does not appear in the message, this method MUST return
+     * a null value.
      *
      * @param string $name Case-insensitive header field name.
-     * @return string[]
+     * @return string|null A string of values as provided for the given header
+     *    concatenated together using a comma. If the header does not appear in
+     *    the message, this method MUST return a null value.
      */
-    public function getHeaderLines($name);
+    public function getHeaderLine($name);
 
     /**
-     * Create a new instance with the provided header, replacing any existing
+     * Return an instance with the provided header, replacing any existing
      * values of any headers with the same case-insensitive name.
      *
      * While header names are case-insensitive, the casing of the header will
      * be preserved by this function, and returned from getHeaders().
      *
      * This method MUST be implemented in such a way as to retain the
-     * immutability of the message, and MUST return a new instance that has the
+     * immutability of the message, and MUST return an instance that has the
      * new and/or updated header and value.
      *
      * @param string $name Case-insensitive header field name.
@@ -125,15 +134,15 @@ public function getHeaderLines($name);
     public function withHeader($name, $value);
 
     /**
-     * Creates a new instance, with the specified header appended with the
+     * Return an instance with the specified header appended with the
      * given value.
      *
      * Existing values for the specified header will be maintained. The new
      * value(s) will be appended to the existing list. If the header did not
      * exist previously, it will be added.
      *
      * This method MUST be implemented in such a way as to retain the
-     * immutability of the message, and MUST return a new instance that has the
+     * immutability of the message, and MUST return an instance that has the
      * new header and/or value.
      *
      * @param string $name Case-insensitive header field name to add.
@@ -144,12 +153,12 @@ public function withHeader($name, $value);
     public function withAddedHeader($name, $value);
 
     /**
-     * Creates a new instance, without the specified header.
+     * Return an instance without the specified header.
      *
      * Header resolution MUST be done without case-sensitivity.
      *
      * This method MUST be implemented in such a way as to retain the
-     * immutability of the message, and MUST return a new instance that removes
+     * immutability of the message, and MUST return an instance that removes
      * the named header.
      *
      * @param string $name Case-insensitive header field name to remove.
@@ -160,22 +169,22 @@ public function withoutHeader($name);
     /**
      * Gets the body of the message.
      *
-     * @return StreamableInterface Returns the body as a stream.
+     * @return StreamInterface Returns the body as a stream.
      */
     public function getBody();
 
     /**
-     * Create a new instance, with the specified message body.
+     * Return an instance with the specified message body.
      *
-     * The body MUST be a StreamableInterface object.
+     * The body MUST be a StreamInterface object.
      *
      * This method MUST be implemented in such a way as to retain the
      * immutability of the message, and MUST return a new instance that has the
      * new body stream.
      *
-     * @param StreamableInterface $body Body.
+     * @param StreamInterface $body Body.
      * @return self
      * @throws \InvalidArgumentException When the body is not valid.
      */
-    public function withBody(StreamableInterface $body);
+    public function withBody(StreamInterface $body);
 }

src/RequestInterface.php

@@ -16,7 +16,7 @@
  *
  * Requests are considered immutable; all methods that might change state MUST
  * be implemented such that they retain the internal state of the current
- * message and return a new instance that contains the changed state.
+ * message and return an instance that contains the changed state.
  */
 interface RequestInterface extends MessageInterface
 {
@@ -28,7 +28,7 @@ interface RequestInterface extends MessageInterface
      *
      * This method acts exactly like MessageInterface::getHeaders(), with one
      * behavioral change: if the Host header has not been previously set, the
-     * method MUST attempt to pull the host segment of the composed URI, if
+     * method MUST attempt to pull the host component of the composed URI, if
      * present.
      *
      * @see MessageInterface::getHeaders()
@@ -45,32 +45,38 @@ public function getHeaders();
      * This method acts exactly like MessageInterface::getHeader(), with
      * one behavioral change: if the Host header is requested, but has
      * not been previously set, the method MUST attempt to pull the host
-     * segment of the composed URI, if present.
+     * component of the composed URI, if present.
      *
      * @see MessageInterface::getHeader()
      * @see UriInterface::getHost()
      * @param string $name Case-insensitive header field name.
-     * @return string
+     * @return string[] An array of string values as provided for the given
+     *    header. If the header does not appear in the message, this method MUST
+     *    return an empty array.
      */
     public function getHeader($name);
 
     /**
      * Extends MessageInterface::getHeaderLines() to provide request-specific
      * behavior.
      *
-     * Retrieves a header by the given case-insensitive name as an array of strings.
+     * This method returns all of the header values of the given
+     * case-insensitive header name as a string concatenated together using
+     * a comma.
      *
      * This method acts exactly like MessageInterface::getHeaderLines(), with
      * one behavioral change: if the Host header is requested, but has
      * not been previously set, the method MUST attempt to pull the host
-     * segment of the composed URI, if present.
+     * component of the composed URI, if present.
      *
-     * @see MessageInterface::getHeaderLines()
+     * @see MessageInterface::getHeaderLine()
      * @see UriInterface::getHost()
      * @param string $name Case-insensitive header field name.
-     * @return string[]
+     * @return string|null A string of values as provided for the given header
+     *    concatenated together using a comma. If the header does not appear in
+     *    the message, this method MUST return a null value.
      */
-    public function getHeaderLines($name);
+    public function getHeaderLine($name);
 
     /**
      * Retrieves the message's request target.
@@ -91,15 +97,15 @@ public function getHeaderLines($name);
     public function getRequestTarget();
 
     /**
-     * Create a new instance with a specific request-target.
+     * Return an instance with the specific request-target.
      *
      * If the request needs a non-origin-form request-target — e.g., for
      * specifying an absolute-form, authority-form, or asterisk-form —
      * this method may be used to create an instance with the specified
      * request-target, verbatim.
      *
      * This method MUST be implemented in such a way as to retain the
-     * immutability of the message, and MUST return a new instance that has the
+     * immutability of the message, and MUST return an instance that has the
      * changed request target.
      *
      * @link http://tools.ietf.org/html/rfc7230#section-2.7 (for the various
@@ -117,14 +123,14 @@ public function withRequestTarget($requestTarget);
     public function getMethod();
 
     /**
-     * Create a new instance with the provided HTTP method.
+     * Return an instance with the provided HTTP method.
      *
      * While HTTP method names are typically all uppercase characters, HTTP
      * method names are case-sensitive and thus implementations SHOULD NOT
      * modify the given string.
      *
      * This method MUST be implemented in such a way as to retain the
-     * immutability of the message, and MUST return a new instance that has the
+     * immutability of the message, and MUST return an instance that has the
      * changed request method.
      *
      * @param string $method Case-insensitive method.
@@ -145,15 +151,29 @@ public function withMethod($method);
     public function getUri();
 
     /**
-     * Create a new instance with the provided URI.
+     * Returns an instance with the provided URI.
+     *
+     * This method will update the Host header of the returned request by
+     * default if the URI contains a host component. If the URI does not
+     * contain a host component, any pre-existing Host header will be carried
+     * over to the returned request.
+     *
+     * You can opt-in to preserving the original state of the Host header by
+     * setting `$preserveHost` to `true`. When `$preserveHost` is set to
+     * `true`, the returned request will not update the Host header of the
+     * returned message -- even if the message contains no Host header. This
+     * means that a call to `getHeader('Host')` on the original request MUST
+     * equal the return value of a call to `getHeader('Host')` on the returned
+     * request.
      *
      * This method MUST be implemented in such a way as to retain the
-     * immutability of the message, and MUST return a new instance that has the
+     * immutability of the message, and MUST return an instance that has the
      * new UriInterface instance.
      *
      * @link http://tools.ietf.org/html/rfc3986#section-4.3
      * @param UriInterface $uri New request URI to use.
+     * @param bool $preserveHost Preserve the original state of the Host header.
      * @return self
      */
-    public function withUri(UriInterface $uri);
+    public function withUri(UriInterface $uri, $preserveHost = false);
 }

src/ResponseInterface.php

@@ -15,35 +15,35 @@
  *
  * Responses are considered immutable; all methods that might change state MUST
  * be implemented such that they retain the internal state of the current
- * message and return a new instance that contains the changed state.
+ * message and return an instance that contains the changed state.
  */
 interface ResponseInterface extends MessageInterface
 {
     /**
-     * Gets the response Status-Code.
+     * Gets the response status code.
      *
-     * The Status-Code is a 3-digit integer result code of the server's attempt
+     * The status code is a 3-digit integer result code of the server's attempt
      * to understand and satisfy the request.
      *
-     * @return integer Status code.
+     * @return int Status code.
      */
     public function getStatusCode();
 
     /**
-     * Create a new instance with the specified status code, and optionally
+     * Return an instance with the specified status code, and optionally
      * reason phrase, for the response.
      *
-     * If no Reason-Phrase is specified, implementations MAY choose to default
+     * If no reason phrase is specified, implementations MAY choose to default
      * to the RFC 7231 or IANA recommended reason phrase for the response's
-     * Status-Code.
+     * status code.
      *
      * This method MUST be implemented in such a way as to retain the
-     * immutability of the message, and MUST return a new instance that has the
+     * immutability of the message, and MUST return an instance that has the
      * updated status and reason phrase.
      *
      * @link http://tools.ietf.org/html/rfc7231#section-6
      * @link http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
-     * @param integer $code The 3-digit integer result code to set.
+     * @param int $code The 3-digit integer result code to set.
      * @param null|string $reasonPhrase The reason phrase to use with the
      *     provided status code; if none is provided, implementations MAY
      *     use the defaults as suggested in the HTTP specification.
@@ -53,13 +53,14 @@ public function getStatusCode();
     public function withStatus($code, $reasonPhrase = null);
 
     /**
-     * Gets the response Reason-Phrase, a short textual description of the Status-Code.
+     * Gets the response reason phrase, a short textual description of the
+     * status code.
      *
-     * Because a Reason-Phrase is not a required element in a response
-     * Status-Line, the Reason-Phrase value MAY be null. Implementations MAY
+     * Because a reason phrase is not a required element in a response
+     * status line, the reason phrase value MAY be null. Implementations MAY
      * choose to return the default RFC 7231 recommended reason phrase (or those
      * listed in the IANA HTTP Status Code Registry) for the response's
-     * Status-Code.
+     * status code.
      *
      * @link http://tools.ietf.org/html/rfc7231#section-6
      * @link http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml