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\StreamInterface;
/**
* Message defines core functionality for classes that represent HTTP messages.
*/
abstract class Message implements MessageInterface
{
/** @var HeaderCollection */
@ -15,8 +18,19 @@ abstract class Message implements MessageInterface
protected $protcolVersion = "1.1";
/**
* @param array $headers
* @param StreamInterface $body
* Create a new Message, optionally with 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.
*
* @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)
{
@ -62,10 +76,6 @@ abstract class Message implements MessageInterface
* The version string MUST contain only the HTTP version number (e.g.,
* "1.1", "1.0").
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return a new instance that has the
* new protocol version.
*
* @param string $version HTTP protocol version
* @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
* 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
* exact case in which headers were originally specified.
*
* @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.
* @return array Returns an associative array of the message's headers.
*/
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
* 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.
*
* @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.
* header. If the header does not appear in the message, this method
* returns an empty array.
*/
public function getHeader($name)
{
@ -157,13 +166,13 @@ abstract class Message implements MessageInterface
* comma concatenation. For such headers, use getHeader() instead
* and supply your own delimiter when concatenating.
*
* If the header does not appear in the message, this method MUST return
* an empty string.
* If the header does not appear in the message, this method returns an
* empty string.
*
* @param string $name Case-insensitive header field name.
* @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 an empty string.
* the message, this method returns an empty string.
*/
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
* 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|string[] $value Header value(s).
* @return self
@ -193,7 +198,6 @@ abstract class Message implements MessageInterface
public function withHeader($name, $value)
{
$values = $this->getValidatedHeaders($name, $value);
$message = clone $this;
unset($message->headers[$name]);
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
* 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|string[] $value Header value(s).
* @return self
@ -233,12 +233,6 @@ abstract class Message implements MessageInterface
/**
* 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.
* @return self
*/
@ -264,10 +258,6 @@ abstract class Message implements MessageInterface
*
* 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.
* @return self
* @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;
/**
* NullStream is a minimal, always-empty, non-writeable stream.
*
* Use this for messages with no body.
*/
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
*/
public function __toString()
@ -26,7 +22,7 @@ class NullStream implements StreamInterface
}
/**
* Closes the stream and any underlying resources.
* No-op
*
* @return void
*/
@ -35,9 +31,7 @@ class NullStream implements StreamInterface
}
/**
* Separates any underlying resources from the stream.
*
* After the stream has been detached, the stream is in an unusable state.
* No-op
*
* @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.
*/
@ -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.
*/
@ -66,7 +60,7 @@ class NullStream implements StreamInterface
}
/**
* Returns true if the stream is at the end of the stream.
* Returns true
*
* @return bool
*/
@ -76,7 +70,7 @@ class NullStream implements StreamInterface
}
/**
* Returns whether or not the stream is seekable.
* Returns false
*
* @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
* @param int $offset Stream offset
@ -103,10 +97,7 @@ class NullStream implements StreamInterface
}
/**
* Seek to the beginning of the stream.
*
* If the stream is not seekable, this method will raise an exception;
* otherwise, it will perform a seek(0).
* Always throws exception
*
* @see seek()
* @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
*/
@ -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.
* @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
*/
@ -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
* 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.
*
* The keys returned are identical to the keys returned from PHP's
* stream_get_meta_data() function.
* Returns null
*
* @link http://php.net/manual/en/function.stream-get-meta-data.php
* @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\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
{
/** @var string */
@ -18,6 +30,9 @@ class Request extends Message implements RequestInterface
// ------------------------------------------------------------------------
/**
* Create a new Request.
*
* @see WellRESTed\Message\Message
* @param UriInterface $uri
* @param string $method
* @param array $headers
@ -61,7 +76,7 @@ class Request extends Message implements RequestInterface
* withRequestTarget() below).
*
* 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
*/
@ -91,10 +106,6 @@ class Request extends Message implements RequestInterface
* this method may be used to create an instance with the specified
* request-target, verbatim.
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return a new instance that has the
* changed request target.
*
* @link http://tools.ietf.org/html/rfc7230#section-2.7 (for the various
* request-target forms allowed in request messages)
* @param mixed $requestTarget
@ -121,13 +132,9 @@ class Request extends Message implements RequestInterface
* Create a new instance with the provided HTTP method.
*
* While HTTP method names are typically all uppercase characters, HTTP
* method names are case-sensitive and thus implementations SHOULD NOT
* method names are case-sensitive. Therefore, this method will not
* modify the given string.
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return a new instance that has the
* changed request method.
*
* @param string $method Case-insensitive method.
* @return self
* @throws \InvalidArgumentException for invalid HTTP methods.
@ -142,11 +149,9 @@ class Request extends Message implements RequestInterface
/**
* Retrieves the URI instance.
*
* This method MUST return a UriInterface instance.
*
* @link http://tools.ietf.org/html/rfc3986#section-4.3
* @return UriInterface Returns a UriInterface instance
* representing the URI of the request, if any.
* representing the URI of the request.
*/
public function getUri()
{
@ -156,22 +161,23 @@ class Request extends Message implements RequestInterface
/**
* 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
* contain a host component, any pre-existing Host header will 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:
*
* 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
* new UriInterface instance.
* - If the the Host header is missing or empty, and the new URI contains
* a host component, this method will 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 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
* @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\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
{
/**
* 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
*/
/** @var string Text explanation of the HTTP Status Code. */
private $reasonPhrase;
/** @var int HTTP status code */
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 array $headers
* @param StreamInterface $body
@ -35,9 +49,9 @@ class Response extends Message implements 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.
*
* @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
* reason phrase, for the response.
*
* If no Reason-Phrase is specified, implementations MAY choose to default
* to the RFC 7231 or IANA recommended reason phrase for the response's
* Status-Code.
* If no reason phrase is specified, this method will provide a standard
* reason phrase, if possible.
*
* 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
* @param integer $code The 3-digit integer result code to set.
* @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
* 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.
* The reason phrase is not required and may be an empty string.
*
* @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, or an empty string if unknown.
*/
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\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
{
/** @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()
{
parent::__construct();
@ -62,9 +99,6 @@ class ServerRequest extends Request implements ServerRequestInterface
*
* Retrieves cookies sent by the client to the server.
*
* The data MUST be compatible with the structure of the $_COOKIE
* superglobal.
*
* @return array
*/
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 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.
* @return self
*/
@ -98,10 +128,10 @@ class ServerRequest extends Request implements ServerRequestInterface
*
* 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
* values, you may need to parse the composed URL or the `QUERY_STRING`
* composed in the server params.
* values, you may need to parse the query string from `getUri()->getQuery()`
* or from the `QUERY_STRING` server param.
*
* @return array
*/
@ -124,10 +154,6 @@ class ServerRequest extends Request implements ServerRequestInterface
* Setting query string arguments MUST NOT change the URL stored by the
* 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
* $_GET.
* @return self
@ -149,7 +175,7 @@ class ServerRequest extends Request implements ServerRequestInterface
* instantiation, or MAY be injected via withUploadedFiles().
*
* @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()
{
@ -159,10 +185,6 @@ class ServerRequest extends Request implements ServerRequestInterface
/**
* 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.
* @return self
* @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.
*
* 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.
*
* 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
* 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
* typically be in an array or object.
* @return self
@ -281,10 +299,6 @@ class ServerRequest extends Request implements ServerRequestInterface
* This method allows setting a single derived request attribute as
* described in getAttributes().
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return a new instance that has the
* updated attribute.
*
* @see getAttributes()
* @param string $name The attribute name.
* @param mixed $value The value of the attribute.
@ -478,5 +492,4 @@ class ServerRequest extends Request implements ServerRequestInterface
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.
*
* 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.
*
* 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
*/
@ -53,7 +50,7 @@ class Stream implements StreamInterface
try {
rewind($this->resource);
$string = $this->getContents();
} catch (Exception $e) {
} catch (\Exception $e) {
// Silence exceptions in order to conform with PHP's string casting operations.
}
return $string;
@ -74,7 +71,7 @@ class Stream implements StreamInterface
*
* 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()
{
@ -159,13 +156,12 @@ class Stream implements StreamInterface
/**
* Seek to the beginning of the stream.
*
* If the stream is not seekable, this method will return FALSE, indicating
* failure; otherwise, it will perform a seek(0), and return the status of
* that operation.
* If the stream is not seekable, this method will raise an exception;
* otherwise, it will perform a seek(0).
*
* @see seek()
* @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()
{
@ -227,8 +223,9 @@ class Stream implements StreamInterface
* @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.
* @return string Returns the data read from the stream, or an empty string
* if no bytes are available.
* @throws \RuntimeException if an error occurs.
*/
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\UploadedFileInterface;
/**
* Value object representing a file uploaded through an HTTP request.
*/
class UploadedFile implements UploadedFileInterface
{
private $clientFilename;
@ -15,6 +18,13 @@ class UploadedFile implements UploadedFileInterface
private $stream;
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)
{
$this->clientFilename = $name;
@ -33,13 +43,13 @@ class UploadedFile implements UploadedFileInterface
/**
* 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
* stream functionality to manipulate the file upload, such as
* 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 will raise
* an exception.
*
* @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
* 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.
*
* 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/move_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.
*
* 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.
*/
public function getSize()
@ -113,14 +112,11 @@ class UploadedFile implements UploadedFileInterface
/**
* 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.
*
* 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
* @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
* 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
* was provided.
*/
@ -154,9 +147,6 @@ class UploadedFile implements UploadedFileInterface
* a malicious media type with the intention to corrupt or hack your
* 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
* was provided.
*/

38
src/Message/Uri.php
View File

@ -4,6 +4,17 @@ namespace WellRESTed\Message;
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
{
const MIN_PORT = 0;
@ -38,7 +49,7 @@ class Uri implements UriInterface
$this->scheme = $parsed["scheme"];
}
if (isset($parsed["host"])) {
$this->host = $parsed["host"];
$this->host = strtolower($parsed["host"]);
}
if (isset($parsed["port"])) {
$this->port = $parsed["port"];
@ -65,12 +76,12 @@ class Uri implements UriInterface
/**
* 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.
*
* 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.
*
* @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.
*
* 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.
*
* The authority syntax of the URI is:
@ -94,7 +105,7 @@ class Uri implements UriInterface
* </pre>
*
* 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
* @return string The URI authority, in "[user-info@]host[:port]" format.
@ -109,13 +120,12 @@ class Uri implements UriInterface
// User Info
$userInfo = $this->getUserInfo();
if ($userInfo !== "") {
$authority = $userInfo .= "@";
$authority .= $userInfo . "@";
}
// Host
$authority .= $host;
// Port: Include only if set AND non-standard.
$port = $this->getPort();
if ($port !== null) {
@ -132,15 +142,15 @@ class Uri implements UriInterface
/**
* 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.
*
* 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
* user value, with a colon (":") separating the values.
*
* The trailing "@" character is not part of the user information and MUST
* NOT be added.
* The trailing "@" character is not part of the user information and will
* not be added.
*
* @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.
*
* 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.
*
* @see http://tools.ietf.org/html/rfc3986#section-3.2.2
@ -345,7 +355,7 @@ class Uri implements UriInterface
}
$uri = clone $this;
$uri->host = $host;
$uri->host = strtolower($host);
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
* @param string $expected The expected result of getScheme
* @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::withUserInfo
* @covers WellRESTed\Message\Uri::getUserInfo
* @covers WellRESTed\Message\Uri::withUserInfo
* @dataProvider userInfoProvider
*
* @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::withHost
* @covers WellRESTed\Message\Uri::getHost
* @covers WellRESTed\Message\Uri::withHost
* @dataProvider hostProvider
* @param $expected
* @param $host
@ -252,12 +252,14 @@ class UriTest extends \PHPUnit_Framework_TestCase
{
return [
["", ""],
["localhost", "localhost"]
["localhost", "localhost"],
["localhost", "LOCALHOST"],
["foo.com", "FOO.com"]
];
}
/**
* @covers WellRESTed\Message\Uri::withHost
* @covers WellRESTed\Message\Uri::withHost
* @expectedException \InvalidArgumentException
* @dataProvider invalidHostProvider
* @param $host
@ -308,8 +310,8 @@ class UriTest extends \PHPUnit_Framework_TestCase
}
/**
* @covers WellRESTed\Message\Uri::getPort
* @covers WellRESTed\Message\Uri::withPort
* @covers WellRESTed\Message\Uri::getPort
* @covers WellRESTed\Message\Uri::withPort
* @dataProvider portAndSchemeProvider
*
* @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
* @dataProvider invalidPortProvider
* @param int $port
@ -370,9 +372,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
}
/**
* @covers WellRESTed\Message\Uri::getPath
* @covers WellRESTed\Message\Uri::withPath
* @covers WellRESTed\Message\Uri::percentEncode
* @covers WellRESTed\Message\Uri::getPath
* @covers WellRESTed\Message\Uri::withPath
* @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider pathProvider
* @param $expected
* @param $path
@ -385,9 +387,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
}
/**
* @covers WellRESTed\Message\Uri::getPath
* @covers WellRESTed\Message\Uri::withPath
* @covers WellRESTed\Message\Uri::percentEncode
* @covers WellRESTed\Message\Uri::getPath
* @covers WellRESTed\Message\Uri::withPath
* @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider pathProvider
* @param $expected
* @param $path
@ -426,9 +428,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
}
/**
* @covers WellRESTed\Message\Uri::getQuery
* @covers WellRESTed\Message\Uri::withQuery
* @covers WellRESTed\Message\Uri::percentEncode
* @covers WellRESTed\Message\Uri::getQuery
* @covers WellRESTed\Message\Uri::withQuery
* @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider queryProvider
* @param $expected
* @param $query
@ -441,9 +443,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
}
/**
* @covers WellRESTed\Message\Uri::getQuery
* @covers WellRESTed\Message\Uri::withQuery
* @covers WellRESTed\Message\Uri::percentEncode
* @covers WellRESTed\Message\Uri::getQuery
* @covers WellRESTed\Message\Uri::withQuery
* @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider queryProvider
* @param $expected
* @param $query
@ -466,7 +468,7 @@ class UriTest extends \PHPUnit_Framework_TestCase
}
/**
* @covers WellRESTed\Message\Uri::withPath
* @covers WellRESTed\Message\Uri::withPath
* @expectedException \InvalidArgumentException
* @dataProvider invalidPathProvider
* @param $path
@ -499,9 +501,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
}
/**
* @covers WellRESTed\Message\Uri::getFragment
* @covers WellRESTed\Message\Uri::withFragment
* @covers WellRESTed\Message\Uri::percentEncode
* @covers WellRESTed\Message\Uri::getFragment
* @covers WellRESTed\Message\Uri::withFragment
* @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider fragmentProvider
* @param $expected
* @param $fragment
@ -514,9 +516,9 @@ class UriTest extends \PHPUnit_Framework_TestCase
}
/**
* @covers WellRESTed\Message\Uri::getFragment
* @covers WellRESTed\Message\Uri::withFragment
* @covers WellRESTed\Message\Uri::percentEncode
* @covers WellRESTed\Message\Uri::getFragment
* @covers WellRESTed\Message\Uri::withFragment
* @covers WellRESTed\Message\Uri::percentEncode
* @dataProvider fragmentProvider
* @param $expected
* @param $fragment