Merge pull request #43 from weierophinney/hotfix/sync-with-spec

Update to latest PSR-7 version

Author: Paul M. Jones

src/MessageInterface.php

@@ -94,8 +94,7 @@ public function hasHeader($name);
     public function getHeader($name);
 
     /**
-     * Retrieves the line for a single header, with the header values as a
-     * comma-separated string.
+     * Retrieves a comma-separated string of the values for a single header.
      *
      * This method returns all of the header values of the given
      * case-insensitive header name as a string concatenated together using
@@ -106,18 +105,17 @@ public function getHeader($name);
      * and supply your own delimiter when concatenating.
      *
      * If the header does not appear in the message, this method MUST return
-     * a null value.
+     * an empty string.
      *
      * @param string $name Case-insensitive header field name.
-     * @return string|null A string of values as provided for the given header
+     * @return string A string of values as provided for the given header
      *    concatenated together using a comma. If the header does not appear in
-     *    the message, this method MUST return a null value.
+     *    the message, this method MUST return an empty string.
      */
     public function getHeaderLine($name);
 
     /**
-     * Return an instance with the provided header, replacing any existing
-     * values of any headers with the same case-insensitive name.
+     * Return an instance with the provided value replacing the specified header.
      *
      * While header names are case-insensitive, the casing of the header will
      * be preserved by this function, and returned from getHeaders().
@@ -134,8 +132,7 @@ public function getHeaderLine($name);
     public function withHeader($name, $value);
 
     /**
-     * Return an instance with the specified header appended with the
-     * given value.
+     * 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

src/RequestInterface.php

@@ -14,70 +14,15 @@
  * - Headers
  * - Message body
  *
+ * During construction, implementations MUST attempt to set the Host header from
+ * a provided URI if no Host header is provided.
+ *
  * 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 an instance that contains the changed state.
  */
 interface RequestInterface extends MessageInterface
 {
-    /**
-     * Extends MessageInterface::getHeaders() to provide request-specific
-     * behavior.
-     *
-     * Retrieves all message headers.
-     *
-     * This method acts exactly like MessageInterface::getHeaders(), with one
-     * behavioral change: if the Host header has not been previously set, the
-     * method MUST attempt to pull the host component of the composed URI, if
-     * present.
-     *
-     * @see MessageInterface::getHeaders()
-     * @see UriInterface::getHost()
-     * @return array Returns an associative array of the message's headers. Each
-     *     key MUST be a header name, and each value MUST be an array of strings.
-     */
-    public function getHeaders();
-
-    /**
-     * Extends MessageInterface::getHeader() to provide request-specific
-     * behavior.
-     *
-     * This method acts exactly like MessageInterface::getHeader(), with
-     * one behavioral change: if the Host header is requested, but has
-     * not been previously set, the method MUST attempt to pull the host
-     * component of the composed URI, if present.
-     *
-     * @see MessageInterface::getHeader()
-     * @see UriInterface::getHost()
-     * @param string $name Case-insensitive header field name.
-     * @return string[] An array of string values as provided for the given
-     *    header. If the header does not appear in the message, this method MUST
-     *    return an empty array.
-     */
-    public function getHeader($name);
-
-    /**
-     * Extends MessageInterface::getHeaderLines() to provide request-specific
-     * behavior.
-     *
-     * This method returns all of the header values of the given
-     * case-insensitive header name as a string concatenated together using
-     * a comma.
-     *
-     * This method acts exactly like MessageInterface::getHeaderLines(), with
-     * one behavioral change: if the Host header is requested, but has
-     * not been previously set, the method MUST attempt to pull the host
-     * component of the composed URI, if present.
-     *
-     * @see MessageInterface::getHeaderLine()
-     * @see UriInterface::getHost()
-     * @param string $name Case-insensitive header field name.
-     * @return string|null A string of values as provided for the given header
-     *    concatenated together using a comma. If the header does not appear in
-     *    the message, this method MUST return a null value.
-     */
-    public function getHeaderLine($name);
-
     /**
      * Retrieves the message's request target.
      *
@@ -133,7 +78,7 @@ public function getMethod();
      * immutability of the message, and MUST return an instance that has the
      * changed request method.
      *
-     * @param string $method Case-insensitive method.
+     * @param string $method Case-sensitive method.
      * @return self
      * @throws \InvalidArgumentException for invalid HTTP methods.
      */
@@ -153,18 +98,23 @@ public function getUri();
     /**
      * Returns an instance with the provided URI.
      *
-     * This method will update the Host header of the returned request by
+     * This method MUST update the Host header of the returned request by
      * default if the URI contains a host component. If the URI does not
-     * contain a host component, any pre-existing Host header will be carried
+     * contain a host component, any pre-existing Host header MUST be carried
      * over to the returned request.
      *
      * You can opt-in to preserving the original state of the Host header by
      * setting `$preserveHost` to `true`. When `$preserveHost` is set to
-     * `true`, the returned request will not update the Host header of the
-     * returned message -- even if the message contains no Host header. This
-     * means that a call to `getHeader('Host')` on the original request MUST
-     * equal the return value of a call to `getHeader('Host')` on the returned
-     * request.
+     * `true`, this method interacts with the Host header in the following ways:
+     *
+     * - If the the Host header is missing or empty, and the new URI contains
+     *   a host component, this method MUST update the Host header in the returned
+     *   request.
+     * - If the Host header is missing or empty, and the new URI does not contain a
+     *   host component, this method MUST NOT update the Host header in the returned
+     *   request.
+     * - If a Host header is present and non-empty, this method MUST NOT update
+     *   the Host header in the returned request.
      *
      * This method MUST be implemented in such a way as to retain the
      * immutability of the message, and MUST return an instance that has the

src/ResponseInterface.php

@@ -30,8 +30,7 @@ interface ResponseInterface extends MessageInterface
     public function getStatusCode();
 
     /**
-     * Return an instance with the specified status code, and optionally
-     * reason phrase, for the response.
+     * Return an instance with the specified status code and, optionally, reason phrase.
      *
      * If no reason phrase is specified, implementations MAY choose to default
      * to the RFC 7231 or IANA recommended reason phrase for the response's
@@ -44,17 +43,16 @@ public function getStatusCode();
      * @link http://tools.ietf.org/html/rfc7231#section-6
      * @link http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
      * @param int $code The 3-digit integer result code to set.
-     * @param null|string $reasonPhrase The reason phrase to use with the
+     * @param 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 self
      * @throws \InvalidArgumentException For invalid status code arguments.
      */
-    public function withStatus($code, $reasonPhrase = null);
+    public function withStatus($code, $reasonPhrase = '');
 
     /**
-     * Gets the response reason phrase, a short textual description of the
-     * status code.
+     * Gets the response reason phrase associated with the status code.
      *
      * Because a reason phrase is not a required element in a response
      * status line, the reason phrase value MAY be null. Implementations MAY
@@ -64,7 +62,7 @@ public function withStatus($code, $reasonPhrase = null);
      *
      * @link http://tools.ietf.org/html/rfc7231#section-6
      * @link http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
-     * @return string|null Reason phrase, or null if unknown.
+     * @return string Reason phrase; must return an empty string if none present.
      */
     public function getReasonPhrase();
 }

