Use consistent verbiage and formatting.

Cleaned up for consistent verbiage around mutability. All return values
that returned the interface name were altered to use `self`, to ensure
that they report correctly in documentation and IDEs.

`ServerRequest::setAttributes()` was removed, per @Crell, and
`ServerRequest::withoutAttribute()` added (to make usage consistent with
headers).

Author: weierophinney

src/MessageInterface.php

@@ -17,7 +17,7 @@
 interface MessageInterface
 {
     /**
-     * Gets the HTTP protocol version as a string.
+     * Retrieves the HTTP protocol version as a string.
      *
      * The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
      *
@@ -36,12 +36,12 @@ public function getProtocolVersion();
      * new protocol version.
      *
      * @param string $version HTTP protocol version
-     * @return MessageInterface
+     * @return self
      */
     public function withProtocolVersion($version);
 
     /**
-     * Gets all message headers.
+     * Retrieves all message headers.
      *
      * 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.
@@ -81,7 +81,8 @@ public function hasHeader($header);
      * a comma.
      *
      * NOTE: Not all header values may be appropriately represented using
-     * comma concatenation.
+     * comma concatenation. For such headers, use getHeaderLines() instead
+     * and supply your own delimiter when concatenating.
      *
      * @param string $header Case-insensitive header name.
      * @return string
@@ -109,7 +110,7 @@ public function getHeaderLines($header);
      *
      * @param string $header Header name
      * @param string|string[] $value Header value(s).
-     * @return MessageInterface
+     * @return self
      * @throws \InvalidArgumentException for invalid header names or values.
      */
     public function withHeader($header, $value);
@@ -119,30 +120,31 @@ public function withHeader($header, $value);
      * given value.
      *
      * Existing values for the specified header will be maintained. The new
-     * value(s) will be appended to the existing list.
+     * 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
      * new header and/or value.
      *
      * @param string $header Header name to add
      * @param string|string[] $value Header value(s).
-     * @return MessageInterface
+     * @return self
      * @throws \InvalidArgumentException for invalid header names or values.
      */
     public function withAddedHeader($header, $value);
 
     /**
      * Creates a new instance, without the specified header.
      *
-     * Header resolution MUST be done without case-insensitivity.
+     * 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
      * the named header.
      *
      * @param string $header HTTP header to remove
-     * @return MessageInterface
+     * @return self
      */
     public function withoutHeader($header);
 
@@ -163,7 +165,7 @@ public function getBody();
      * new body stream.
      *
      * @param StreamableInterface $body Body.
-     * @return MessageInterface
+     * @return self
      * @throws \InvalidArgumentException When the body is not valid.
      */
     public function withBody(StreamableInterface $body);

src/RequestInterface.php

@@ -28,8 +28,7 @@ interface RequestInterface extends MessageInterface
     public function getMethod();
 
     /**
-     * Create a new instance with the provided HTTP method to perform on the
-     * resource identified by the Request-URI.
+     * Create a new 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
@@ -40,13 +39,13 @@ public function getMethod();
      * changed request method.
      *
      * @param string $method Case-insensitive method.
-     * @return RequestInterface
+     * @return self
      * @throws \InvalidArgumentException for invalid HTTP methods.
      */
     public function withMethod($method);
 
     /**
-     * Retrieves the absolute URI.
+     * Retrieves the URI instance.
      *
      * This method MUST return a UriInterface instance.
      *
@@ -65,7 +64,7 @@ public function getUri();
      *
      * @link http://tools.ietf.org/html/rfc3986#section-4.3
      * @param UriInterface $uri New request URI to use.
-     * @return RequestInterface
+     * @return self
      */
     public function withUri(UriInterface $uri);
 }

src/ResponseInterface.php

@@ -47,7 +47,7 @@ public function getStatusCode();
      * @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.
-     * @return ResponseInterface
+     * @return self
      * @throws \InvalidArgumentException For invalid status code arguments.
      */
     public function withStatus($code, $reasonPhrase = null);

src/ServerRequestInterface.php

@@ -10,12 +10,12 @@
  *
  * - Protocol version
  * - HTTP method
- * - URL
+ * - URI
  * - Headers
  * - Message body
  *
  * Additionally, it encapsulates all data as it has arrived to the
- * application from the PHP environment, including:
+ * application from the CGI and/or PHP environment, including:
  *
  * - The values represented in $_SERVER.
  * - Any cookies provided (generally via $_COOKIE)
@@ -77,7 +77,7 @@ public function getCookieParams();
      * updated cookie values.
      *
      * @param array $cookies Array of key/value pairs representing cookies.
-     * @return ServerRequestInterface
+     * @return self
      */
     public function withCookieParams(array $cookies);
 
@@ -102,7 +102,7 @@ public function getQueryParams();
      * 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
+     * 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.
      *
@@ -115,7 +115,7 @@ public function getQueryParams();
      *
      * @param array $query Array of query string arguments, typically from
      *     $_GET.
-     * @return ServerRequestInterface
+     * @return self
      */
     public function withQueryParams(array $query);
 
