1. class
  2. http
  3. \
  4. Env
  5. \
  6. Request

Request

class Request extends Message (View source)

The http\Env\Request class' instances represent the server's current HTTP request.

See http\Message for inherited members.

Constants

TYPE_NONE

No specific type of message.
TYPE_REQUEST

A request message.
TYPE_RESPONSE

A response message.

Properties

protected int $type

The message type. See http\Message::TYPE_* constants.

 from  Message
protected Body $body

The message's body.

 from  Message
protected string $requestMethod

The request method if the message is of type request.

 from  Message
protected string $requestUrl

The request url if the message is of type request.

 from  Message
protected string $responseStatus

The response status phrase if the message is of type response.

 from  Message
protected int $responseCode

The response code if the message is of type response.

 from  Message
protected string $httpVersion

A custom HTTP protocol version.

 from  Message
protected array $headers

Any message headers.

 from  Message
protected Message $parentMessage

Any parent message.

 from  Message
protected QueryString $query

The request's query parameters. ($_GET)
protected QueryString $form

The request's form parameters. ($_POST)
protected array $files

The request's form uploads. ($_FILES)
$cookie

The request's cookies. ($_COOKIE)

Methods

__construct()

Create an instance of the server's current HTTP request.

string
__toString()

Retrieve the message serialized to a string.

from  Message
Message
addBody(Body $body)

Append the data of $body to the message's body.

from  Message
Message
addHeader(string $name, mixed $value)

Add an header, appending to already existing headers.

from  Message
Message
addHeaders(array $headers, bool $append = false)

Add headers, optionally appending values, if header keys already exist.

from  Message
int
count()

Implements Countable.

from  Message
mixed
current()

Implements iterator.

from  Message
Message
detach()

Detach a clone of this message from any message chain.

from  Message
Body
getBody()

Retrieve the message's body.

from  Message
mixed|Header
getHeader(string $header, string $into_class = null)

Retrieve a single header, optionally hydrated into a http\Header extending class.

from  Message
array
getHeaders()

Retrieve all message headers.

from  Message
string
getHttpVersion()

Retrieve the HTTP protocol version of the message.

from  Message
string|null
getInfo()

Retrieve the first line of a request or response message.

from  Message
Message
getParentMessage()

Retrieve any parent message.

from  Message
string|false
getRequestMethod()

Retrieve the request method of the message.

from  Message
string|false
getRequestUrl()

Retrieve the request URL of the message.

from  Message
int|false
getResponseCode()

Retrieve the response code of the message.

from  Message
string|false
getResponseStatus()

Retrieve the response status of the message.

from  Message
int
getType()

Retrieve the type of the message.

from  Message
bool
isMultipart(string $boundary = null)

Check whether this message is a multipart message based on it's content type.

from  Message
mixed
key()

Implements Iterator.

from  Message
void
next()

Implements Iterator.

from  Message
Message
prepend(Message $message, bool $top = true)

Prepend message(s) $message to this message, or the top most message of this message chain.

from  Message
Message
reverse()

Reverse the message chain and return the former top-most message.

from  Message
void
rewind()

Implements Iterator.

from  Message
string|null
serialize()

Implements Serializable.

from  Message
Message
setBody(Body $body)

Set the message's body.

from  Message
Message
setHeader(string $header, mixed $value = null)

Set a single header.

from  Message
Message
setHeaders(array $headers = null)

Set the message headers.

from  Message
Message
setHttpVersion(string $http_version)

Set the HTTP protocol version of the message.

from  Message
Message
setInfo(string $http_info)

Set the complete message info, i.e. type and response resp. request information, at once.

from  Message
Message
setRequestMethod(string $method)

Set the request method of the message.

from  Message
Message
setRequestUrl(string $url)

Set the request URL of the message.

from  Message
Message
setResponseCode(int $response_code, bool $strict = true)

Set the response status code.

from  Message
Message
setResponseStatus(string $response_status)

Set the response status phrase.

from  Message
Message
setType(int $type)

Set the message type and reset the message info.

from  Message
Message
splitMultipartBody()

Splits the body of a multipart message.

from  Message
Message
toCallback(callable $callback)

Stream the message through a callback.

from  Message
Message
toStream(resource $stream)

Stream the message into stream $stream, starting from $offset, streaming $maxlen at most.

from  Message
string
toString(bool $include_parent = false)

Retrieve the message serialized to a string.

from  Message
void
unserialize(string $data)

Implements Serializable.

from  Message
bool
valid()

Implements Iterator.