src/ServerRequestInterface.php

@@ -72,6 +72,9 @@ public function getCookieParams();
      * be compatible with the structure of $_COOKIE. Typically, this data will
      * be injected at instantiation.
      *
+     * This method MUST NOT update the related Cookie header of the request
+     * instance, nor related 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 an instance that has the
      * updated cookie values.
@@ -241,8 +244,7 @@ public function getAttribute($name, $default = null);
     public function withAttribute($name, $value);
 
     /**
-     * Return an instance that removes the specified derived request
-     * attribute.
+     * Return an instance that removes the specified derived request attribute.
      *
      * This method allows removing a single derived request attribute as
      * described in getAttributes().

src/StreamInterface.php

@@ -44,7 +44,7 @@ public function close();
     public function detach();
 
     /**
-     * Get the size of the stream if known
+     * Get the size of the stream if known.
      *
      * @return int|null Returns the size in bytes if known, or null if unknown.
      */

src/UploadedFileInterface.php

@@ -20,7 +20,7 @@ interface UploadedFileInterface
      * stream_copy_to_stream() (though the result will need to be decorated in a
      * native PHP stream wrapper to work with such functions).
      *
-     * If the move() method has been called previously, this method MUST raise
+     * If the moveTo() method has been called previously, this method MUST raise
      * an exception.
      *
      * @return StreamInterface Stream representation of the uploaded file.
@@ -38,23 +38,30 @@ public function getStream();
      * appropriate method (move_uploaded_file(), rename(), or a stream
      * operation) to perform the operation.
      *
+     * $targetPath may be an absolute path, or a relative path. If it is a
+     * relative path, resolution should be the same as used by PHP's rename()
+     * function.
+     *
      * The original file or stream MUST be removed on completion.
      *
      * If this method is called more than once, any subsequent calls MUST raise
      * an exception.
      *
      * When used in an SAPI environment where $_FILES is populated, when writing
-     * files via move(), is_uploaded_file() and move_uploaded_file() SHOULD be
-     * use to ensure permissions and upload status are verified correctly.
+     * files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be
+     * used to ensure permissions and upload status are verified correctly.
+     *
+     * If you wish to move to a stream, use getStream(), as SAPI operations
+     * cannot guarantee writing to stream destinations.
      *
      * @see http://php.net/is_uploaded_file
      * @see http://php.net/move_uploaded_file
-     * @param string $path Path to which to move the uploaded file.
+     * @param string $targetPath Path to which to move the uploaded file.
      * @throws \InvalidArgumentException if the $path specified is invalid.
      * @throws \RuntimeException on any error during the move operation, or on
      *     the second or subsequent call to the method.
      */
-    public function move($path);
+    public function moveTo($targetPath);
 
     /**
      * Retrieve the file size.

src/UriInterface.php

@@ -249,6 +249,11 @@ public function withPort($port);
      * rootless (not starting with a slash). Implementations MUST support all
      * three syntaxes.
      *
+     * If the path is intended to be domain-relative rather than path relative then
+     * it must begin with a slash ("/"). Paths not starting with a slash ("/")
+     * are assumed to be relative to some base path known to the application or
+     * consumer.
+     *
      * Users can provide both encoded and decoded path characters.
      * Implementations ensure the correct encoding as outlined in getPath().
      *