Merge pull request #11 from weierophinney/feature/update-from-psr

Updated to latest version of proposal

Author: philsturgeon

src/IncomingRequestInterface.php

@@ -3,44 +3,76 @@
 namespace Psr\Http\Message;
 
 /**
- * An incoming (server-side) HTTP request.
+ * Representation of an incoming, server-side HTTP request.
  *
- * This interface further describes a server-side request and provides
- * accessors and mutators around common request data, including query
- * string arguments, body parameters, upload file metadata, cookies, and
- * arbitrary attributes derived from the request by the application.
+ * Per the HTTP specification, this interface includes accessors for
+ * the following:
+ *
+ * - Protocol version
+ * - HTTP method
+ * - URL
+ * - Headers
+ * - Message body
+ *
+ * Additionally, it encapsulates all data as it has arrived to the 
+ * application from the PHP environment, including:
+ *
+ * - The values represented in $_SERVER.
+ * - Any cookies provided (generally via $_COOKIE)
+ * - Query string arguments (generally via $_GET, or as parsed via parse_str())
+ * - Upload files, if any (as represented by $_FILES)
+ * - Deserialized body parameters (generally from $_POST)
+ *
+ * The above values MUST be immutable, in order to ensure that all consumers of
+ * the request instance within a given request cycle receive the same information.
+ *
+ * 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.
  */
-interface IncomingRequestInterface extends RequestInterface
+interface IncomingRequestInterface extends MessageInterface
 {
     /**
-     * Retrieve cookies.
+     * Retrieves the HTTP method of the request.
      *
-     * Retrieves cookies sent by the client to the server.
+     * @return string Returns the request method.
+     */
+    public function getMethod();
+
+    /**
+     * Retrieves the request URL.
      *
-     * The assumption is these are injected during instantiation, typically
-     * from PHP's $_COOKIE superglobal. The data IS NOT REQUIRED to come from
-     * $_COOKIE, but MUST be compatible with the structure of $_COOKIE.
+     * @link http://tools.ietf.org/html/rfc3986#section-4.3
+     * @return string Returns the URL as a string. The URL SHOULD be an absolute
+     *     URI as specified in RFC 3986, but MAY be a relative URI.
+     */
+    public function getUrl();
+
+    /**
+     * Retrieve server parameters.
      *
+     * Retrieves data related to the incoming request environment, 
+     * typically derived from PHP's $_SERVER superglobal. The data IS NOT 
+     * REQUIRED to originate from $_SERVER.
+     * 
      * @return array
      */
-    public function getCookieParams();
+    public function getServerParams();
 
     /**
-     * Set cookie parameters.
+     * Retrieve cookies.
      *
-     * Allows a library to set the cookie parameters. Use cases include
-     * libraries that implement additional security practices, such as
-     * encrypting or hashing cookie values; in such cases, they will read
-     * the original value, filter them, and re-inject into the incoming
-     * request.
+     * Retrieves cookies sent by the client to the server.
      *
-     * The value provided MUST be compatible with the structure of $_COOKIE.
+     * The assumption is these are injected during instantiation, typically
+     * from PHP's $_COOKIE superglobal. The data IS NOT REQUIRED to come from
+     * $_COOKIE, but MUST be compatible with the structure of $_COOKIE.
      *
-     * @param array $cookies Cookie values
-     * @return void
-     * @throws \InvalidArgumentException For invalid cookie parameters.
+     * @return array
      */
-    public function setCookieParams(array $cookies);
+    public function getCookieParams();
 
     /**
      * Retrieve query string arguments.
@@ -81,46 +113,59 @@ public function getFileParams();
      * PHP's $_POST superglobal. The data IS NOT REQUIRED to come from $_POST,
      * but MUST be an array.
      *
-     * In cases where the request content cannot be coerced to an array, the
-     * parent getBody() method should be used to retrieve the body content.
-     *
      * @return array The deserialized body parameters, if any.
      */
     public function getBodyParams();
 
-    /**
-     * Set the request body parameters.
-     *
-     * If the body content can be deserialized to an array, the values obtained
-     * MAY then be injected into the response using this method. This method
-     * will typically be invoked by a factory marshaling request parameters.
-     *
-     * @param array $values The deserialized body parameters, if any.
-     * @return void
-     * @throws \InvalidArgumentException For $values that cannot be accepted.
-     */
-    public function setBodyParams(array $values);
-
     /**
      * Retrieve attributes derived from the request.
      *
-     * If a router or similar is used to match against the path and/or request,
-     * this method MAY be used to retrieve the results, so long as those
-     * results can be represented as an array.
+     * The request "attributes" may be used to allow injection of any
+     * parameters derived from the request: e.g., the results of path
+     * match operations; the results of decrypting cookies; the results of
+     * deserializing non-form-encoded message bodies; etc. Attributes
+     * will be application and request specific, and CAN be mutable.
      *
      * @return array Attributes derived from the request.
      */
     public function getAttributes();
 
     /**
-     * Set attributes derived from the request
+     * Retrieve a single derived request attribute.
+     * 
+     * Retrieves a single derived request attribute as described in
+     * getAttributes(). If the attribute has not been previously set, returns
+     * the default value as provided.
+     * 
+     * @see getAttributes()
+     * @param string $attribute Attribute name.
+     * @param mixed $default Default value to return if the attribute does not exist.
+     * @return mixed
+     */
+    public function getAttribute($attribute, $default = null);
+
+    /**
+     * Set attributes derived from the request.
      *
-     * If a router or similar is used to match against the path and/or request,
-     * this method MAY be used to inject the request with the results, so long
-     * as those results can be represented as an array.
+     * This method allows setting request attributes, as described in
+     * getAttributes().
      *
+     * @see getAttributes()
      * @param array $attributes Attributes derived from the request.
      * @return void
      */
     public function setAttributes(array $attributes);
+
+    /**
+     * Set a single derived request attribute.
+     * 
+     * This method allows setting a single derived request attribute as
+     * described in getAttributes().
+     *
+     * @see getAttributes()
+     * @param string $attribute The attribute name.
+     * @param mixed $value The value of the attribute.
+     * @return void
+     */
+    public function setAttribute($attribute, $value);
 }

