From a5f5432693acb062cee4c2435ac3fb42540ef684 Mon Sep 17 00:00:00 2001 From: Matthew Weier O'Phinney Date: Fri, 17 Oct 2014 08:41:11 -0500 Subject: [PATCH] Updated to php-fig/fig-standards@476606bb --- src/IncomingRequestInterface.php | 99 ++++++++++++++------------------ src/MessageInterface.php | 67 ++++++--------------- src/RequestInterface.php | 21 ++++--- src/ResponseInterface.php | 20 +++++-- src/StreamableInterface.php | 28 ++++----- 5 files changed, 102 insertions(+), 133 deletions(-) diff --git a/src/IncomingRequestInterface.php b/src/IncomingRequestInterface.php index cd873ee..0efe918 100644 --- a/src/IncomingRequestInterface.php +++ b/src/IncomingRequestInterface.php @@ -6,9 +6,9 @@ * An incoming (server-side) HTTP request. * * This interface further describes a server-side request and provides - * accessors and mutators around common request data, such as query + * accessors and mutators around common request data, including query * string arguments, body parameters, upload file metadata, cookies, and - * matched routing parameters. + * arbitrary attributes derived from the request by the application. */ interface IncomingRequestInterface extends RequestInterface { @@ -18,13 +18,10 @@ interface IncomingRequestInterface extends RequestInterface * Retrieves cookies sent by the client to the server. * * The assumption is these are injected during instantiation, typically - * from PHP's $_COOKIE superglobal, and should remain immutable over the - * course of the incoming request. + * from PHP's $_COOKIE superglobal. The data IS NOT REQUIRED to come from + * $_COOKIE, but MUST be compatible with the structure of $_COOKIE. * - * The return value can be either an array or an object that acts like - * an array (e.g., implements ArrayAccess, or an ArrayObject). - * - * @return array|\ArrayAccess + * @return array */ public function getCookieParams(); @@ -35,28 +32,28 @@ public function getCookieParams(); * 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.. - * - * The value provided should be an array or array-like object - * (e.g., implements ArrayAccess, or an ArrayObject). + * request. * - * @param array|\ArrayAccess $cookies Cookie values/structs + * The value provided MUST be compatible with the structure of $_COOKIE. * + * @param array $cookies Cookie values * @return void + * @throws \InvalidArgumentException For invalid cookie parameters. */ - public function setCookieParams($cookies); + public function setCookieParams(array $cookies); /** * Retrieve query string arguments. * * Retrieves the deserialized query string arguments, if any. * - * The assumption is these are injected during instantiation, typically - * from PHP's $_GET superglobal, and should remain immutable over the - * course of the incoming request. - * - * The return value can be either an array or an object that acts like - * an array (e.g., implements ArrayAccess, or an ArrayObject). + * These values SHOULD remain immutable over the course of the incoming + * request. They MAY be injected during instantiation, such as from PHP's + * $_GET superglobal, or MAY be derived from some other value such as the + * URI. In cases where the arguments are parsed from the URI, the data + * MUST be compatible with what PHP's `parse_str()` would return for + * purposes of how duplicate query parameters are handled, and how nested + * sets are handled. * * @return array */ @@ -65,15 +62,12 @@ public function getQueryParams(); /** * Retrieve the upload file metadata. * - * This method should return file upload metadata in the same structure + * This method MUST return file upload metadata in the same structure * as PHP's $_FILES superglobal. * - * The assumption is these are injected during instantiation, typically - * from PHP's $_FILES superglobal, and should remain immutable over the - * course of the incoming request. - * - * The return value can be either an array or an object that acts like - * an array (e.g., implements ArrayAccess, or an ArrayObject). + * These values SHOULD remain immutable over the course of the incoming + * request. They MAY be injected during instantiation, such as from PHP's + * $_FILES superglobal, or MAY be derived from other sources. * * @return array Upload file(s) metadata, if any. */ @@ -82,56 +76,51 @@ public function getFileParams(); /** * Retrieve any parameters provided in the request body. * - * If the request body can be deserialized, and if the deserialized values - * can be represented as an array or object, this method can be used to - * retrieve them. + * If the request body can be deserialized to an array, this method MAY be + * used to retrieve them. These MAY be injected during instantiation from + * PHP's $_POST superglobal. The data IS NOT REQUIRED to come from $_POST, + * but MUST be an array. * - * In other cases, the parent getBody() method should be used to retrieve - * the body content. + * 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|object The deserialized body parameters, if any. These may - * be either an array or an object, though an array or - * array-like object is recommended. + * @return array The deserialized body parameters, if any. */ public function getBodyParams(); /** * Set the request body parameters. * - * If the body content can be deserialized, 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|object $values The deserialized body parameters, if any. - * These may be either an array or an object, - * though an array or array-like object is - * recommended. + * 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($values); + public function setBodyParams(array $values); /** - * Retrieve parameters matched during routing. + * Retrieve attributes derived from the request. * * If a router or similar is used to match against the path and/or request, - * this method can be used to retrieve the results, so long as those - * results can be represented as an array or array-like object. + * this method MAY be used to retrieve the results, so long as those + * results can be represented as an array. * - * @return array|\ArrayAccess Path parameters matched by routing + * @return array Attributes derived from the request. */ - public function getPathParams(); + public function getAttributes(); /** - * Set parameters discovered by matching that path + * Set attributes derived from the request * * If a router or similar is used to match against the path and/or request, - * this method can be used to inject the request with the results, so long - * as those results can be represented as an array or array-like object. - * - * @param array|\ArrayAccess $values Path parameters matched by routing + * this method MAY be used to inject the request with the results, so long + * as those results can be represented as an array. * + * @param array $attributes Attributes derived from the request. * @return void */ - public function setPathParams(array $values); + public function setAttributes(array $attributes); } diff --git a/src/MessageInterface.php b/src/MessageInterface.php index 9b3887d..4082916 100644 --- a/src/MessageInterface.php +++ b/src/MessageInterface.php @@ -4,7 +4,11 @@ /** * HTTP messages consist of requests from a client to a server and responses - * from a server to a client. + * from a server to a client. This interface defines the methods common to + * each. + * + * @link http://www.ietf.org/rfc/rfc7230.txt + * @link http://www.ietf.org/rfc/rfc7231.txt */ interface MessageInterface { @@ -24,7 +28,6 @@ public function getProtocolVersion(); * "1.1", "1.0"). * * @param string $version HTTP protocol version - * * @return void */ public function setProtocolVersion($version); @@ -43,9 +46,7 @@ public function getBody(); * 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); @@ -61,7 +62,15 @@ public function setBody(StreamableInterface $body = null); * echo $name . ": " . implode(", ", $values); * } * - * @return array Returns an associative array of the message's headers. + * // Emit headers iteratively: + * foreach ($message->getHeaders() as $name => $values) { + * foreach ($values as $value) { + * header(sprintf('%s: %s', $name, $value), false); + * } + * } + * + * @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(); @@ -69,7 +78,6 @@ public function getHeaders(); * Checks if a header exists by the given case-insensitive name. * * @param string $header Case-insensitive header name. - * * @return bool Returns true if any header names match the given header * name using a case-insensitive string comparison. Returns false if * no matching header name is found in the message. @@ -84,7 +92,6 @@ public function hasHeader($header); * a comma. * * @param string $header Case-insensitive header name. - * * @return string */ public function getHeader($header); @@ -93,7 +100,6 @@ public function getHeader($header); * Retrieves a header by the given case-insensitive name as an array of strings. * * @param string $header Case-insensitive header name. - * * @return string[] */ public function getHeaderAsArray($header); @@ -106,64 +112,29 @@ public function getHeaderAsArray($header); * or an array of strings. * * @param string $header Header name - * @param string|string[]|object|object[] $value Header value(s). Values may - * be objects as long as they - * can be cast to strings. - * + * @param string|string[] $value Header value(s). * @return void + * @throws \InvalidArgumentException for invalid header names or values. */ public function setHeader($header, $value); - /** - * Sets headers, replacing any headers that have already been set on the message. - * - * The array keys MUST be a string. Each array value MUST be either a string - * or object, or array of strings and/or objects; any object used as a - * header value MUST be able to be cast to a string. - * - * @param array $headers Headers to set. - * - * @return void - */ - public function setHeaders(array $headers); - /** * Appends a header value for the specified header. * * Existing values for the specified header will be maintained. The new - * value will be appended to the existing list. + * value(s) will be appended to the existing list. * * @param string $header Header name to add - * @param string|object $value Value of the header; object is allowed if it - * can be cast to a string. - * + * @param string|string[] $value Header value(s). * @return void + * @throws \InvalidArgumentException for invalid header names or values. */ public function addHeader($header, $value); - /** - * Merges in an associative array of headers. - * - * Each array key MUST be a string representing the case-insensitive name - * of a header. Each value MUST be either a string or object, or array of - * strings and/or objects; any object used as a header value MUST be able - * to be cast to a string. - * - * For each value, the value is appended to any existing header of the same - * name, or, if a header does not already exist by the given name, then the - * header is added. - * - * @param array $headers Associative array of headers to add to the message - * - * @return void - */ - public function addHeaders(array $headers); - /** * Remove a specific header by case-insensitive name. * * @param string $header HTTP header to remove - * * @return void */ public function removeHeader($header); diff --git a/src/RequestInterface.php b/src/RequestInterface.php index d6e7b7c..2c2d464 100644 --- a/src/RequestInterface.php +++ b/src/RequestInterface.php @@ -3,39 +3,40 @@ namespace Psr\Http\Message; /** - * A HTTP request message. - * @link http://tools.ietf.org/html/rfc2616#section-5 + * An HTTP request message. + * + * @link http://tools.ietf.org/html/rfc7230#section-3 */ interface RequestInterface extends MessageInterface { /** - * Gets the HTTP method of the request. + * Retrieves the HTTP method of the request. * * @return string Returns the request method. */ public function getMethod(); /** - * Sets the method to be performed on the resource identified by the Request-URI. + * Sets the HTTP method to be performed 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 * modify the given string. * * @param string $method Case-insensitive method. - * * @return void + * @throws \InvalidArgumentException for invalid HTTP methods. */ public function setMethod($method); /** - * Gets the absolute request URL. + * Retrieves the absolute request URL. * + * @link http://tools.ietf.org/html/rfc3986#section-4.3 * @return string|object Returns the URL as a string, or an object that * implements the `__toString()` method. The URL must be an absolute URI * as specified in RFC 3986. - * - * @link http://tools.ietf.org/html/rfc3986#section-4.3 */ public function getUrl(); @@ -46,12 +47,10 @@ public function getUrl(); * `__toString()` method. The URL must be an absolute URI as specified * in RFC 3986. * + * @link http://tools.ietf.org/html/rfc3986#section-4.3 * @param string|object $url Request URL. - * * @return void - * * @throws \InvalidArgumentException If the URL is invalid. - * @link http://tools.ietf.org/html/rfc3986#section-4.3 */ public function setUrl($url); } diff --git a/src/ResponseInterface.php b/src/ResponseInterface.php index baf2eaa..3cbb9b4 100644 --- a/src/ResponseInterface.php +++ b/src/ResponseInterface.php @@ -3,8 +3,10 @@ namespace Psr\Http\Message; /** - * A HTTP response message. - * @link http://tools.ietf.org/html/rfc2616#section-6 + * An HTTP response message. + * + * @link http://tools.ietf.org/html/rfc7231#section-6 + * @link http://tools.ietf.org/html/rfc7231#section-7 */ interface ResponseInterface extends MessageInterface { @@ -22,17 +24,21 @@ 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. * - * Because a Reason-Phrase is not a required element in response + * Because a Reason-Phrase is not a required element in a response * Status-Line, the Reason-Phrase value MAY be null. Implementations MAY - * choose to return the default RFC 2616 recommended reason phrase for the - * response's Status-Code. + * choose to return the default RFC 7231 recommended reason phrase (or those + * listed in the IANA HTTP Status Code Registry) for the response's + * Status-Code. * + * @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. */ public function getReasonPhrase(); @@ -41,9 +47,11 @@ public function getReasonPhrase(); * Sets the Reason-Phrase of the response. * * If no Reason-Phrase is specified, implementations MAY choose to default - * to the RFC 2616 recommended reason phrase for the response's Status-Code. + * 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); } diff --git a/src/StreamableInterface.php b/src/StreamableInterface.php index 491dee1..463180e 100644 --- a/src/StreamableInterface.php +++ b/src/StreamableInterface.php @@ -3,7 +3,7 @@ namespace Psr\Http\Message; /** - * Describes streamable content. + * Describes streamable message body content. * * Typically, an instance will wrap a PHP stream; this interface provides * a wrapper around the most common operations, including serialization of @@ -50,21 +50,25 @@ public function detach(); * Any internal state such as caching of cursor position should be reset * when attach() is called, as the stream has changed. * + * @param string|resource $stream The underlying stream. String values + * SHOULD be used to create a stream + * resource. * @return void + * @throws \InvalidArgumentException For invalid $stream arguments. */ public function attach($stream); /** * Get the size of the stream if known * - * @return int|null Returns the size in bytes if known, or null if unknown + * @return int|null Returns the size in bytes if known, or null if unknown. */ public function getSize(); /** * Returns the current position of the file read/write pointer * - * @return int|bool Position of the file pointer or false on error + * @return int|bool Position of the file pointer or false on error. */ public function tell(); @@ -76,15 +80,16 @@ public function tell(); public function eof(); /** - * Returns whether or not the stream is seekable + * Returns whether or not the stream is seekable. * * @return bool */ public function isSeekable(); /** - * Seek to a position in the stream + * Seek to a position in the stream. * + * @link http://www.php.net/manual/en/function.fseek.php * @param int $offset Stream offset * @param int $whence Specifies how the cursor position will be calculated * based on the seek offset. Valid values are identical @@ -93,13 +98,12 @@ public function isSeekable(); * SEEK_CUR: Set position to current location plus offset * SEEK_END: Set position to end-of-stream plus offset * - * @return bool Returns TRUE on success or FALSE on failure - * @link http://www.php.net/manual/en/function.fseek.php + * @return bool Returns TRUE on success or FALSE on failure. */ public function seek($offset, $whence = SEEK_SET); /** - * Returns whether or not the stream is writable + * Returns whether or not the stream is writable. * * @return bool */ @@ -116,19 +120,18 @@ public function isWritable(); public function write($string); /** - * Returns whether or not the stream is readable + * Returns whether or not the stream is readable. * * @return bool */ public function isReadable(); /** - * Read data from the stream + * Read data from the stream. * * @param int $length Read up to $length bytes from the object and return * them. Fewer than $length bytes may be returned if * underlying stream call returns fewer bytes. - * * @return string|false Returns the data read from the stream, false if * unable to read or if an error occurs. */ @@ -147,13 +150,12 @@ public function getContents(); * The keys returned are identical to the keys returned from PHP's * stream_get_meta_data() function. * + * @link http://php.net/manual/en/function.stream-get-meta-data.php * @param string $key Specific metadata to retrieve. - * * @return array|mixed|null Returns an associative array if no key is * provided. Returns a specific key value if a key * is provided and the value is found, or null if * the key is not found. - * @see http://php.net/manual/en/function.stream-get-meta-data.php */ public function getMetadata($key = null); }