Implementing immutability in messages

Marked all classes and setters as immutable. All setters have language
indicating they MUST be implemented to keep immutable state of the
object, and MUST return a new instance with the modified values.

Author: weierophinney

src/MessageInterface.php

@@ -7,6 +7,10 @@
  * from a server to a client. This interface defines the methods common to
  * each.
  *
+ * 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.
+ *
  * @link http://www.ietf.org/rfc/rfc7230.txt
  * @link http://www.ietf.org/rfc/rfc7231.txt
  */
@@ -27,8 +31,12 @@ public function getProtocolVersion();
      * 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
+     * new protocol version.
+     *
      * @param string $version HTTP protocol version
-     * @return void
+     * @return MessageInterface
      */
     public function setProtocolVersion($version);
 
@@ -95,9 +103,13 @@ public function getHeaderLines($header);
      * The header name is case-insensitive. The header values MUST be a string
      * or an array of strings.
      *
+     * 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 and/or updated header and value.
+     *
      * @param string $header Header name
      * @param string|string[] $value Header value(s).
-     * @return void
+     * @return MessageInterface
      * @throws \InvalidArgumentException for invalid header names or values.
      */
     public function setHeader($header, $value);
@@ -108,18 +120,26 @@ public function setHeader($header, $value);
      * Existing values for the specified header will be maintained. The new
      * value(s) will be appended to the existing list.
      *
+     * 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 void
+     * @return MessageInterface
      * @throws \InvalidArgumentException for invalid header names or values.
      */
     public function addHeader($header, $value);
 
     /**
      * Remove a specific header by case-insensitive name.
      *
+     * 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 void
+     * @return MessageInterface
      */
     public function removeHeader($header);
 
@@ -135,8 +155,12 @@ public function getBody();
      *
      * The body MUST be a StreamableInterface 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.
-     * @return void
+     * @return MessageInterface
      * @throws \InvalidArgumentException When the body is not valid.
      */
     public function setBody(StreamableInterface $body);

src/RequestInterface.php

