1. class
  2. http
  3. \
  4. Message

Message

class Message implements Countable, Serializable, Iterator (View source)

The message class builds the foundation for any request and response message.

See http\Client\Request and http\Client\Response, as well as http\Env\Request and http\Env\Response.

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.
protected Body $body

The message's body.
protected string $requestMethod

The request method if the message is of type request.
protected string $requestUrl

The request url if the message is of type request.
protected string $responseStatus

The response status phrase if the message is of type response.
protected int $responseCode

The response code if the message is of type response.
protected string $httpVersion

A custom HTTP protocol version.
protected array $headers

Any message headers.
protected Message $parentMessage

Any parent message.

Methods

__construct(mixed $message = null, bool $greedy = true)

Create a new HTTP message.

string
__toString()

Retrieve the message serialized to a string.

Message
addBody(Body $body)

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

Message
addHeader(string $name, mixed $value)

Add an header, appending to already existing headers.

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

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

int
count()

Implements Countable.

mixed
current()

Implements iterator.

Message
detach()

Detach a clone of this message from any message chain.

Body
getBody()

Retrieve the message's body.

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

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

array
getHeaders()

Retrieve all message headers.

string
getHttpVersion()

Retrieve the HTTP protocol version of the message.

string|null
getInfo()

Retrieve the first line of a request or response message.

Message
getParentMessage()

Retrieve any parent message.

string|false
getRequestMethod()

Retrieve the request method of the message.

string|false
getRequestUrl()

Retrieve the request URL of the message.

int|false
getResponseCode()

Retrieve the response code of the message.

string|false
getResponseStatus()

Retrieve the response status of the message.

int
getType()

Retrieve the type of the message.

bool
isMultipart(string $boundary = null)

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

mixed
key()

Implements Iterator.

void
next()

Implements Iterator.

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

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

Message
reverse()

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

void
rewind()

Implements Iterator.

string|null
serialize()

Implements Serializable.

Message
setBody(Body $body)

Set the message's body.

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

Set a single header.

Message
setHeaders(array $headers = null)

Set the message headers.

Message
setHttpVersion(string $http_version)

Set the HTTP protocol version of the message.

Message
setInfo(string $http_info)

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

Message
setRequestMethod(string $method)

Set the request method of the message.

Message
setRequestUrl(string $url)

Set the request URL of the message.

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

Set the response status code.

Message
setResponseStatus(string $response_status)

Set the response status phrase.

Message
setType(int $type)

Set the message type and reset the message info.

Message
splitMultipartBody()

Splits the body of a multipart message.

Message
toCallback(callable $callback)

Stream the message through a callback.

Message
toStream(resource $stream)

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

string
toString(bool $include_parent = false)

Retrieve the message serialized to a string.

void
unserialize(string $data)

Implements Serializable.

bool
valid()

Implements Iterator.

Details

at line 1092
__construct(mixed $message = null, bool $greedy = true)

Create a new HTTP message.

Parameters

mixed $message

Either a resource or a string, representing the HTTP message.
bool $greedy

Whether to read from a $message resource until EOF.

Exceptions

InvalidArgumentException
BadMessageException

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.

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.

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.

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.

at line 1136
int count()

Implements Countable.

Return Value

int

The custom count as an integer.

The return value is cast to an integer.

at line 1144
mixed current()

Implements iterator.

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

Return Value

mixed

Can return any type.

at line 1152
Message detach()

Detach a clone of this message from any message chain.

Return Value

Message clone.

Exceptions

InvalidArgumentException

at line 1162
Body getBody()

Retrieve the message's body.

See http\Message::setBody().

Return Value

Body

the message body.

Exceptions

InvalidArgumentException
UnexpectedValueException

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.

at line 1180
array getHeaders()

Retrieve all message headers.

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

Return Value

array

the message's headers.

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".

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.

at line 1214
Message getParentMessage()

Retrieve any parent message.

See http\Message::reverse().

Return Value

Message

the parent message.

Exceptions

InvalidArgumentException
BadMethodCallException

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.

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.

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.

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.

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.

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".

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.

at line 1283
void next()

Implements Iterator.

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

Return Value

void

Any returned value is ignored.

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

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

at line 1315
void rewind()

Implements Iterator.

Return Value

void

Any returned value is ignored.

at line 1322
string|null serialize()

Implements Serializable.

Return Value

string|null

The string representation of the object or null

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

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.

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.

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

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

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

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

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

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

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.

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

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.

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.

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.

at line 1481
void unserialize(string $data)

Implements Serializable.

Parameters

string $data

The string representation of the object.

Return Value

void

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.