Skip to content

[PSR-7] Clarify requirement for new instances #482

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 7, 2015
Merged

[PSR-7] Clarify requirement for new instances #482

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
44b535d
Added errata section for immutability vs return $this
weierophinney Mar 31, 2015
c07a468
Move errata into design decision
weierophinney Apr 1, 2015
65e1160
New version of clarification: allow return $this
weierophinney Apr 1, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion proposed/http-message-meta.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -324,6 +324,19 @@ The above combines assignment and notification in a single call.
This practice has a side benefit of making explicit any changes to application
state being made.

### New instances vs returning $this

One observation made on the various `with*()` methods is that they can likely
safely `return $this;` if the argument presented will not result in a change in
the value. One rationale for doing so is performance (as this will not result in
a cloning operation).

The various interfaces have been written with verbiage indicating that
immutability MUST be preserved, but only indicate that "an instance" must be
returned containing the new state. Since instances that represent the same value
are considered equal, returning `$this` is functionally equivalent, and thus
allowed.

### Using streams instead of X

`MessageInterface` uses a body value that must implement `StreamableInterface`. This
Expand Down Expand Up @@ -615,6 +628,6 @@ used to populate the headers of an HTTP message.

* Michael Dowling
* Larry Garfield
* Evert Pot
* Phil Sturgeon
* Chris Wilkinson
* Evert Pot
92 changes: 46 additions & 46 deletions proposed/http-message.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -315,7 +315,7 @@ namespace Psr\Http\Message;
*
* 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
Expand All @@ -332,13 +332,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
Expand Down Expand Up @@ -413,14 +413,14 @@ interface MessageInterface
public function getHeaderLines($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.
Expand All @@ -431,15 +431,15 @@ interface MessageInterface
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.
Expand All @@ -450,12 +450,12 @@ interface MessageInterface
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.
Expand All @@ -471,7 +471,7 @@ interface MessageInterface
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.
*
Expand Down Expand Up @@ -508,7 +508,7 @@ namespace Psr\Http\Message;
*
* 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
{
Expand Down Expand Up @@ -583,15 +583,15 @@ interface RequestInterface extends MessageInterface
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
Expand All @@ -609,14 +609,14 @@ interface RequestInterface extends MessageInterface
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.
Expand All @@ -637,10 +637,10 @@ interface RequestInterface extends MessageInterface
public function getUri();

/**
* Create a new instance with the provided URI.
* Return an instance with the provided URI.
*
* 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
Expand Down Expand Up @@ -694,7 +694,7 @@ namespace Psr\Http\Message;
*
* 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 ServerRequestInterface extends RequestInterface
{
Expand Down Expand Up @@ -722,14 +722,14 @@ interface ServerRequestInterface extends RequestInterface
public function getCookieParams();

/**
* Create a new instance with the specified cookies.
* Return an 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
* 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
* immutability of the message, and MUST return an instance that has the
* updated cookie values.
*
* @param array $cookies Array of key/value pairs representing cookies.
Expand All @@ -752,7 +752,7 @@ interface ServerRequestInterface extends RequestInterface
public function getQueryParams();

/**
* Create a new instance with the specified query string arguments.
* Return an 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
Expand All @@ -766,7 +766,7 @@ interface ServerRequestInterface extends RequestInterface
* 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
* immutability of the message, and MUST return an instance that has the
* updated query string arguments.
*
* @param array $query Array of query string arguments, typically from
Expand Down Expand Up @@ -807,7 +807,7 @@ interface ServerRequestInterface extends RequestInterface
public function getParsedBody();

/**
* Create a new instance with the specified body parameters.
* Return an instance with the specified body parameters.
*
* These MAY be injected during instantiation.
*
Expand All @@ -825,7 +825,7 @@ interface ServerRequestInterface extends RequestInterface
* instance with 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
* immutability of the message, and MUST return an instance that has the
* updated body parameters.
*
* @param null|array|object $data The deserialized body data. This will
Expand Down Expand Up @@ -865,13 +865,13 @@ interface ServerRequestInterface extends RequestInterface
public function getAttribute($name, $default = null);

/**
* Create a new instance with the specified derived request attribute.
* Return an instance with the specified derived request attribute.
*
* 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
* immutability of the message, and MUST return an instance that has the
* updated attribute.
*
* @see getAttributes()
Expand All @@ -882,14 +882,14 @@ interface ServerRequestInterface extends RequestInterface
public function withAttribute($name, $value);

/**
* Create a new instance that removes the specified derived request
* Return an instance that removes the specified derived request
* attribute.
*
* 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 removes
* immutability of the message, and MUST return an instance that removes
* the attribute.
*
* @see getAttributes()
Expand Down Expand Up @@ -920,7 +920,7 @@ namespace Psr\Http\Message;
*
* 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
{
Expand All @@ -935,15 +935,15 @@ interface ResponseInterface extends MessageInterface
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
* 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
* 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
Expand Down Expand Up @@ -1144,7 +1144,7 @@ namespace Psr\Http\Message;
*
* Instances of this interface are considered immutable; all methods that
* might change state MUST be implemented such that they retain the internal
* state of the current instance and return a new instance that contains the
* state of the current instance and return an instance that contains the
* changed state.
*
* Typically the Host header will be also be present in the request message.
Expand Down Expand Up @@ -1265,10 +1265,10 @@ interface UriInterface
public function getFragment();

/**
* Create a new instance with the specified scheme.
* Return an instance with the specified scheme.
*
* This method MUST retain the state of the current instance, and return
* a new instance that contains the specified scheme. If the scheme
* an instance that contains the specified scheme. If the scheme
* provided includes the "://" delimiter, it MUST be removed.
*
* Implementations SHOULD restrict values to "http", "https", or an empty
Expand All @@ -1283,10 +1283,10 @@ interface UriInterface
public function withScheme($scheme);

/**
* Create a new instance with the specified user information.
* Return an instance with the specified user information.
*
* This method MUST retain the state of the current instance, and return
* a new instance that contains the specified user information.
* an instance that contains the specified user information.
*
* Password is optional, but the user information MUST include the
* user; an empty string for the user is equivalent to removing user
Expand All @@ -1299,10 +1299,10 @@ interface UriInterface
public function withUserInfo($user, $password = null);

/**
* Create a new instance with the specified host.
* Return an instance with the specified host.
*
* This method MUST retain the state of the current instance, and return
* a new instance that contains the specified host.
* an instance that contains the specified host.
*
* An empty host value is equivalent to removing the host.
*
Expand All @@ -1313,10 +1313,10 @@ interface UriInterface
public function withHost($host);

/**
* Create a new instance with the specified port.
* Return an instance with the specified port.
*
* This method MUST retain the state of the current instance, and return
* a new instance that contains the specified port.
* an instance that contains the specified port.
*
* Implementations MUST raise an exception for ports outside the
* established TCP and UDP port ranges.
Expand All @@ -1332,10 +1332,10 @@ interface UriInterface
public function withPort($port);

/**
* Create a new instance with the specified path.
* Return an instance with the specified path.
*
* This method MUST retain the state of the current instance, and return
* a new instance that contains the specified path.
* an instance that contains the specified path.
*
* The path MUST be prefixed with "/"; if not, the implementation MAY
* provide the prefix itself.
Expand All @@ -1353,10 +1353,10 @@ interface UriInterface
public function withPath($path);

/**
* Create a new instance with the specified query string.
* Return an instance with the specified query string.
*
* This method MUST retain the state of the current instance, and return
* a new instance that contains the specified query string.
* an instance that contains the specified query string.
*
* If the query string is prefixed by "?", that character MUST be removed.
* Additionally, the query string SHOULD be parseable by parse_str() in
Expand All @@ -1375,10 +1375,10 @@ interface UriInterface
public function withQuery($query);

/**
* Create a new instance with the specified URI fragment.
* Return an instance with the specified URI fragment.
*
* This method MUST retain the state of the current instance, and return
* a new instance that contains the specified URI fragment.
* an instance that contains the specified URI fragment.
*
* If the fragment is prefixed by "#", that character MUST be removed.
*
Expand Down