Renamed all mutator methods

Since messages are immutable, and to avoid confusion with regular setters that
change internal state, I've renamed all setter methods to use alternate
verbiage. "with" is an accepted standard, and this was used whenever possible,
with the following exceptions:

- `addHeader` was renamed to `withAddedHeader()`.
- `removeHeader` was renamed to `withoutHeader()`.

Author: weierophinney

src/MessageInterface.php

@@ -26,7 +26,7 @@ interface MessageInterface
     public function getProtocolVersion();
 
     /**
-     * Set the HTTP protocol version.
+     * Create a new instance with the specified HTTP protocol version.
      *
      * The version string MUST contain only the HTTP version number (e.g.,
      * "1.1", "1.0").
@@ -38,7 +38,7 @@ public function getProtocolVersion();
      * @param string $version HTTP protocol version
      * @return MessageInterface
      */
-    public function setProtocolVersion($version);
+    public function withProtocolVersion($version);
 
     /**
      * Gets all message headers.
@@ -97,8 +97,8 @@ public function getHeader($header);
     public function getHeaderLines($header);
 
     /**
-     * Sets a header, replacing any existing values of any headers with the
-     * same case-insensitive name.
+     * Create a new instance with the provided header, replacing any existing
+     * values of any headers with the same case-insensitive name.
      *
      * The header name is case-insensitive. The header values MUST be a string
      * or an array of strings.
@@ -112,10 +112,11 @@ public function getHeaderLines($header);
      * @return MessageInterface
      * @throws \InvalidArgumentException for invalid header names or values.
      */
-    public function setHeader($header, $value);
+    public function withHeader($header, $value);
 
     /**
-     * Appends a header value for the specified header.
+     * Creates a new 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.
@@ -129,10 +130,12 @@ public function setHeader($header, $value);
      * @return MessageInterface
      * @throws \InvalidArgumentException for invalid header names or values.
      */
-    public function addHeader($header, $value);
+    public function withAddedHeader($header, $value);
 
     /**
-     * Remove a specific header by case-insensitive name.
+     * Creates a new instance, without the specified header.
+     *
+     * Header resolution MUST be done without case-insensitivity.
      *
      * 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
@@ -141,7 +144,7 @@ public function addHeader($header, $value);
      * @param string $header HTTP header to remove
      * @return MessageInterface
      */
-    public function removeHeader($header);
+    public function withoutHeader($header);
 
     /**
      * Gets the body of the message.
@@ -151,7 +154,7 @@ public function removeHeader($header);
     public function getBody();
 
     /**
-     * Sets the body of the message.
+     * Create a new instance, with the specified message body.
      *
      * The body MUST be a StreamableInterface object.
      *
@@ -163,5 +166,5 @@ public function getBody();
      * @return MessageInterface
      * @throws \InvalidArgumentException When the body is not valid.
      */
-    public function setBody(StreamableInterface $body);
+    public function withBody(StreamableInterface $body);
 }

src/RequestInterface.php

@@ -28,8 +28,8 @@ interface RequestInterface extends MessageInterface
     public function getMethod();
 
     /**
-     * Sets the HTTP method to be performed on the resource identified by the
-     * Request-URI.
+     * Create a new instance with the provided HTTP method to perform 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
@@ -43,7 +43,7 @@ public function getMethod();
      * @return RequestInterface
      * @throws \InvalidArgumentException for invalid HTTP methods.
      */
-    public function setMethod($method);
+    public function withMethod($method);
 
     /**
      * Retrieves the absolute URI.
@@ -70,7 +70,7 @@ public function setMethod($method);
     public function getAbsoluteUri();
 
     /**
-     * Sets the absolute URI of the request.
+     * Create a new instance with the provided absolute URI.
      *
      * The absolute URI MUST be a string, and MUST include the scheme and host.
      *
@@ -92,7 +92,7 @@ public function getAbsoluteUri();
      * @return RequestInterface
      * @throws \InvalidArgumentException If the URI is invalid.
      */