from  Message
QueryString|string|mixed
getCookie(string $name = null, mixed $type = null, mixed $defval = null, bool $delete = false)

Retrieve an URL query value ($_GET).

array
getFiles()

Retrieve the uploaded files list ($_FILES).

QueryString|string|mixed
getForm(string $name = null, mixed $type = null, mixed $defval = null, bool $delete = false)

Retrieve a form value ($_POST).

QueryString|string|mixed
getQuery(string $name = null, mixed $type = null, mixed $defval = null, bool $delete = false)

Retrieve an URL query value ($_GET).

Details

at line 2953
__construct()

Create an instance of the server's current HTTP request.

Upon construction, the http\Env\Request acquires http\QueryString instances of query parameters ($_GET) and form parameters ($_POST).

It also compiles an array of uploaded files ($_FILES) more comprehensive than the original $_FILES array, see http\Env\Request::getFiles() for that matter.

Exceptions

InvalidArgumentException
UnexpectedValueException

in Message at line 1100
string __toString()

Retrieve the message serialized to a string.

Alias of http\Message::toString().

Return Value

string

the single serialized HTTP message.

in Message at line 1109
Message addBody(Body $body)

Append the data of $body to the message's body.

See http\Message::setBody() and http\Message\Body::append().

Parameters

Body $body

The message body to add.

Return Value

Message self.

in Message at line 1119
Message addHeader(string $name, mixed $value)

Add an header, appending to already existing headers.

See http\Message::addHeaders() and http\Message::setHeader().

Parameters

string $name

The header name.
mixed $value

The header value.

Return Value

Message self.

in Message at line 1129
Message addHeaders(array $headers, bool $append = false)

Add headers, optionally appending values, if header keys already exist.

See http\Message::addHeader() and http\Message::setHeaders().

Parameters

array $headers

The HTTP headers to add.
bool $append

Whether to append values for existing headers.

Return Value

Message self.

in Message at line 1136
int count()

Implements Countable.

Return Value

int

The custom count as an integer.

The return value is cast to an integer.

in Message at line 1144
mixed current()

Implements iterator.

See http\Message::valid() and http\Message::rewind().

Return Value

mixed

Can return any type.

in Message at line 1152
Message detach()

Detach a clone of this message from any message chain.

Return Value

Message clone.

Exceptions

InvalidArgumentException

in Message at line 1162
Body getBody()

Retrieve the message's body.

See http\Message::setBody().

Return Value

Body

the message body.

Exceptions

InvalidArgumentException
UnexpectedValueException

in Message at line 1172
mixed|Header getHeader(string $header, string $into_class = null)

Retrieve a single header, optionally hydrated into a http\Header extending class.

Parameters

string $header

The header's name.
string $into_class

The name of a class extending http\Header.

Return Value

mixed|Header

mixed the header value if $into_class is NULL. or \http\Header descendant.

in Message at line 1180
array getHeaders()

Retrieve all message headers.

See http\Message::setHeaders() and http\Message::getHeader().

Return Value

array

the message's headers.

in Message at line 1188
string getHttpVersion()

Retrieve the HTTP protocol version of the message.

See http\Message::setHttpVersion().

Return Value

string

the HTTP protocol version, e.g. "1.0"; defaults to "1.1".

in Message at line 1204
string|null getInfo()

Retrieve the first line of a request or response message.

See http\Message::setInfo and also:

  • http\Message::getType()
  • http\Message::getHttpVersion()
  • http\Message::getResponseCode()
  • http\Message::getResponseStatus()
  • http\Message::getRequestMethod()
  • http\Message::getRequestUrl()

Return Value

string|null

string the HTTP message information. or NULL if the message is neither of type request nor response.

in Message at line 1214
Message getParentMessage()

Retrieve any parent message.

See http\Message::reverse().

Return Value

Message

the parent message.

Exceptions

InvalidArgumentException
BadMethodCallException

in Message at line 1223
string|false getRequestMethod()

Retrieve the request method of the message.

See http\Message::setRequestMethod() and http\Message::getRequestUrl().

Return Value

string|false

string the request method. or false if the message was not of type request.

in Message at line 1232
string|false getRequestUrl()

Retrieve the request URL of the message.

See http\Message::setRequestUrl().

Return Value

string|false

string the request URL; usually the path and the querystring. or false if the message was not of type request.

in Message at line 1241
int|false getResponseCode()

Retrieve the response code of the message.

See http\Message::setResponseCode() and http\Message::getResponseStatus().

Return Value

int|false

int the response status code. or false if the message is not of type response.

in Message at line 1250
string|false getResponseStatus()

