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

Request

class Request extends Message (View source)

The http\Client\Request class provides an HTTP message implementation tailored to represent a request message to be sent by the client.

See http\Client::enqueue().

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 array $options

Array of options for this request, which override client options.

Methods

__construct(string|null $meth = null, string|null $url = null, array|null $headers = null, Body|null $body = null)

Create a new client request message to be enqueued and sent by http\Client.

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<0, max>
count()

Implements Countable.

from  Message
TValue
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|null $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
TKey|null
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|null $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
Request
addQuery(mixed $query_data)

Add querystring data.

Request
addSslOptions(array|null $ssl_options = null)

Add specific SSL options.

string|null
getContentType()

Extract the currently set "Content-Type" header.

array
getOptions()

Get priorly set options.

string|null
getQuery()

Retrieve the currently set querystring.

array
getSslOptions()

Retrieve priorly set SSL options.

Request
setContentType(string $content_type)

Set the MIME content type of the request message.

Request
setOptions(array|null $options = null)

Set client options.

Request
setQuery(mixed $query_data)

(Re)set the querystring.

Request
setSslOptions(array|null $ssl_options = null)

Specifically set SSL options.

Details

at line 2316
__construct(string|null $meth = null, string|null $url = null, array|null $headers = null, Body|null $body = null)

Create a new client request message to be enqueued and sent by http\Client.

Parameters

string|null $meth

The request method.
string|null $url

The request URL.
array|null $headers

HTTP headers.
Body|null $body

Request body.

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<0, max> count()

Implements Countable.

Return Value

int<0, max>

The custom count as an integer.

The return value is cast to an integer.

in Message at line 1144
TValue current()

Implements iterator.

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

Return Value

TValue

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|null $into_class = null)

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

Parameters

string $header

The header's name.
string|null $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
TKey|null key()

Implements Iterator.

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

Return Value

TKey|null

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|null $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|null $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 2327
Request addQuery(mixed $query_data)

Add querystring data.

See http\Client\Request::setQuery() and http\Message::setRequestUrl().

Parameters

mixed $query_data

Additional querystring data.

Return Value

Request self.

Exceptions

InvalidArgumentException
BadQueryStringException

at line 2337
Request addSslOptions(array|null $ssl_options = null)

Add specific SSL options.

See http\Client\Request::setSslOptions(), http\Client\Request::setOptions() and http\Client\Curl\$ssl options.

Parameters

array|null $ssl_options

Add this SSL options.

Return Value

Request self.

Exceptions

InvalidArgumentException

at line 2346
string|null getContentType()

Extract the currently set "Content-Type" header.

See http\Client\Request::setContentType().

Return Value

string|null

string the currently set content type. or NULL if no "Content-Type" header is set.

at line 2354
array getOptions()

Get priorly set options.

See http\Client\Request::setOptions().

Return Value

array options.

at line 2362
string|null getQuery()

Retrieve the currently set querystring.

Return Value

string|null

string the currently set querystring. or NULL if no querystring is set.

at line 2370
array getSslOptions()

Retrieve priorly set SSL options.

See http\Client\Request::getOptions() and http\Client\Request::setSslOptions().

Return Value

array

SSL options.

at line 2380
Request setContentType(string $content_type)

Set the MIME content type of the request message.

Parameters

string $content_type

The MIME type used as "Content-Type".

Return Value

Request self.

Exceptions

InvalidArgumentException
UnexpectedValueException

at line 2395
Request setOptions(array|null $options = null)

Set client options.

See http\Client::setOptions() and http\Client\Curl.

Request specific options override general options which were set in the client.

NOTE: Only options specified prior enqueueing a request are applied to the request.

Parameters

array|null $options

The options to set.

Return Value

Request self.

Exceptions

InvalidArgumentException

at line 2406
Request setQuery(mixed $query_data)

(Re)set the querystring.

See http\Client\Request::addQuery() and http\Message::setRequestUrl().

Parameters

mixed $query_data

Return Value

Request self.

Exceptions

InvalidArgumentException
BadQueryStringException

at line 2416
Request setSslOptions(array|null $ssl_options = null)

Specifically set SSL options.

See http\Client\Request::setOptions() and http\Client\Curl\$ssl options.

Parameters

array|null $ssl_options

Set SSL options to this array.

Return Value

Request self.

Exceptions

InvalidArgumentException