Clientbase
/
wellrested
mirror of https://github.com/basemaster/wellrested.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docblocks for Message namespace

This commit is contained in:
PJ Dietz 2015-04-29 21:09:05 -04:00
parent 086b09db4f
commit adf8def961
9 changed files with 222 additions and 223 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
src/Message/Message.php
View File

@ -5,6 +5,9 @@ namespace WellRESTed\Message;
use Psr\Http\Message\MessageInterface; use Psr\Http\Message\MessageInterface;
use Psr\Http\Message\StreamInterface; use Psr\Http\Message\StreamInterface;
/**
* Message defines core functionality for classes that represent HTTP messages.
*/
abstract class Message implements MessageInterface abstract class Message implements MessageInterface
{ {
/** @var HeaderCollection */ /** @var HeaderCollection */
@ -15,8 +18,19 @@ abstract class Message implements MessageInterface
protected $protcolVersion = "1.1"; protected $protcolVersion = "1.1";
/** /**
* @param array $headers * Create a new Message, optionally with headers and a body.
* @param StreamInterface $body *
* If provided, $headers MUST by an associative array with header field
* names as (string) keys and lists of header field values (string[])
* as values.
*
* If no StreamInterface is provided for $body, the instance will create
* a NullStream instance for the message body.
*
* @param array $headers Associative array of headers fields with header
* field names as keys and list arrays of field values as values
* @param StreamInterface $body A stream representation of the message
* entity body
*/ */
public function __construct(array $headers = null, StreamInterface $body = null) public function __construct(array $headers = null, StreamInterface $body = null)
{ {
@ -62,10 +76,6 @@ abstract class Message implements MessageInterface
* The version string MUST contain only the HTTP version number (e.g., * The version string MUST contain only the HTTP version number (e.g.,
* "1.1", "1.0"). * "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 * @param string $version HTTP protocol version
* @return self * @return self
*/ */
@ -77,7 +87,7 @@ abstract class Message implements MessageInterface
} }
/** /**
* Retrieves all message headers. * Retrieve all message headers.
* *
* The keys represent the header name as it will be sent over the wire, and * The keys represent the header name as it will be sent over the wire, and
* each value is an array of strings associated with the header. * each value is an array of strings associated with the header.
@ -97,8 +107,7 @@ abstract class Message implements MessageInterface
* While header names are not case-sensitive, getHeaders() will preserve the * While header names are not case-sensitive, getHeaders() will preserve the
* exact case in which headers were originally specified. * exact case in which headers were originally specified.
* *
* @return array Returns an associative array of the message's headers. Each * @return array Returns an associative array of the message's headers.
* key MUST be a header name, and each value MUST be an array of strings.
*/ */
public function getHeaders() public function getHeaders()
{ {
@ -128,13 +137,13 @@ abstract class Message implements MessageInterface
* This method returns an array of all the header values of the given * This method returns an array of all the header values of the given
* case-insensitive header name. * case-insensitive header name.
* *
* If the header does not appear in the message, this method MUST return an * If the header does not appear in the message, this method returns an
* empty array. * empty array.
* *
* @param string $name Case-insensitive header field name. * @param string $name Case-insensitive header field name.
* @return string[] An array of string values as provided for the given * @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 * header. If the header does not appear in the message, this method
* return an empty array. * returns an empty array.
*/ */
public function getHeader($name) public function getHeader($name)
{ {
@ -157,13 +166,13 @@ abstract class Message implements MessageInterface
* comma concatenation. For such headers, use getHeader() instead * comma concatenation. For such headers, use getHeader() instead
* and supply your own delimiter when concatenating. * and supply your own delimiter when concatenating.
* *
* If the header does not appear in the message, this method MUST return * If the header does not appear in the message, this method returns an
* an empty string. * empty string.
* *
* @param string $name Case-insensitive header field name. * @param string $name Case-insensitive header field name.
* @return string 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 * concatenated together using a comma. If the header does not appear in
* the message, this method MUST return an empty string. * the message, this method returns an empty string.
*/ */
public function getHeaderLine($name) public function getHeaderLine($name)
{ {
@ -181,10 +190,6 @@ abstract class Message implements MessageInterface
* While header names are case-insensitive, the casing of the header will * While header names are case-insensitive, the casing of the header will
* be preserved by this function, and returned from getHeaders(). * 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
* new and/or updated header and value.
*
* @param string $name Case-insensitive header field name. * @param string $name Case-insensitive header field name.
* @param string|string[] $value Header value(s). * @param string|string[] $value Header value(s).
* @return self * @return self
@ -193,7 +198,6 @@ abstract class Message implements MessageInterface
public function withHeader($name, $value) public function withHeader($name, $value)
{ {
$values = $this->getValidatedHeaders($name, $value); $values = $this->getValidatedHeaders($name, $value);
$message = clone $this; $message = clone $this;
unset($message->headers[$name]); unset($message->headers[$name]);
foreach ($values as $value) { foreach ($values as $value) {
@ -210,10 +214,6 @@ abstract class Message implements MessageInterface
* value(s) will be appended to the existing list. If the header did not * value(s) will be appended to the existing list. If the header did not
* exist previously, it will be added. * 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
* new header and/or value.
*
* @param string $name Case-insensitive header field name to add. * @param string $name Case-insensitive header field name to add.
* @param string|string[] $value Header value(s). * @param string|string[] $value Header value(s).
* @return self * @return self
@ -233,12 +233,6 @@ abstract class Message implements MessageInterface
/** /**
* Creates a new instance, without the specified header. * Creates a new 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
* the named header.
*
* @param string $name Case-insensitive header field name to remove. * @param string $name Case-insensitive header field name to remove.
* @return self * @return self
*/ */
@ -264,10 +258,6 @@ abstract class Message implements MessageInterface
* *
* The body MUST be a StreamInterface object. * The body MUST be a StreamInterface 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 StreamInterface $body Body. * @param StreamInterface $body Body.
* @return self * @return self
* @throws \InvalidArgumentException When the body is not valid. * @throws \InvalidArgumentException When the body is not valid.
@ -300,4 +290,3 @@ abstract class Message implements MessageInterface
} }
} }
} }

50
src/Message/NullStream.php
View File

@ -4,20 +4,16 @@ namespace WellRESTed\Message;
use Psr\Http\Message\StreamInterface; use Psr\Http\Message\StreamInterface;
/**
* NullStream is a minimal, always-empty, non-writeable stream.
*
* Use this for messages with no body.
*/
class NullStream implements StreamInterface class NullStream implements StreamInterface
{ {
/** /**
* Reads all data from the stream into a string, from the beginning to end. * Returns an empty string
* *
* This method MUST attempt to seek to the beginning of the stream before
* reading data and read the stream until the end is reached.
*
* Warning: This could attempt to load a large amount of data into memory.
*
* This method MUST NOT raise an exception in order to conform with PHP's
* string casting operations.
*
* @see http://php.net/manual/en/language.oop5.magic.php#object.tostring
* @return string * @return string
*/ */
public function __toString() public function __toString()
@ -26,7 +22,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Closes the stream and any underlying resources. * No-op
* *
* @return void * @return void
*/ */
@ -35,9 +31,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Separates any underlying resources from the stream. * No-op
*
* After the stream has been detached, the stream is in an unusable state.
* *
* @return resource|null Underlying PHP stream, if any * @return resource|null Underlying PHP stream, if any
*/ */
@ -46,7 +40,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Get the size of the stream if known * Returns 0
* *
* @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.
*/ */
@ -56,7 +50,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Returns the current position of the file read/write pointer * Returns 0
* *
* @return int|bool Position of the file pointer or false on error. * @return int|bool Position of the file pointer or false on error.
*/ */
@ -66,7 +60,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Returns true if the stream is at the end of the stream. * Returns true
* *
* @return bool * @return bool
*/ */
@ -76,7 +70,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Returns whether or not the stream is seekable. * Returns false
* *
* @return bool * @return bool
*/ */
@ -86,7 +80,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Seek to a position in the stream. * Always throws exception
* *
* @link http://www.php.net/manual/en/function.fseek.php * @link http://www.php.net/manual/en/function.fseek.php
* @param int $offset Stream offset * @param int $offset Stream offset
@ -103,10 +97,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Seek to the beginning of the stream. * Always throws exception
*
* If the stream is not seekable, this method will raise an exception;
* otherwise, it will perform a seek(0).
* *
* @see seek() * @see seek()
* @link http://www.php.net/manual/en/function.fseek.php * @link http://www.php.net/manual/en/function.fseek.php
@ -118,7 +109,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Returns whether or not the stream is writable. * Returns false.
* *
* @return bool * @return bool
*/ */
@ -128,7 +119,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Write data to the stream. * Always throws exception
* *
* @param string $string The string that is to be written. * @param string $string The string that is to be written.
* @return int Returns the number of bytes written to the stream. * @return int Returns the number of bytes written to the stream.
@ -140,7 +131,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Returns whether or not the stream is readable. * Returns true
* *
* @return bool * @return bool
*/ */
@ -150,7 +141,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Read data from the stream. * Returns an empty string
* *
* @param int $length Read up to $length bytes from the object and return * @param int $length Read up to $length bytes from the object and return
* them. Fewer than $length bytes may be returned if underlying stream * them. Fewer than $length bytes may be returned if underlying stream
@ -177,10 +168,7 @@ class NullStream implements StreamInterface
} }
/** /**
* Get stream metadata as an associative array or retrieve a specific key. * Returns null
*
* 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 * @link http://php.net/manual/en/function.stream-get-meta-data.php
* @param string $key Specific metadata to retrieve. * @param string $key Specific metadata to retrieve.

50
src/Message/Request.php
View File

@ -6,6 +6,18 @@ use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\StreamInterface; use Psr\Http\Message\StreamInterface;
use Psr\Http\Message\UriInterface; use Psr\Http\Message\UriInterface;
/**
* Representation of an outgoing, client-side request.
*
* Per the HTTP specification, this interface includes properties for
* each of the following:
*
* - Protocol version
* - HTTP method
* - URI
* - Headers
* - Message body
*/
class Request extends Message implements RequestInterface class Request extends Message implements RequestInterface
{ {
/** @var string */ /** @var string */
@ -18,6 +30,9 @@ class Request extends Message implements RequestInterface
// ------------------------------------------------------------------------ // ------------------------------------------------------------------------
/** /**
* Create a new Request.
*
* @see WellRESTed\Message\Message
* @param UriInterface $uri * @param UriInterface $uri
* @param string $method * @param string $method
* @param array $headers * @param array $headers
@ -61,7 +76,7 @@ class Request extends Message implements RequestInterface
* withRequestTarget() below). * withRequestTarget() below).
* *
* If no URI is available, and no request-target has been specifically * If no URI is available, and no request-target has been specifically
* provided, this method MUST return the string "/". * provided, this method will return the string "/".
* *
* @return string * @return string
*/ */
@ -91,10 +106,6 @@ class Request extends Message implements RequestInterface
* this method may be used to create an instance with the specified * this method may be used to create an instance with the specified
* request-target, verbatim. * 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
* changed request target.
*
* @link http://tools.ietf.org/html/rfc7230#section-2.7 (for the various * @link http://tools.ietf.org/html/rfc7230#section-2.7 (for the various
* request-target forms allowed in request messages) * request-target forms allowed in request messages)
* @param mixed $requestTarget * @param mixed $requestTarget
@ -121,13 +132,9 @@ class Request extends Message implements RequestInterface
* Create a new instance with the provided HTTP method. * Create a new instance with the provided HTTP method.
* *
* While HTTP method names are typically all uppercase characters, HTTP * While HTTP method names are typically all uppercase characters, HTTP
* method names are case-sensitive and thus implementations SHOULD NOT * method names are case-sensitive. Therefore, this method will not
* modify the given string. * 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. * @param string $method Case-insensitive method.
* @return self * @return self
* @throws \InvalidArgumentException for invalid HTTP methods. * @throws \InvalidArgumentException for invalid HTTP methods.
@ -142,11 +149,9 @@ class Request extends Message implements RequestInterface
/** /**
* Retrieves the URI instance. * Retrieves the URI instance.
* *
* This method MUST return a UriInterface instance.
*
* @link http://tools.ietf.org/html/rfc3986#section-4.3 * @link http://tools.ietf.org/html/rfc3986#section-4.3
* @return UriInterface Returns a UriInterface instance * @return UriInterface Returns a UriInterface instance
* representing the URI of the request, if any. * representing the URI of the request.
*/ */
public function getUri() public function getUri()
{ {
@ -156,22 +161,23 @@ class Request extends Message implements RequestInterface
/** /**
* Returns an instance with the provided URI. * Returns an instance with the provided URI.
* *
* This method will update the Host header of the returned request by * This method updates the Host header of the returned request by
* default if the URI contains a host component. If the URI does not * 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 will be carried
* over to the returned request. * over to the returned request.
* *
* You can opt-in to preserving the original state of the Host header by * You can opt-in to preserving the original state of the Host header by
* setting `$preserveHost` to `true`. When `$preserveHost` is set to * setting `$preserveHost` to `true`. When `$preserveHost` is set to
* `true`, the returned request will not update the Host header of the * `true`, this method interacts with the Host header in the following ways:
* 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.
* *
* This method MUST be implemented in such a way as to retain the * - If the the Host header is missing or empty, and the new URI contains
* immutability of the message, and MUST return an instance that has the * a host component, this method will update the Host header in the returned
* new UriInterface instance. * request.
* - If the Host header is missing or empty, and the new URI does not contain a
* host component, this method will not update the Host header in the returned
* request.
* - If a Host header is present and non-empty, this method will not update
* the Host header in the returned request.
* *
* @link http://tools.ietf.org/html/rfc3986#section-4.3 * @link http://tools.ietf.org/html/rfc3986#section-4.3
* @param UriInterface $uri New request URI to use. * @param UriInterface $uri New request URI to use.

54
src/Message/Response.php
View File

@ -5,21 +5,35 @@ namespace WellRESTed\Message;
use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\StreamInterface; use Psr\Http\Message\StreamInterface;
/**
* Representation of an outgoing, server-side response.
*
* Per the HTTP specification, this interface includes properties for
* each of the following:
*
* - Protocol version
* - Status code and reason phrase
* - Headers
* - Message body
*/
class Response extends Message implements ResponseInterface class Response extends Message implements ResponseInterface
{ {
/** /** @var string Text explanation of the HTTP Status Code. */
* Text explanation of the HTTP Status Code. You only need to set this if
* you are using nonstandard status codes. Otherwise, the instance will
* set the when you update the status code.
*
* @var string
*/
private $reasonPhrase; private $reasonPhrase;
/** @var int HTTP status code */ /** @var int HTTP status code */
private $statusCode; private $statusCode;
/** @var string HTTP protocol and version */
/** /**
* Create a new Response, optionally with status code, headers, and a body.
*
* If provided, $headers MUST by an associative array with header field
* names as (string) keys and lists of header field values (string[])
* as values.
*
* If no StreamInterface is provided for $body, the instance will create
* a NullStream instance for the message body.
*
* @see WellRESTed\Message\Message
* @param int $statusCode * @param int $statusCode
* @param array $headers * @param array $headers
* @param StreamInterface $body * @param StreamInterface $body
@ -35,9 +49,9 @@ class Response extends Message implements ResponseInterface
// Psr\Http\Message\ResponseInterface // Psr\Http\Message\ResponseInterface
/** /**
* Gets the response Status-Code. * Gets the response status code.
* *
* The Status-Code is a 3-digit integer result code of the server's attempt * The status code is a 3-digit integer result code of the server's attempt
* to understand and satisfy the request. * to understand and satisfy the request.
* *
* @return integer Status code. * @return integer Status code.
@ -51,15 +65,9 @@ class Response extends Message implements ResponseInterface
* Create a new instance with the specified status code, and optionally * Create a new instance with the specified status code, and optionally
* reason phrase, for the response. * reason phrase, for the response.
* *
* If no Reason-Phrase is specified, implementations MAY choose to default * If no reason phrase is specified, this method will provide a standard
* to the RFC 7231 or IANA recommended reason phrase for the response's * reason phrase, if possible.
* 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 * @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 integer $code The 3-digit integer result code to set.
* @param string $reasonPhrase The reason phrase to use with the * @param string $reasonPhrase The reason phrase to use with the
@ -80,17 +88,13 @@ class Response extends Message implements ResponseInterface
} }
/** /**
* Gets the response Reason-Phrase, a short textual description of the Status-Code. * Gets the response reason phrase, a short textual description of the status code.
* *
* Because a Reason-Phrase is not a required element in a response * The reason phrase is not required and may be an empty string.
* Status-Line, the Reason-Phrase value MAY be null. Implementations MAY
* 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://tools.ietf.org/html/rfc7231#section-6
* @link http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml * @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, or an empty string if unknown.
*/ */
public function getReasonPhrase() public function getReasonPhrase()
{ {

71
src/Message/ServerRequest.php
View File

@ -5,6 +5,34 @@ namespace WellRESTed\Message;
use Psr\Http\Message\ServerRequestInterface; use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\StreamInterface; use Psr\Http\Message\StreamInterface;
/**
* Representation of an incoming, server-side HTTP request.
*
* Per the HTTP specification, this interface includes properties for
* each of the following:
*
* - Protocol version
* - HTTP method
* - URI
* - Headers
* - Message body
*
* Additionally, it encapsulates all data as it has arrived to the
* application from the CGI and/or 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)
*
* $_SERVER values MUST be treated as immutable, as they represent 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 or the request body, and may need treatment
* during the application (e.g., body parameters may be deserialized based on
* content type).
*/
class ServerRequest extends Request implements ServerRequestInterface class ServerRequest extends Request implements ServerRequestInterface
{ {
/** @var array */ /** @var array */
@ -22,6 +50,15 @@ class ServerRequest extends Request implements ServerRequestInterface
// ------------------------------------------------------------------------ // ------------------------------------------------------------------------
/**
* Creates a new, empty representation of a server-side HTTP request.
*
* To obtain a ServerRequest representing the request sent to the server
* instantiaing the request, use the factory method
* ServerRequest::getServerRequest
*
* @see ServerRequest::getServerRequest
*/
public function __construct() public function __construct()
{ {
parent::__construct(); parent::__construct();
@ -62,9 +99,6 @@ class ServerRequest extends Request implements ServerRequestInterface
* *
* Retrieves cookies sent by the client to the server. * Retrieves cookies sent by the client to the server.
* *
* The data MUST be compatible with the structure of the $_COOKIE
* superglobal.
*
* @return array * @return array
*/ */
public function getCookieParams() public function getCookieParams()
@ -79,10 +113,6 @@ class ServerRequest extends Request implements ServerRequestInterface
* be compatible with the structure of $_COOKIE. Typically, this data will * be compatible with the structure of $_COOKIE. Typically, this data will
* be injected at instantiation. * 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. * @param array $cookies Array of key/value pairs representing cookies.
* @return self * @return self
*/ */
@ -98,10 +128,10 @@ class ServerRequest extends Request implements ServerRequestInterface
* *
* Retrieves the deserialized query string arguments, if any. * Retrieves the deserialized query string arguments, if any.
* *
* Note: the query params might not be in sync with the URL or server * Note: the query params might not be in sync with the URI or server
* params. If you need to ensure you are only getting the original * params. If you need to ensure you are only getting the original
* values, you may need to parse the composed URL or the `QUERY_STRING` * values, you may need to parse the query string from `getUri()->getQuery()`
* composed in the server params. * or from the `QUERY_STRING` server param.
* *
* @return array * @return array
*/ */
@ -124,10 +154,6 @@ class ServerRequest extends Request implements ServerRequestInterface
* Setting query string arguments MUST NOT change the URL stored by the * Setting query string arguments MUST NOT change the URL stored by the
* request, nor the values in the server params. * 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 * @param array $query Array of query string arguments, typically from
* $_GET. * $_GET.
* @return self * @return self
@ -149,7 +175,7 @@ class ServerRequest extends Request implements ServerRequestInterface
* instantiation, or MAY be injected via withUploadedFiles(). * instantiation, or MAY be injected via withUploadedFiles().
* *
* @return array An array tree of UploadedFileInterface instances; an empty * @return array An array tree of UploadedFileInterface instances; an empty
* array MUST be returned if no data is present. * array will be returned if no data is present.
*/ */
public function getUploadedFiles() public function getUploadedFiles()
{ {
@ -159,10 +185,6 @@ class ServerRequest extends Request implements ServerRequestInterface
/** /**
* Create a new instance with the specified uploaded files. * Create a new instance with the specified uploaded files.
* *
* 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 body parameters.
*
* @param array An array tree of UploadedFileInterface instances. * @param array An array tree of UploadedFileInterface instances.
* @return self * @return self
* @throws \InvalidArgumentException if an invalid structure is provided. * @throws \InvalidArgumentException if an invalid structure is provided.
@ -183,7 +205,7 @@ class ServerRequest extends Request implements ServerRequestInterface
* Retrieve any parameters provided in the request body. * Retrieve any parameters provided in the request body.
* *
* If the request Content-Type is either application/x-www-form-urlencoded * If the request Content-Type is either application/x-www-form-urlencoded
* or multipart/form-data, and the request method is POST, this method MUST * or multipart/form-data, and the request method is POST, this method will
* return the contents of $_POST. * return the contents of $_POST.
* *
* Otherwise, this method may return any results of deserializing * Otherwise, this method may return any results of deserializing
@ -217,10 +239,6 @@ class ServerRequest extends Request implements ServerRequestInterface
* is a JSON payload, this method could be used to create a request * is a JSON payload, this method could be used to create a request
* instance with the deserialized parameters. * 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
* updated body parameters.
*
* @param null|array|object $data The deserialized body data. This will * @param null|array|object $data The deserialized body data. This will
* typically be in an array or object. * typically be in an array or object.
* @return self * @return self
@ -281,10 +299,6 @@ class ServerRequest extends Request implements ServerRequestInterface
* This method allows setting a single derived request attribute as * This method allows setting a single derived request attribute as
* described in getAttributes(). * 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() * @see getAttributes()
* @param string $name The attribute name. * @param string $name The attribute name.
* @param mixed $value The value of the attribute. * @param mixed $value The value of the attribute.
@ -478,5 +492,4 @@ class ServerRequest extends Request implements ServerRequestInterface
return true; return true;
} }
} }

21
src/Message/Stream.php
View File

@ -36,14 +36,11 @@ class Stream implements StreamInterface
/** /**
* Reads all data from the stream into a string, from the beginning to end. * Reads all data from the stream into a string, from the beginning to end.
* *
* This method MUST attempt to seek to the beginning of the stream before * This method will attempt to seek to the beginning of the stream before
* reading data and read the stream until the end is reached. * reading data and read the stream until the end is reached.
* *
* Warning: This could attempt to load a large amount of data into memory. * Warning: This could attempt to load a large amount of data into memory.
* *
* This method MUST NOT raise an exception in order to conform with PHP's
* string casting operations.
*
* @see http://php.net/manual/en/language.oop5.magic.php#object.tostring * @see http://php.net/manual/en/language.oop5.magic.php#object.tostring
* @return string * @return string
*/ */
@ -53,7 +50,7 @@ class Stream implements StreamInterface
try { try {
rewind($this->resource); rewind($this->resource);
$string = $this->getContents(); $string = $this->getContents();
} catch (Exception $e) { } catch (\Exception $e) {
// Silence exceptions in order to conform with PHP's string casting operations. // Silence exceptions in order to conform with PHP's string casting operations.
} }
return $string; return $string;
@ -74,7 +71,7 @@ class Stream implements StreamInterface
* *
* After the stream has been detached, the stream is in an unusable state. * After the stream has been detached, the stream is in an unusable state.
* *
* @return resource|null Underlying PHP stream, if any * @return resource|null Underlying file-pointer handler
*/ */
public function detach() public function detach()
{ {
@ -159,13 +156,12 @@ class Stream implements StreamInterface
/** /**
* Seek to the beginning of the stream. * Seek to the beginning of the stream.
* *
* If the stream is not seekable, this method will return FALSE, indicating * If the stream is not seekable, this method will raise an exception;
* failure; otherwise, it will perform a seek(0), and return the status of * otherwise, it will perform a seek(0).
* that operation.
* *
* @see seek() * @see seek()
* @link http://www.php.net/manual/en/function.fseek.php * @link http://www.php.net/manual/en/function.fseek.php
* @return bool Returns TRUE on success or FALSE on failure. * @throws \RuntimeException on failure.
*/ */
public function rewind() public function rewind()
{ {
@ -227,8 +223,9 @@ class Stream implements StreamInterface
* @param int $length Read up to $length bytes from the object and return * @param int $length Read up to $length bytes from the object and return
* them. Fewer than $length bytes may be returned if underlying stream * them. Fewer than $length bytes may be returned if underlying stream
* call returns fewer bytes. * call returns fewer bytes.
* @return string|false Returns the data read from the stream, false if * @return string Returns the data read from the stream, or an empty string
* unable to read or if an error occurs. * if no bytes are available.
* @throws \RuntimeException if an error occurs.
*/ */
public function read($length) public function read($length)
{ {

42
src/Message/UploadedFile.php
View File

@ -5,6 +5,9 @@ namespace WellRESTed\Message;
use Psr\Http\Message\StreamInterface; use Psr\Http\Message\StreamInterface;
use Psr\Http\Message\UploadedFileInterface; use Psr\Http\Message\UploadedFileInterface;
/**
* Value object representing a file uploaded through an HTTP request.
*/
class UploadedFile implements UploadedFileInterface class UploadedFile implements UploadedFileInterface
{ {
private $clientFilename; private $clientFilename;
@ -15,6 +18,13 @@ class UploadedFile implements UploadedFileInterface
private $stream; private $stream;
private $tmpName; private $tmpName;
/**
* @param string $name
* @param string $type
* @param int $size
* @param string $tmpName
* @param int $error
*/
public function __construct($name, $type, $size, $tmpName, $error) public function __construct($name, $type, $size, $tmpName, $error)
{ {
$this->clientFilename = $name; $this->clientFilename = $name;
@ -33,13 +43,13 @@ class UploadedFile implements UploadedFileInterface
/** /**
* Retrieve a stream representing the uploaded file. * Retrieve a stream representing the uploaded file.
* *
* This method MUST return a StreamInterface instance, representing the * This method returns a StreamInterface instance, representing the
* uploaded file. The purpose of this method is to allow utilizing native PHP * uploaded file. The purpose of this method is to allow utilizing native PHP
* stream functionality to manipulate the file upload, such as * stream functionality to manipulate the file upload, such as
* stream_copy_to_stream() (though the result will need to be decorated in a * stream_copy_to_stream() (though the result will need to be decorated in a
* native PHP stream wrapper to work with such functions). * 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 will raise
* an exception. * an exception.
* *
* @return StreamInterface Stream representation of the uploaded file. * @return StreamInterface Stream representation of the uploaded file.
@ -59,19 +69,12 @@ class UploadedFile implements UploadedFileInterface
* *
* Use this method as an alternative to move_uploaded_file(). This method is * Use this method as an alternative to move_uploaded_file(). This method is
* guaranteed to work in both SAPI and non-SAPI environments. * guaranteed to work in both SAPI and non-SAPI environments.
* Implementations must determine which environment they are in, and use the
* appropriate method (move_uploaded_file(), rename(), or a stream
* operation) to perform the operation.
* *
* The original file or stream MUST be removed on completion. * The original file or stream will be removed on completion.
* *
* If this method is called more than once, any subsequent calls MUST raise * If this method is called more than once, any subsequent calls will raise
* an exception. * 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.
*
* @see http://php.net/is_uploaded_file * @see http://php.net/is_uploaded_file
* @see http://php.net/move_uploaded_file * @see http://php.net/move_uploaded_file
* @param string $path Path to which to move the uploaded file. * @param string $path Path to which to move the uploaded file.
@ -99,10 +102,6 @@ class UploadedFile implements UploadedFileInterface
/** /**
* Retrieve the file size. * Retrieve the file size.
* *
* Implementations SHOULD return the value stored in the "size" key of
* the file in the $_FILES array if available, as PHP calculates this based
* on the actual size transmitted.
*
* @return int|null The file size in bytes or null if unknown. * @return int|null The file size in bytes or null if unknown.
*/ */
public function getSize() public function getSize()
@ -113,14 +112,11 @@ class UploadedFile implements UploadedFileInterface
/** /**
* Retrieve the error associated with the uploaded file. * Retrieve the error associated with the uploaded file.
* *
* The return value MUST be one of PHP's UPLOAD_ERR_XXX constants. * The return value will be one of PHP's UPLOAD_ERR_XXX constants.
* *
* If the file was uploaded successfully, this method MUST return * If the file was uploaded successfully, this method will return
* UPLOAD_ERR_OK. * UPLOAD_ERR_OK.
* *
* Implementations SHOULD return the value stored in the "error" key of
* the file in the $_FILES array.
*
* @see http://php.net/manual/en/features.file-upload.errors.php * @see http://php.net/manual/en/features.file-upload.errors.php
* @return int One of PHP's UPLOAD_ERR_XXX constants. * @return int One of PHP's UPLOAD_ERR_XXX constants.
*/ */
@ -136,9 +132,6 @@ class UploadedFile implements UploadedFileInterface
* a malicious filename with the intention to corrupt or hack your * a malicious filename with the intention to corrupt or hack your
* application. * application.
* *
* Implementations SHOULD return the value stored in the "name" key of
* the file in the $_FILES array.
*
* @return string|null The filename sent by the client or null if none * @return string|null The filename sent by the client or null if none
* was provided. * was provided.
*/ */
@ -154,9 +147,6 @@ class UploadedFile implements UploadedFileInterface
* a malicious media type with the intention to corrupt or hack your * a malicious media type with the intention to corrupt or hack your
* application. * application.
* *
* Implementations SHOULD return the value stored in the "type" key of
* the file in the $_FILES array.
*
* @return string|null The media type sent by the client or null if none * @return string|null The media type sent by the client or null if none
* was provided. * was provided.
*/ */

38
src/Message/Uri.php
View File

@ -4,6 +4,17 @@ namespace WellRESTed\Message;
use Psr\Http\Message\UriInterface; use Psr\Http\Message\UriInterface;
/**
* Value object representing a URI.
*
* This interface is meant to represent URIs according to RFC 3986 and to
* provide methods for most common operations. Additional functionality for
* working with URIs can be provided on top of the interface or externally.
* Its primary use is for HTTP requests, but may also be used in other
* contexts.
*
* @link http://tools.ietf.org/html/rfc3986 (the URI specification)
*/
class Uri implements UriInterface class Uri implements UriInterface
{ {
const MIN_PORT = 0; const MIN_PORT = 0;
@ -38,7 +49,7 @@ class Uri implements UriInterface
$this->scheme = $parsed["scheme"]; $this->scheme = $parsed["scheme"];
} }
if (isset($parsed["host"])) { if (isset($parsed["host"])) {
$this->host = $parsed["host"]; $this->host = strtolower($parsed["host"]);
} }
if (isset($parsed["port"])) { if (isset($parsed["port"])) {
$this->port = $parsed["port"]; $this->port = $parsed["port"];
@ -65,12 +76,12 @@ class Uri implements UriInterface
/** /**
* Retrieve the scheme component of the URI. * Retrieve the scheme component of the URI.
* *
* If no scheme is present, this method MUST return an empty string. * If no scheme is present, this method will return an empty string.
* *
* The value returned MUST be normalized to lowercase, per RFC 3986 * The value returned will be normalized to lowercase, per RFC 3986
* Section 3.1. * Section 3.1.
* *
* The trailing ":" character is not part of the scheme and MUST NOT be * The trailing ":" character is not part of the scheme and will not be
* added. * added.
* *
* @see https://tools.ietf.org/html/rfc3986#section-3.1 * @see https://tools.ietf.org/html/rfc3986#section-3.1
@ -84,7 +95,7 @@ class Uri implements UriInterface
/** /**
* Retrieve the authority component of the URI. * Retrieve the authority component of the URI.
* *
* If no authority information is present, this method MUST return an empty * If no authority information is present, this method will return an empty
* string. * string.
* *
* The authority syntax of the URI is: * The authority syntax of the URI is:
@ -94,7 +105,7 @@ class Uri implements UriInterface
* </pre> * </pre>
* *
* If the port component is not set or is the standard port for the current * If the port component is not set or is the standard port for the current
* scheme, it SHOULD NOT be included. * scheme, it will not be included.
* *
* @see https://tools.ietf.org/html/rfc3986#section-3.2 * @see https://tools.ietf.org/html/rfc3986#section-3.2
* @return string The URI authority, in "[user-info@]host[:port]" format. * @return string The URI authority, in "[user-info@]host[:port]" format.
@ -109,13 +120,12 @@ class Uri implements UriInterface
// User Info // User Info
$userInfo = $this->getUserInfo(); $userInfo = $this->getUserInfo();
if ($userInfo !== "") { if ($userInfo !== "") {
$authority = $userInfo .= "@"; $authority .= $userInfo . "@";
} }
// Host // Host
$authority .= $host; $authority .= $host;
// Port: Include only if set AND non-standard. // Port: Include only if set AND non-standard.
$port = $this->getPort(); $port = $this->getPort();
if ($port !== null) { if ($port !== null) {
@ -132,15 +142,15 @@ class Uri implements UriInterface
/** /**
* Retrieve the user information component of the URI. * Retrieve the user information component of the URI.
* *
* If no user information is present, this method MUST return an empty * If no user information is present, this method will return an empty
* string. * string.
* *
* If a user is present in the URI, this will return that value; * If a user is present in the URI, this will return that value;
* additionally, if the password is also present, it will be appended to the * additionally, if the password is also present, it will be appended to the
* user value, with a colon (":") separating the values. * user value, with a colon (":") separating the values.
* *
* The trailing "@" character is not part of the user information and MUST * The trailing "@" character is not part of the user information and will
* NOT be added. * not be added.
* *
* @return string The URI user information, in "username[:password]" format. * @return string The URI user information, in "username[:password]" format.
*/ */
@ -156,9 +166,9 @@ class Uri implements UriInterface
/** /**
* Retrieve the host component of the URI. * Retrieve the host component of the URI.
* *
* If no host is present, this method MUST return an empty string. * If no host is present, this method will return an empty string.
* *
* The value returned MUST be normalized to lowercase, per RFC 3986 * The value returned will be normalized to lowercase, per RFC 3986
* Section 3.2.2. * Section 3.2.2.
* *
* @see http://tools.ietf.org/html/rfc3986#section-3.2.2 * @see http://tools.ietf.org/html/rfc3986#section-3.2.2
@ -345,7 +355,7 @@ class Uri implements UriInterface
} }
$uri = clone $this; $uri = clone $this;
$uri->host = $host; $uri->host = strtolower($host);
return $uri; return $uri;
} }

60
test/tests/unit/Message/UriTest.php
View File

@ -22,7 +22,7 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::withScheme * @covers WellRESTed\Message\Uri::withScheme
* @dataProvider schemeProvider * @dataProvider schemeProvider
* @param string $expected The expected result of getScheme * @param string $expected The expected result of getScheme
* @param string $scheme The scheme to pass to withScheme * @param string $scheme The scheme to pass to withScheme
@ -196,8 +196,8 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::getUserInfo * @covers WellRESTed\Message\Uri::getUserInfo
* @covers WellRESTed\Message\Uri::withUserInfo * @covers WellRESTed\Message\Uri::withUserInfo
* @dataProvider userInfoProvider * @dataProvider userInfoProvider
* *
* @param string $expected The combined user:password value * @param string $expected The combined user:password value
@ -235,8 +235,8 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::getHost * @covers WellRESTed\Message\Uri::getHost
* @covers WellRESTed\Message\Uri::withHost * @covers WellRESTed\Message\Uri::withHost
* @dataProvider hostProvider * @dataProvider hostProvider
* @param $expected * @param $expected
* @param $host * @param $host
@ -252,12 +252,14 @@ class UriTest extends \PHPUnit_Framework_TestCase
{ {
return [ return [
["", ""], ["", ""],
["localhost", "localhost"] ["localhost", "localhost"],
["localhost", "LOCALHOST"],
["foo.com", "FOO.com"]
]; ];
} }
/** /**
* @covers WellRESTed\Message\Uri::withHost * @covers WellRESTed\Message\Uri::withHost
* @expectedException \InvalidArgumentException * @expectedException \InvalidArgumentException
* @dataProvider invalidHostProvider * @dataProvider invalidHostProvider
* @param $host * @param $host
@ -308,8 +310,8 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::getPort * @covers WellRESTed\Message\Uri::getPort
* @covers WellRESTed\Message\Uri::withPort * @covers WellRESTed\Message\Uri::withPort
* @dataProvider portAndSchemeProvider * @dataProvider portAndSchemeProvider
* *
* @param int|null $expectedPort * @param int|null $expectedPort
@ -336,7 +338,7 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::withPort * @covers WellRESTed\Message\Uri::withPort
* @expectedException \InvalidArgumentException * @expectedException \InvalidArgumentException
* @dataProvider invalidPortProvider * @dataProvider invalidPortProvider
* @param int $port * @param int $port
@ -370,9 +372,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::getPath * @covers WellRESTed\Message\Uri::getPath
* @covers WellRESTed\Message\Uri::withPath * @covers WellRESTed\Message\Uri::withPath
* @covers WellRESTed\Message\Uri::percentEncode * @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider pathProvider * @dataProvider pathProvider
* @param $expected * @param $expected
* @param $path * @param $path
@ -385,9 +387,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::getPath * @covers WellRESTed\Message\Uri::getPath
* @covers WellRESTed\Message\Uri::withPath * @covers WellRESTed\Message\Uri::withPath
* @covers WellRESTed\Message\Uri::percentEncode * @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider pathProvider * @dataProvider pathProvider
* @param $expected * @param $expected
* @param $path * @param $path
@ -426,9 +428,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::getQuery * @covers WellRESTed\Message\Uri::getQuery
* @covers WellRESTed\Message\Uri::withQuery * @covers WellRESTed\Message\Uri::withQuery
* @covers WellRESTed\Message\Uri::percentEncode * @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider queryProvider * @dataProvider queryProvider
* @param $expected * @param $expected
* @param $query * @param $query
@ -441,9 +443,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::getQuery * @covers WellRESTed\Message\Uri::getQuery
* @covers WellRESTed\Message\Uri::withQuery * @covers WellRESTed\Message\Uri::withQuery
* @covers WellRESTed\Message\Uri::percentEncode * @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider queryProvider * @dataProvider queryProvider
* @param $expected * @param $expected
* @param $query * @param $query
@ -466,7 +468,7 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::withPath * @covers WellRESTed\Message\Uri::withPath
* @expectedException \InvalidArgumentException * @expectedException \InvalidArgumentException
* @dataProvider invalidPathProvider * @dataProvider invalidPathProvider
* @param $path * @param $path
@ -499,9 +501,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::getFragment * @covers WellRESTed\Message\Uri::getFragment
* @covers WellRESTed\Message\Uri::withFragment * @covers WellRESTed\Message\Uri::withFragment
* @covers WellRESTed\Message\Uri::percentEncode * @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider fragmentProvider * @dataProvider fragmentProvider
* @param $expected * @param $expected
* @param $fragment * @param $fragment
@ -514,9 +516,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
} }
/** /**
* @covers WellRESTed\Message\Uri::getFragment * @covers WellRESTed\Message\Uri::getFragment
* @covers WellRESTed\Message\Uri::withFragment * @covers WellRESTed\Message\Uri::withFragment
* @covers WellRESTed\Message\Uri::percentEncode * @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider fragmentProvider * @dataProvider fragmentProvider
* @param $expected * @param $expected
* @param $fragment * @param $fragment