Retrieve the response status of the message.

See http\Message::setResponseStatus() and http\Message::getResponseCode().

Return Value

string|false

string the response status phrase. or false if the message is not of type response.

in Message at line 1258
int getType()

Retrieve the type of the message.

See http\Message::setType() and http\Message::getInfo().

Return Value

int

the message type. See http\Message::TYPE_* constants.

in Message at line 1269
bool isMultipart(string $boundary = null)

Check whether this message is a multipart message based on it's content type.

If the message is a multipart message and a reference $boundary is given, the boundary string of the multipart message will be stored in $boundary.

See http\Message::splitMultipartBody().

Parameters

string $boundary

A reference where the boundary string will be stored.

Return Value

bool

whether this is a message with a multipart "Content-Type".

in Message at line 1277
mixed key()

Implements Iterator.

See http\Message::current() and http\Message::rewind().

Return Value

mixed

TKey on success, or null on failure.

in Message at line 1283
void next()

Implements Iterator.

See http\Message::valid() and http\Message::rewind().

Return Value

void

Any returned value is ignored.

in Message at line 1297
Message prepend(Message $message, bool $top = true)

Prepend message(s) $message to this message, or the top most message of this message chain.

NOTE: The message chains must not overlap.

Parameters

Message $message

The message (chain) to prepend as parent messages.
bool $top

Whether to prepend to the top-most parent message.

Return Value

Message self.

Exceptions

InvalidArgumentException
UnexpectedValueException

in Message at line 1310
Message reverse()

Reverse the message chain and return the former top-most message.

NOTE: Message chains are ordered in reverse-parsed order by default, i.e. the last parsed message is the message you'll receive from any call parsing HTTP messages.

This call re-orders the messages of the chain and returns the message that was parsed first with any later parsed messages re-parentized.

Return Value

Message

the other end of the message chain.

Exceptions

InvalidArgumentException

in Message at line 1315
void rewind()

Implements Iterator.

Return Value

void

Any returned value is ignored.

in Message at line 1322
string|null serialize()

Implements Serializable.

Return Value

string|null

The string representation of the object or null

in Message at line 1333
Message setBody(Body $body)

Set the message's body.

See http\Message::getBody() and http\Message::addBody().

Parameters

Body $body

The new message body.

Return Value

Message self.

Exceptions

InvalidArgumentException
UnexpectedValueException

in Message at line 1347
Message setHeader(string $header, mixed $value = null)

Set a single header.

See http\Message::getHeader() and http\Message::addHeader().

NOTE: Prior to v2.5.6/v3.1.0 headers with the same name were merged into a single header with values concatenated by comma.

Parameters

string $header

The header's name.
mixed $value

The header's value. Removes the header if NULL.

Return Value

Message self.

in Message at line 1360
Message setHeaders(array $headers = null)

Set the message headers.

See http\Message::getHeaders() and http\Message::addHeaders().

NOTE: Prior to v2.5.6/v3.1.0 headers with the same name were merged into a single header with values concatenated by comma.

Parameters

array $headers

The message's headers.

Return Value

Message null.

in Message at line 1371
Message setHttpVersion(string $http_version)

Set the HTTP protocol version of the message.

See http\Message::getHttpVersion().

Parameters

string $http_version

The protocol version, e.g. "1.1", optionally prefixed by "HTTP/".

Return Value

Message self.

Exceptions

InvalidArgumentException
BadHeaderException

in Message at line 1382
Message setInfo(string $http_info)

Set the complete message info, i.e. type and response resp. request information, at once.

See http\Message::getInfo().

Parameters

string $http_info

The message info (first line of an HTTP message).

Return Value

Message self.

Exceptions

InvalidArgumentException
BadHeaderException

in Message at line 1393
Message setRequestMethod(string $method)

Set the request method of the message.

See http\Message::getRequestMethod() and http\Message::setRequestUrl().

Parameters

string $method

The request method.

Return Value

Message self.

Exceptions

InvalidArgumentException
BadMethodCallException

in Message at line 1404
Message setRequestUrl(string $url)

Set the request URL of the message.

See http\Message::getRequestUrl() and http\Message::setRequestMethod().

Parameters

string $url

The request URL.

Return Value

Message self.

Exceptions

InvalidArgumentException
BadMethodCallException

in Message at line 1419
Message setResponseCode(int $response_code, bool $strict = true)

Set the response status code.

See http\Message::getResponseCode() and http\Message::setResponseStatus().

NOTE: This method also resets the response status phrase to the default for that code.

Parameters

int $response_code

The response code.
bool $strict