-    public function setAbsoluteUri($uri);
+    public function withAbsoluteUri($uri);
 
     /**
      * Retrieves the request URL.
@@ -106,7 +106,7 @@ public function setAbsoluteUri($uri);
     public function getUrl();
 
     /**
-     * Sets the request URL.
+     * Create a new instance with the specified request URL.
      *
      * The URL MUST be a string. The URL SHOULD be an origin-form (path + query
      * string) per RFC 7230 section 5.3; if other URL parts are present, the
@@ -124,5 +124,5 @@ public function getUrl();
      * @return RequestInterface
      * @throws \InvalidArgumentException If the URL is invalid.
      */
-    public function setUrl($url);
+    public function withUrl($url);
 }

src/ResponseInterface.php

@@ -30,7 +30,8 @@ interface ResponseInterface extends MessageInterface
     public function getStatusCode();
 
     /**
-     * Sets the status code, and optionally reason phrase,  of this response.
+     * Create a new instance with the specified status code, and optionally
+     * reason phrase, for the response.
      *
      * If no Reason-Phrase is specified, implementations MAY choose to default
      * to the RFC 7231 or IANA recommended reason phrase for the response's
@@ -49,7 +50,7 @@ public function getStatusCode();
      * @return ResponseInterface
      * @throws \InvalidArgumentException For invalid status code arguments.
      */
-    public function setStatus($code, $reasonPhrase = null);
+    public function withStatus($code, $reasonPhrase = null);
 
     /**
      * Gets the response Reason-Phrase, a short textual description of the Status-Code.

src/ServerRequestInterface.php

@@ -66,9 +66,7 @@ public function getServerParams();
     public function getCookieParams();
 
     /**
-     * Set cookies.
-     *
-     * Set cookies sent by the client to the server.
+     * Create a new instance with the specified cookies.
      *
      * The data IS NOT REQUIRED to come from the $_COOKIE superglobal, but MUST
      * be compatible with the structure of $_COOKIE. Typically, this data will
@@ -81,7 +79,7 @@ public function getCookieParams();
      * @param array $cookies Array of key/value pairs representing cookies.
      * @return ServerRequestInterface
      */
-    public function setCookieParams(array $cookies);
+    public function withCookieParams(array $cookies);
 
     /**
      * Retrieve query string arguments.
@@ -98,7 +96,7 @@ public function setCookieParams(array $cookies);
     public function getQueryParams();
 
     /**
-     * Set query string arguments.
+     * Create a new instance with the specified query string arguments.
      *
      * These values SHOULD remain immutable over the course of the incoming
      * request. They MAY be injected during instantiation, such as from PHP's
@@ -119,7 +117,7 @@ public function getQueryParams();
      *     $_GET.
      * @return ServerRequestInterface
      */
-    public function setQueryParams(array $query);
+    public function withQueryParams(array $query);
 
     /**
      * Retrieve the upload file metadata.
@@ -146,7 +144,7 @@ public function getFileParams();
     public function getBodyParams();
 
     /**
-     * Set parameters provided in the request body.
+     * Create a new instance with the specified body parameters.
      *
      * These MAY be injected during instantiation from PHP's $_POST
      * superglobal. The data IS NOT REQUIRED to come from $_POST, but MUST be
@@ -163,7 +161,7 @@ public function getBodyParams();
      * @param array $params The deserialized body parameters.
      * @return ServerRequestInterface
      */
-    public function setBodyParams(array $params);
+    public function withBodyParams(array $params);
 
     /**
      * Retrieve attributes derived from the request.
@@ -193,7 +191,8 @@ public function getAttributes();
     public function getAttribute($attribute, $default = null);
 
     /**
-     * Set attributes derived from the request.
+     * Create a new instance with the specified attributes as derived from the
+     * request.
      *
      * This method allows setting request attributes, as described in
      * getAttributes().
@@ -206,10 +205,10 @@ public function getAttribute($attribute, $default = null);
      * @param array $attributes Attributes derived from the request.
      * @return ServerRequestInterface
      */
-    public function setAttributes(array $attributes);
+    public function withAttributes(array $attributes);
 
     /**
-     * Set a single derived request attribute.
+     * Create a new instance with the specified derived request attribute.
      *
      * This method allows setting a single derived request attribute as
      * described in getAttributes().
@@ -223,5 +222,5 @@ public function setAttributes(array $attributes);
      * @param mixed $value The value of the attribute.
      * @return ServerRequestInterface
      */
-    public function setAttribute($attribute, $value);
+    public function withAttribute($attribute, $value);
 }