Updated with recent feedback

Author: Phil Sturgeon

src/MessageInterface.php

@@ -9,8 +9,9 @@
 interface MessageInterface
 {
     /**
-     * Gets the HTTP protocol version as a string containing only the HTTP
-     * version (e.g., "1.1", "1.0").
+     * Gets the HTTP protocol version as a string.
+     *
+     * The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
      *
      * @return string HTTP protocol version.
      */
@@ -32,6 +33,8 @@ public function getBody();
      * @param StreamInterface|null $body Body.
      *
      * @return void
+     *
+     * @throws \InvalidArgumentException When the body is not valid.
      */
     public function setBody(StreamInterface $body = null);
 
@@ -75,31 +78,30 @@ public function hasHeader($header);
     public function getHeader($header);
 
     /**
-     * Retrieve a header by the given case-insensitive name as an array of
-     * strings.
+     * Retrieves a header by the given case-insensitive name as an array of strings.
      *
      * @param string $header Case-insensitive header name.
      *
-     * @return array
+     * @return string[]
      */
     public function getHeaderAsArray($header);
 
     /**
      * Sets a header, replacing any existing values of any headers with the
      * same case-insensitive name.
      *
-     * The header values MUST be a string or an array of strings.
+     * The header name is case-insensitive. The header values MUST be a string
+     * or an array of strings.
      *
-     * @param string       $header Header name
-     * @param string|array $value  Header value(s)
+     * @param string $header Header name
+     * @param string|string[] $value  Header value(s)
      *
      * @return void
      */
     public function setHeader($header, $value);
 
     /**
-     * Sets headers, replacing any headers that have already been set on the
-     * message.
+     * Sets headers, replacing any headers that have already been set on the message.
      *
      * The array keys MUST be a string. The array values must be either a
      * string or an array of strings.
@@ -111,8 +113,10 @@ public function setHeader($header, $value);
     public function setHeaders(array $headers);
 
     /**
-     * Appends a header value to any existing values associated with the
-     * given header name.
+     * 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.
      *
      * @param string $header Header name to add
      * @param string $value  Value of the header

src/RequestInterface.php

@@ -16,8 +16,7 @@ interface RequestInterface extends MessageInterface
     public function getMethod();
 
     /**
-     * Sets the method to be performed on the resource identified by the
-     * Request-URI.
+     * Sets the 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
@@ -32,7 +31,11 @@ public function setMethod($method);
     /**
      * Gets the absolute request URL.
      *
-     * @return string Returns the URL as a string.
+     * @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();
 
@@ -43,9 +46,10 @@ public function getUrl();
      * `__toString()` method. The URL must be an absolute URI as specified
      * in RFC 3986.
      *
-     * @param string $url Request URL.
+     * @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
      */

src/ResponseInterface.php

@@ -9,16 +9,24 @@
 interface ResponseInterface extends MessageInterface
 {
     /**
-     * Gets the response Status-Code, a 3-digit integer result code of the
-     * server's attempt to understand and satisfy the request.
+     * Gets the response Status-Code.
+     *
+     * 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.
      */
     public function getStatusCode();
 
     /**
-     * Gets the response Reason-Phrase, a short textual description of the
-     * Status-Code.
+     * Sets the status code of this response.
+     *
+     * @param integer $code The 3-digit integer result code to set.
+     */
+    public function setStatusCode($code);
+
+    /**
+     * Gets the response Reason-Phrase, a short textual description of the Status-Code.
      *
      * Because a Reason-Phrase is not a required element in response
      * Status-Line, the Reason-Phrase value MAY be null. Implementations MAY
@@ -28,4 +36,14 @@ public function getStatusCode();
      * @return string|null Reason phrase, or null if unknown.
      */
     public function getReasonPhrase();
+
+    /**
+     * Sets the Reason-Phrase of the response.
+     *
+     * If no Reason-Phrase is specified, implementations MAY choose to default
+     * to the RFC 2616 recommended reason phrase for the response's Status-Code.
+     *
+     * @param string $phrase The Reason-Phrase to set.
+     */
+    public function setReasonPhrase($phrase);
 }

src/StreamInterface.php

@@ -8,8 +8,10 @@
 interface StreamInterface
 {
     /**
-     * Attempts to seek to the beginning of the stream and reads all data into
-     * a string until the end of the stream is reached.
+     * Reads all data from the stream into a string, from the beginning to end.
+     *
+     * This method MUST attempt to seek to the beginning of the stream before
+     * reading data and read the stream until the end is reached.
      *
      * Warning: This could attempt to load a large amount of data into memory.
      *
@@ -19,13 +21,17 @@ public function __toString();
 
     /**
      * Closes the stream and any underlying resources.
+     *
+     * @return void
      */
     public function close();
 
     /**
      * Separates any underlying resources from the stream.
      *
      * After the stream has been detached, the stream is in an unusable state.
+     *
+     * @return void
      */
     public function detach();