Whether to check that the response code is between 100 and 599 inclusive.

Return Value

Message self.

Exceptions

InvalidArgumentException
BadMethodCallException

in Message at line 1430
Message setResponseStatus(string $response_status)

Set the response status phrase.

See http\Message::getResponseStatus() and http\Message::setResponseCode().

Parameters

string $response_status

The status phrase.

Return Value

Message self.

Exceptions

InvalidArgumentException
BadMethodCallException

in Message at line 1439
Message setType(int $type)

Set the message type and reset the message info.

See http\Message::getType() and http\Message::setInfo().

Parameters

int $type

The desired message type. See the http\Message::TYPE_* constants.

Return Value

Message self.

in Message at line 1450
Message splitMultipartBody()

Splits the body of a multipart message.

See http\Message::isMultipart() and http\Message\Body::addPart().

Return Value

Message

a message chain of all messages of the multipart body.

Exceptions

InvalidArgumentException
BadMethodCallException
BadMessageException

in Message at line 1458
Message toCallback(callable $callback)

Stream the message through a callback.

Parameters

callable $callback

The callback of the form function(http\Message $from, string $data).

Return Value

Message self.

in Message at line 1466
Message toStream(resource $stream)

Stream the message into stream $stream, starting from $offset, streaming $maxlen at most.

Parameters

resource $stream

The resource to write to.

Return Value

Message self.

in Message at line 1474
string toString(bool $include_parent = false)

Retrieve the message serialized to a string.

Parameters

bool $include_parent

Whether to include all parent messages.

Return Value

string

the HTTP message chain serialized to a string.

in Message at line 1481
void unserialize(string $data)

Implements Serializable.

Parameters

string $data

The string representation of the object.

Return Value

void

in Message at line 1489
bool valid()

Implements Iterator.

See http\Message::current() and http\Message::rewind().

Return Value

bool

The return value will be casted to boolean and then evaluated. Returns true on success or false on failure.

at line 2970
QueryString|string|mixed getCookie(string $name = null, mixed $type = null, mixed $defval = null, bool $delete = false)

Retrieve an URL query value ($_GET).

See http\QueryString::get() and http\QueryString::TYPE_* constants.

Parameters

string $name

The key to retrieve the value for.
mixed $type

The type to cast the value to. See http\QueryString::TYPE_* constants.
mixed $defval

The default value to return if the key $name does not exist.
bool $delete

Whether to delete the entry from the querystring after retrieval.

Return Value

QueryString|string|mixed

\http\QueryString if called without arguments. or string the whole querystring if $name is of zero length. or mixed $defval if the key $name does not exist. or mixed the querystring value cast to $type if $type was specified and the key $name exists. or string the querystring value if the key $name exists and $type is not specified or equals http\QueryString::TYPE_STRING.

at line 2977
array getFiles()

Retrieve the uploaded files list ($_FILES).

Return Value

array

the consolidated upload files array.

at line 2994
QueryString|string|mixed getForm(string $name = null, mixed $type = null, mixed $defval = null, bool $delete = false)

Retrieve a form value ($_POST).

See http\QueryString::get() and http\QueryString::TYPE_* constants.

Parameters

string $name

The key to retrieve the value for.
mixed $type

The type to cast the value to. See http\QueryString::TYPE_* constants.
mixed $defval

The default value to return if the key $name does not exist.
bool $delete

Whether to delete the entry from the querystring after retrieval.

Return Value

QueryString|string|mixed

\http\QueryString if called without arguments. or string the whole querystring if $name is of zero length. or mixed $defval if the key $name does not exist. or mixed the querystring value cast to $type if $type was specified and the key $name exists. or string the querystring value if the key $name exists and $type is not specified or equals http\QueryString::TYPE_STRING.

at line 3011
QueryString|string|mixed getQuery(string $name = null, mixed $type = null, mixed $defval = null, bool $delete = false)

Retrieve an URL query value ($_GET).

See http\QueryString::get() and http\QueryString::TYPE_* constants.

Parameters

string $name

The key to retrieve the value for.
mixed $type

The type to cast the value to. See http\QueryString::TYPE_* constants.
mixed $defval

The default value to return if the key $name does not exist.
bool $delete

Whether to delete the entry from the querystring after retrieval.

Return Value

QueryString|string|mixed

\http\QueryString if called without arguments. or string the whole querystring if $name is of zero length. or mixed $defval if the key $name does not exist. or mixed the querystring value cast to $type if $type was specified and the key $name exists. or string the querystring value if the key $name exists and $type is not specified or equals http\QueryString::TYPE_STRING.