src/ResponseInterface.php renamed to src/IncomingResponseInterface.php

@@ -3,12 +3,20 @@
 namespace Psr\Http\Message;
 
 /**
- * An HTTP response message.
+ * Representation of an incoming, client-side response.
+ * 
+ * Per the HTTP specification, this interface includes accessors for
+ * the following:
  *
- * @link http://tools.ietf.org/html/rfc7231#section-6
- * @link http://tools.ietf.org/html/rfc7231#section-7
+ * - Protocol version
+ * - Status code and reason phrase
+ * - Headers
+ * - Message body
+ *
+ * As the response is the result of making a request, it is considered
+ * immutable.
  */
-interface ResponseInterface extends MessageInterface
+interface IncomingResponseInterface extends MessageInterface
 {
     /**
      * Gets the response Status-Code.
@@ -20,14 +28,6 @@ interface ResponseInterface extends MessageInterface
      */
     public function getStatusCode();
 
-    /**
-     * Sets the status code of this response.
-     *
-     * @param integer $code The 3-digit integer result code to set.
-     * @throws \InvalidArgumentException For invalid status code arguments.
-     */
-    public function setStatusCode($code);
-
     /**
      * Gets the response Reason-Phrase, a short textual description of the Status-Code.
      *
@@ -42,16 +42,4 @@ public function setStatusCode($code);
      * @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 7231 or IANA recommended reason phrase for the response's
-     * Status-Code.
-     *
-     * @param string $phrase The Reason-Phrase to set.
-     * @throws \InvalidArgumentException For non-string $phrase arguments.
-     */
-    public function setReasonPhrase($phrase);
 }

src/MessageInterface.php

@@ -21,36 +21,13 @@ interface MessageInterface
      */
     public function getProtocolVersion();
 
-    /**
-     * Set the HTTP protocol version.
-     *
-     * The version string MUST contain only the HTTP version number (e.g.,
-     * "1.1", "1.0").
-     *
-     * @param string $version HTTP protocol version
-     * @return void
-     */
-    public function setProtocolVersion($version);
-
     /**
      * Gets the body of the message.
      *
      * @return StreamableInterface|null Returns the body, or null if not set.
      */
     public function getBody();
 
-    /**
-     * Sets the body of the message.
-     *
-     * The body MUST be a StreamableInterface object. Setting the body to null MUST
-     * remove the existing body.
-     *
-     * @param StreamableInterface|null $body Body.
-     * @return void
-     * @throws \InvalidArgumentException When the body is not valid.
-     */
-    public function setBody(StreamableInterface $body = null);
-
     /**
      * Gets all message headers.
      *
@@ -85,12 +62,15 @@ public function getHeaders();
     public function hasHeader($header);
 
     /**
-     * Retrieve a header by the given case-insensitive name as a string.
+     * Retrieve a header by the given case-insensitive name, as a string.
      *
      * This method returns all of the header values of the given
      * case-insensitive header name as a string concatenated together using
      * a comma.
      *
+     * NOTE: Not all header values may be appropriately represented using
+     * comma concatenation.
+     *
      * @param string $header Case-insensitive header name.
      * @return string
      */
@@ -103,39 +83,4 @@ public function getHeader($header);
      * @return string[]
      */
     public function getHeaderAsArray($header);
-
-    /**
-     * Sets a 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.
-     *
-     * @param string $header Header name
-     * @param string|string[] $value Header value(s).
-     * @return void
-     * @throws \InvalidArgumentException for invalid header names or values.
-     */
-    public function setHeader($header, $value);
-
-    /**
-     * Appends a header value for the specified header.
-     *
-     * Existing values for the specified header will be maintained. The new
-     * value(s) will be appended to the existing list.
-     *
-     * @param string $header Header name to add
-     * @param string|string[] $value Header value(s).
-     * @return void
-     * @throws \InvalidArgumentException for invalid header names or values.
-     */
-    public function addHeader($header, $value);
-
-    /**
-     * Remove a specific header by case-insensitive name.
-     *
-     * @param string $header HTTP header to remove
-     * @return void
-     */
-    public function removeHeader($header);
 }