@@ -5,17 +5,18 @@
 /**
  * Representation of an outgoing, client-side request.
  *
- * Per the HTTP specification, this interface includes both accessors for
- * and mutators for the following:
+ * Per the HTTP specification, this interface includes properties for
+ * each of the following:
  *
  * - Protocol version
  * - HTTP method
  * - URL
  * - Headers
  * - Message body
  *
- * As the request CAN be built iteratively, the interface allows
- * mutability of all properties.
+ * 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.
  */
 interface RequestInterface extends MessageInterface
 {
@@ -34,8 +35,12 @@ public function getMethod();
      * 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
+     * changed request method.
+     *
      * @param string $method Case-insensitive method.
-     * @return void
+     * @return RequestInterface
      * @throws \InvalidArgumentException for invalid HTTP methods.
      */
     public function setMethod($method);
@@ -78,9 +83,13 @@ public function getAbsoluteUri();
      * When setting the absolute URI, the url (see getUrl() and setUrl()) MUST
      * be updated.
      *
+     * 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
+     * changed URI and updated URL.
+     *
      * @link http://tools.ietf.org/html/rfc3986#section-4.3
      * @param string $uri Absolute request URI.
-     * @return void
+     * @return RequestInterface
      * @throws \InvalidArgumentException If the URI is invalid.
      */
     public function setAbsoluteUri($uri);
@@ -106,9 +115,13 @@ public function getUrl();
      * When setting the URL, the absolute URI (see getAbsoluteUri() and
      * setAbsoluteUri()) MUST be updated.
      *
+     * 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
+     * changed URL and updated absolute URI.
+     *
      * @link http://tools.ietf.org/html/rfc7230#section-5.3
      * @param string $url Request URL, with path and optionally query string.
-     * @return void
+     * @return RequestInterface
      * @throws \InvalidArgumentException If the URL is invalid.
      */
     public function setUrl($url);

src/ResponseInterface.php

@@ -5,16 +5,17 @@
 /**
  * Representation of an outgoing, server-side response.
  *
- * Per the HTTP specification, this interface includes both accessors for
- * and mutators for the following:
+ * Per the HTTP specification, this interface includes properties for
+ * each of the following:
  *
  * - Protocol version
  * - Status code and reason phrase
  * - Headers
  * - Message body
  *
- * As the response CAN be built iteratively, the interface allows
- * mutability of all properties.
+ * 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.
  */
 interface ResponseInterface extends MessageInterface
 {
@@ -35,12 +36,17 @@ public function getStatusCode();
      * to the RFC 7231 or IANA recommended reason phrase for the response's
      * 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
+     * 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 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
      * @throws \InvalidArgumentException For invalid status code arguments.
      */
     public function setStatus($code, $reasonPhrase = null);

src/ServerRequestInterface.php

@@ -5,8 +5,8 @@
 /**
  * Representation of an incoming, server-side HTTP request.
  *
- * Per the HTTP specification, this interface includes accessors for
- * the following:
+ * Per the HTTP specification, this interface includes properties for
+ * each of the following:
  *
  * - Protocol version
  * - HTTP method
@@ -24,16 +24,21 @@
  * - Deserialized body parameters (generally from $_POST)
  *
  * $_SERVER and $_FILES values MUST be treated as immutable, as they represent
- * application state at the time of request. The other values SHOULD be
- * mutable, as they can be restored from $_SERVER, $_FILES, or the request
- * body, and may need treatment during the application (e.g., body parameters
- * may be deserialized based on content type).
+ * application state at the time of request; as such, no methods are provided
+ * to allow modification of those values. The other values provide such methods,
+ * as they can be restored from $_SERVER, $_FILES, or the request body, and may
+ * need treatment during the application (e.g., body parameters may be
+ * deserialized based on content type).
  *
  * Additionally, this interface recognizes the utility of introspecting a
  * request to derive and match additional parameters (e.g., via URI path
  * matching, decrypting cookie values, deserializing non-form-encoded body
  * content, matching authorization headers to users, etc). These parameters
- * are stored in an "attributes" property, which MUST be mutable.
+ * are stored in an "attributes" property.
+ *
+ * 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.
  */
 interface ServerRequestInterface extends RequestInterface
 {
@@ -69,8 +74,12 @@ public function getCookieParams();
      * be compatible with the structure of $_COOKIE. Typically, this data will
      * be injected at instantiation.
      *
+     * 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 cookie values.
+     *
      * @param array $cookies Array of key/value pairs representing cookies.
-     * @return void
+     * @return ServerRequestInterface
      */
     public function setCookieParams(array $cookies);
 
@@ -102,9 +111,13 @@ public function getQueryParams();
      * Setting query string arguments MUST NOT change the URL stored by the
      * request, nor the values in the server params.
      *
+     * 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 query string arguments.
+     *
      * @param array $query Array of query string arguments, typically from
      *     $_GET.
-     * @return void
+     * @return ServerRequestInterface
      */
     public function setQueryParams(array $query);
 
@@ -143,8 +156,12 @@ public function getBodyParams();
      * a JSON payload, this method could be used to inject the deserialized
      * parameters.
      *
+     * 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 body parameters.
+     *
      * @param array $params The deserialized body parameters.
-     * @return void
+     * @return ServerRequestInterface
      */
     public function setBodyParams(array $params);
 
@@ -181,9 +198,13 @@ public function getAttribute($attribute, $default = null);
      * This method allows setting request attributes, 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.
+     *
      * @see getAttributes()
      * @param array $attributes Attributes derived from the request.
-     * @return void
+     * @return ServerRequestInterface
      */
     public function setAttributes(array $attributes);
 
@@ -193,10 +214,14 @@ public function setAttributes(array $attributes);
      * 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 attribute.
+     *
      * @see getAttributes()
      * @param string $attribute The attribute name.
      * @param mixed $value The value of the attribute.
-     * @return void
+     * @return ServerRequestInterface
      */
     public function setAttribute($attribute, $value);
 }