@@ -159,7 +159,7 @@ public function getBodyParams();
      * updated body parameters.
      *
      * @param array $params The deserialized body parameters.
-     * @return ServerRequestInterface
+     * @return self
      */
     public function withBodyParams(array $params);
 
@@ -183,6 +183,9 @@ public function getAttributes();
      * getAttributes(). If the attribute has not been previously set, returns
      * the default value as provided.
      *
+     * This method obviates the need for a hasAttribute() method, as it allows
+     * specifying a default value to return if the attribute is not found.
+     *
      * @see getAttributes()
      * @param string $attribute Attribute name.
      * @param mixed $default Default value to return if the attribute does not exist.
@@ -191,36 +194,37 @@ public function getAttributes();
     public function getAttribute($attribute, $default = null);
 
     /**
-     * Create a new instance with the specified attributes as derived from the
-     * request.
+     * Create a new instance with the specified derived request attribute.
      *
-     * This method allows setting request attributes, as described in
-     * getAttributes().
+     * This method allows setting a single derived request attribute as
+     * described in getAttributes().
      *
      * 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
-     * updated attributes.
+     * updated attribute.
      *
      * @see getAttributes()
-     * @param array $attributes Attributes derived from the request.
-     * @return ServerRequestInterface
+     * @param string $attribute The attribute name.
+     * @param mixed $value The value of the attribute.
+     * @return self
      */
-    public function withAttributes(array $attributes);
+    public function withAttribute($attribute, $value);
 
     /**
-     * Create a new instance with the specified derived request attribute.
+     * Create a new instance that removes the specified derived request
+     * attribute.
      *
-     * This method allows setting a single derived request attribute as
+     * This method allows removing a single derived request attribute as
      * described in getAttributes().
      *
      * 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
-     * updated attribute.
+     * immutability of the message, and MUST return a new instance that removes
+     * the attribute.
      *
      * @see getAttributes()
      * @param string $attribute The attribute name.
      * @param mixed $value The value of the attribute.
-     * @return ServerRequestInterface
+     * @return self
      */
-    public function withAttribute($attribute, $value);
+    public function withoutAttribute($attribute, $value);
 }

src/StreamableInterface.php

@@ -70,15 +70,13 @@ public function isSeekable();
     /**
      * Seek to a position in the stream.
      *
-     * @link  http://www.php.net/manual/en/function.fseek.php
+     * @link http://www.php.net/manual/en/function.fseek.php
      * @param int $offset Stream offset
      * @param int $whence Specifies how the cursor position will be calculated
-     *                    based on the seek offset. Valid values are identical
-     *                    to the built-in PHP $whence values for `fseek()`.
-     *                    SEEK_SET: Set position equal to offset bytes
-     *                    SEEK_CUR: Set position to current location plus offset
-     *                    SEEK_END: Set position to end-of-stream plus offset
-     *
+     *     based on the seek offset. Valid values are identical to the built-in
+     *     PHP $whence values for `fseek()`.  SEEK_SET: Set position equal to
+     *     offset bytes SEEK_CUR: Set position to current location plus offset
+     *     SEEK_END: Set position to end-of-stream plus offset.
      * @return bool Returns TRUE on success or FALSE on failure.
      */
     public function seek($offset, $whence = SEEK_SET);
@@ -90,6 +88,8 @@ public function seek($offset, $whence = SEEK_SET);
      * failure; otherwise, it will perform a seek(0), and return the status of
      * that operation.
      *
+     * @see seek()
+     * @link http://www.php.net/manual/en/function.fseek.php
      * @return bool Returns TRUE on success or FALSE on failure.
      */
     public function rewind();
@@ -105,9 +105,8 @@ public function isWritable();
      * Write data to the stream.
      *
      * @param string $string The string that is to be written.
-     *
      * @return int|bool Returns the number of bytes written to the stream on
-     *                  success or FALSE on failure.
+     *     success or FALSE on failure.
      */
     public function write($string);
 
@@ -122,10 +121,10 @@ public function isReadable();
      * Read data from the stream.
      *
      * @param int $length Read up to $length bytes from the object and return
-     *                    them. Fewer than $length bytes may be returned if
-     *                    underlying stream call returns fewer bytes.
+     *     them. Fewer than $length bytes may be returned if underlying stream
+     *     call returns fewer bytes.
      * @return string|false Returns the data read from the stream, false if
-     *                      unable to read or if an error occurs.
+     *     unable to read or if an error occurs.
      */
     public function read($length);
 
@@ -145,9 +144,8 @@ public function getContents();
      * @link http://php.net/manual/en/function.stream-get-meta-data.php
      * @param string $key Specific metadata to retrieve.
      * @return array|mixed|null Returns an associative array if no key is
-     *                          provided. Returns a specific key value if a key
-     *                          is provided and the value is found, or null if
-     *                          the key is not found.
+     *     provided. Returns a specific key value if a key is provided and the
+     *     value is found, or null if the key is not found.
      */
     public function getMetadata($key = null);
 }