# class http\Message extends http\Object implements Countable, Serializable, Iterator
+
+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 = http\Message::TYPE_NONE
+ The message type. See http\Message::TYPE_* constants.
+* protected http\Message\Body $body = NULL
+ 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 respose status phrase if the message is of type response.
+* protected int $responseCode = 0
+ The response code if the message is of type response.
+* protected string $httpVersion = NULL
+ A custom HTTP protocol version.
+* protected array $headers = NULL
+ Any message headers.
+* protected http\Message $parentMessage
+ Any parent message.
+
--- /dev/null
+# string http\Message\Body::getBoundary()
+
+Retrieve any boundary of tehe message body.
+See http\Message::splitMultipartBody().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the message body boundary.
+* NULL, if this message body has no boundary.
## Params:
* callable $callback
- The callback of the form function(http\MessageBody $from, string $data).
+ The callback of the form function(http\Message\Body $from, string $data).
* Optional int $offset = 0
Start to stream from this offset.
* Optional int $maxlen = 0
--- /dev/null
+# void http\Message::__construct([mixed $message = NULL[, bool $greedy = true])
+
+Create a new HTTP message.
+
+## Params:
+
+* Optional mixed $message = NULL
+ Either a resource or a string, representing the HTTP message.
+* Optional bool $greedy = true
+ Whether to read from a $message resource until EOF.
+
+## Throws:
+
+* http\Exception.
--- /dev/null
+# string http\Message::__toString()
+
+Retrieve the message serialized to a string.
+Alias of http\Message::toString().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the single serialized HTTP message.
--- /dev/null
+# http\Message http\Message::addBody(http\Message\Body $body)
+
+Append the data of $body to the message's body.
+See http\Message::setBody() and http\Message\Body::append().
+
+## Params:
+
+* http\Message\Body $body
+ The message body to add.
+
+## Returns:
+
+* http\Message, self.
--- /dev/null
+# http\Message http\Message::addHeader(string $name, mixed $value)
+
+Add an header, appending to already existing headers.
+See http\Message::addHeaders() and http\Message::setHeader().
+
+## Params:
+
+* string $name
+ The header name.
+* mixed $value
+ The header value.
+
+## Returns:
+
+* http\Message, self.
+
+## Example:
+
+ <?php
+ $msg = new http\Message;
+
+ $msg->addHeader("X-Num", "123");
+ $msg->addHeader("X-Num", "456");
+
+ echo $msg;
+ ?>
+
+Yields:
+
+ X-Num: 123, 456
--- /dev/null
+# http\Message http\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().
+
+## Params:
+
+* array $headers
+ The HTTP headers to add.
+* Optional bool $append = false
+ Whether to append values for existing headers.
+
+## Returns:
+
+* http\Message, self.
+
+## Example:
+
+ <?php
+ $msg = new http\Message;
+
+ $msg->addHeaders(["Cache-Control" => "public"]);
+ var_dump($msg->getHeaders());
+
+ $msg->addHeaders(["Cache-Control" => "private"]);
+ var_dump($msg->getHeaders());
+
+ $msg->addHeaders(["Cache-Control" => "must-revalidate"], true);
+ var_dump($msg->getHeaders());
+
+ echo $msg;
+ ?>
+
+Yields:
+
+ array(1) {
+ ["Cache-Control"]=>
+ string(6) "public"
+ }
+ array(1) {
+ ["Cache-Control"]=>
+ string(7) "private"
+ }
+ array(1) {
+ ["Cache-Control"]=>
+ array(2) {
+ [0]=>
+ string(7) "private"
+ [1]=>
+ string(15) "must-revalidate"
+ }
+ }
+ Cache-Control: private, must-revalidate
+
--- /dev/null
+# int http\Message::count()
+
+Implements Countable.
+
+## Params:
+
+None.
+
+## Returns:
+
+* int, thre count of messages in the chain above the current message.
--- /dev/null
+# http\Message http\Message::current()
+
+Implements iterator.
+See http\Message::valid() and http\Message::rewind().
+
+## Params:
+
+None.
+
+## Returns:
+
+* http\Message, the current message in the iterated message chain.
--- /dev/null
+# http\Message http\Message::detach()
+
+Detach a clone of this message from any message chain.
+
+## Params:
+
+None.
+
+## Returns:
+
+* http\Message, clone.
+
+## Throws:
+
+* http\Exception.
--- /dev/null
+# http\Message\Body http\Message::getBody()
+
+Retrieve the message's body.
+See http\Message::setBody().
+
+## Params:
+
+None.
+
+## Returns:
+
+* http\Message\Body, the message body.
+
+## Throws:
+
+* http\Exception.
--- /dev/null
+# mixed http\Message::getHeader(string $header[, string $into_class = NULL])
+
+Retrieve a single header, optionally hydrated into a http\Header extending class.
+
+## Params:
+
+* string $header
+ The header's name.
+* Optional string $into_class = NULL
+ The name of a class extending http\Header.
+
+## Returns:
+
+* mixed, the header value if $into_class is NULL.
+* http\Header, descendant.
+
+## Warnings:
+
+* E_INVALID_PARAM, if $into_class is not a descendant of http\Header.
+
+## Example:
+
+ <?php
+ class hdr extends http\Header {
+ function __construct($name, $value) {
+ var_dump($name, $value);
+ parent::__construct($name, $value);
+ }
+ }
+
+ $msg = new http\Message("Foo: bar");
+ $msg->getHeader("foo", "hdr");
+ ?>
+
+Yields:
+
+ string(3) "foo"
+ string(3) "bar"
--- /dev/null
+# array http\Message::getHeaders()
+
+Retrieve all message headers.
+See http\Message::setHeaders() and http\Message::getHeader().
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, the message's headers.
--- /dev/null
+# string http\Message::getHttpVersion()
+
+Retreive the HTTP protocol version of the message.
+See http\Message::setHttpVersion().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the HTTP protocol version, e.g. "1.0"; defaults to "1.1".
--- /dev/null
+# string http\Message::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()
+
+## Params:
+
+None.
+
+## Return:
+
+* string, the HTTP message information.
+* NULL, if the message is neither of type request nor response.
+
--- /dev/null
+# http\Message http\Message::getParentMessage()
+
+Retrieve any parent message.
+See http\Message::reverse().
+
+## Params:
+
+None.
+
+## Returns:
+
+* http/Message, the parent message.
+
+## Throws:
+
+* http\Exception.
+
+
+## Example:
+
+ <?php
+ $message = new http\Message(
+ "GET / HTTP/1.0\n".
+ "HTTP/1.0 200 Ok"
+ );
+ var_dump($message->getParentMessage()->toString());
+ ?>
+
+Yields:
+
+ string(16) "GET / HTTP/1.0
+ "
--- /dev/null
+# string http\Message::getRequestMethod()
+
+Retrieve the request method of the message.
+See http\Message::setRequestMethod() and http\Message::getRequestUrl().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the request method.
+* false, if the message was not of type request.
+
+## Notices:
+
+* E_MESSAGE_TYPE, if the message is not of type request.
--- /dev/null
+# string http\Message::getRequestUrl()
+
+Retrieve the request URL of the message.
+See http\Message::setRequestUrl().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the request URL; usually the path and the querystring.
+* false, if the message was not of type request.
+
+## Notices:
+
+* E_MESSAGE_TYPE, if the message is not of type request.
--- /dev/null
+# int http\Message::getResponseCode()
+
+Retrieve the response code of the message.
+See http\Message::setResponseCode() and http\Massage::getResponseStatus().
+
+## Params:
+
+None.
+
+## Returns:
+
+* int, the response status code.
+* false, if the message is not of type response.
+
+## Notices:
+
+* E_MESSAGE_TYPE, if the message is not of type response.
--- /dev/null
+# string http\Message::getResponseStatus()
+
+Retrieve the response status of the message.
+See http\Message::setResponseStatus() and http\Message::getResponseCode().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the response status phrase.
+* false, if the message is not of type response.
+
+## Notices:
+
+* E_MESSAGE_TYPE, if the message is not of type response.
--- /dev/null
+# int http\Message::getType()
+
+Retrieve the type of the message.
+See http\Message::setType() and http\Message::getInfo().
+
+## Params:
+
+None.
+
+## Returns:
+
+* int, the message type. See http\Message::TYPE_* constants.
--- /dev/null
+# bool http\Message::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().
+
+## Params:
+
+* Optional reference string &$boundary = NULL
+ A reference where the boundary string will be stored.
+
+## Returns:
+
+* bool, whether this is a message with a multipart "Content-Type".
--- /dev/null
+# int http\Message::key()
+
+Implements Iterator.
+See http\Message::current() and http\Message::rewind().
+
+## Params:
+
+None.
+
+## Returns:
+
+* int, a non-sequential integer key.
--- /dev/null
+# void http\Message::next()
+
+Implements Iterator.
+See http\Message::valid() and http\Message::rewind().
+
+## Params:
+
+None.
+
--- /dev/null
+# http\Message http\Message::prepend(http\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.
+
+## Params:
+
+* http\Message $message
+ The message (chain) to prepend as parent messages.
+* Optional bool $top = true
+ Whether to prepend to the top-most parent message.
+
+## Returns:
+
+* http\Message, self.
+
+## Throws:
+
+* http\Exception.
--- /dev/null
+# http\Message http\Messae::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.
+
+## Params:
+
+None.
+
+## Returns:
+
+* http\Message, the other end of the message chain.
--- /dev/null
+# void http\Message::rewind()
+
+Implements Iterator.
+
+## Params:
+
+None.
+
+## Example:
+
+ <?php
+ $message = new http\Message("GET / HTTP/1.1\n".
+ "HTTP/1.1 200\n".
+ "GET / HTTP/1.0\n".
+ "HTTP/1.0 426"
+ );
+ foreach ($message as $key => $msg) {
+ printf("Key %d is a %8s: %s\n",
+ $key, ["message", "request", "response"][$msg->getType()],
+ $msg->getInfo()
+ );
+ }
+ ?>
+
+Yields:
+
+ Key 2 is a response: HTTP/1.0 426
+ Key 8 is a request: GET / HTTP/1.0
+ Key 6 is a response: HTTP/1.1 200
+ Key 4 is a request: GET / HTTP/1.1
--- /dev/null
+# string http\Message::serialize()
+
+Implements Serializable.
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the serialized HTTP message.
--- /dev/null
+# http\Message http\Message::setBody(http\Message\Body $body)
+
+Set the message's body.
+See http\Message::getBody() and http\Message::addBody().
+
+## Params:
+
+* http\Message\Body $body
+ The new message body.
+
+## Returns:
+
+* http\Message, self.
--- /dev/null
+# http\Message http\Message::setHeader(string $header[, mixed $value = NULL])
+
+Set a single header.
+See http\Message::getHeader() and http\Message::addHeader().
+
+## Params:
+
+* string $header
+ The header's name.
+* Optional mixed $value = NULL
+ The header's value. Removes the header if NULL.
+
+## Returns:
+
+* http\Message, self.
--- /dev/null
+# http\Message http\Message::setHeaders(array $headers = NULL)
+
+Set the message headers.
+See http\Message::getHeaders() and http\Message::addHeaders().
+
+## Params:
+
+* array $headers = NULL
+ The message's headers.
+
+## Returns:
+
+* http\Message, null.
+
+## Example:
+
+ <?php
+ $msg = new http\Message;
+
+ $msg->setHeaders([
+ "Content-Type" => "text/plain",
+ "Content-Encoding" => "gzip",
+ "Content-Location" => "/foo/bar"
+ ]);
+ var_dump($msg->getHeaders());
+
+ $msg->setHeaders(null);
+ var_dump($msg->getHeaders());
+ ?>
+
+Yields:
+
+ array(3) {
+ ["Content-Type"]=>
+ string(10) "text/plain"
+ ["Content-Encoding"]=>
+ string(4) "gzip"
+ ["Content-Location"]=>
+ string(8) "/foo/bar"
+ }
+ array(0) {
+ }
+
--- /dev/null
+# http\Message http\Message::setHttpVersion(string $http_version)
+
+Set the HTTP protocol version of the message.
+See http\Message::getHttpVersion().
+
+## Params:
+
+* string $http_version
+ The protocol version, e.g. "1.1", optionally prefixed by "HTTP/".
+
+## Returns:
+
+* http\Message, self.
+
+## Notices:
+
+* E_MALFORMED_HEADERS, if the version separator is non-standard.
+
+## Warnings:
+
+* E_MALFORMED_HEADERS, if the version could not be parsed.
+
+## Example:
+
+ <?php
+ $message = new http\Message;
+ var_dump($message->getHttpVersion());
+ $message->setHttpVersion("HTTP/1_0");
+ var_dump($message->getHttpVersion());
+ ?>
+
+Yields:
+
+ string(3) "1.1"
+ Notice: Non-standard version separator '_' in HTTP protocol version 'HTTP/1_0'
+ string(3) "1.0"
--- /dev/null
+# http\Message http\Message::setInfo(string $http_info)
+
+Set the complete message info, i.e. type and response resp. request information, at once.
+See http\Message::getInfo().
+
+## Params:
+
+* string $http_info
+ The message info (first line of an HTTP message).
+
+## Returns:
+
+* http\Message, self.
+
+## Warnings:
+
+* E_MALFORMED_HEADERS, if the message information could not be parsed.
+
+## Format of the message info:
+
+The message info looks similar to the following line for a response, see also http\Message::setResponseCode() and http\Message::setResponseStatus():
+
+ HTTP/1.1 200 Ok
+
+The message info looks similar to the following line for a request, see also http\Message::setRequestMethod() and http\Message::setRequestUrl():
+
+ GET / HTTP/1.1
+
+See http\Message::setHttpVersion().
--- /dev/null
+# http\Message http\Message::setRequestMethod(string $method)
+
+Set the request method of the message.
+See http\Message::getRequestMethod() and http\Message::setRequestUrl().
+
+## Params:
+
+* string $method
+ The request method.
+
+## Returns:
+
+* http\Message, self.
+* false, if the message was not of type request.
+
+## Notices:
+
+* E_MESSAGE_TYPE, if the message is not of type request.
+
+## Warnings:
+
+* E_INVALID_PARAM, if the method is of zero length.
--- /dev/null
+# http\Message http\Message::setRequestUrl(string $url)
+
+Set the request URL of the message.
+See http\Message::getRequestUrl() and http\Message::setRequestMethod().
+
+## Params:
+
+* string $url
+ The request URL.
+
+## Returns:
+
+* http\Message, self.
+* false, if the message was not of type request.
+
+## Notices:
+
+* E_MESSAGE_TYPE, if the message is not of type request.
+
+## Warnings:
+
+* E_INVALID_PARAM, if the url is of zero length.
+
+## Example:
+
+> **Note:** The request URL in a request message usually only consists of the path and the querystring.
+
+ <?php
+ $m = new http\Message;
+ $m->setType(http\Message::TYPE_REQUEST);
+ $m->setRequestMethod("GET");
+ $m->setRequestUrl("http://foo.bar/baz?q");
+ echo $m;
+ ?>
+
+Yields:
+
+ GET http://foo.bar/baz?q HTTP/1.1
+
+Maybe you did not really expect this, so let's try this:
+
+ <?php
+ $m = new http\Message;
+ $u = new http\Url("http://foo.bar/baz?q");
+ $m->setType(http\Message::TYPE_REQUEST);
+ $m->setRequestMethod("GET");
+ $m->setRequestUrl($u->path ."?". $u->query);
+ $m->setHeader("Host", $u->host);
+ echo $m;
+ ?>
+
+Yields:
+
+ GET /baz?q HTTP/1.1
+ Host: foo.bar
--- /dev/null
+# http\Message http\Message::setResponseCode(int $response_code)
+
+Set the response status code.
+See http\Message::getResponseCode() and http\Message::setResponseStatus().
+
+## Params:
+
+* int $response_code
+ The response code.
+
+## Returns:
+
+* http\Message, self.
+* false, if the message is not of type response.
+
--- /dev/null
+# http\Message http\Message::setResponseStatus(string $response_status)
+
+Set the response status phrase.
+See http\Message::getResponseStatus() and http\Message::setResponseCode().
+
+## Params:
+
+* string $response_status
+ The status phrase.
+
+## Returns:
+
+* http\Message, self.
+* false, if the message is not of type response.
+
+## Notice:
+
+* E_MESSAGE_TYPE, if the message is not of type response.
+
+
+## Example:
+
+ <?php
+ $message = new http\Message;
+ $message->setType(http\Message::TYPE_RESPONSE);
+ $message->setResponseCode(200);
+ $message->setResponseStatus("Ok");
+ echo $message;
+ ?>
+
+Yields:
+
+ HTTP/1.1 200 Ok
--- /dev/null
+# http\Message http\Message::setType(int $type)
+
+Set the message type and reset the message info.
+See http\Message::getType() and http\Message::setInfo().
+
+## Params:
+
+* int $type
+ The desired message type. See the http\Message::TYPE_* constants.
+
+## Returns:
+
+* http\Message, self.
--- /dev/null
+# http\Message http\Message::splitMultipartBody()
+
+Splits the body of a multipart message.
+See http\Message::isMultipart() and http\Message\Body::addPart().
+
+## Params:
+
+None.
+
+## Returns:
+
+* http\Message, a message chain of all messages of the multipart body.
+
+## Example:
+
+ <?php
+ $body = new http\Message\Body;
+ $body->addPart(new http\Message("Content-type: text/plain\n\nHello "));
+ $body->addPart(new http\Message("Content-type: text/plain\n\nWorld!"));
+
+ $msg = new http\Message;
+ $msg->setHeader("Content-Type",
+ "multipart/mixed; boundary=" . $body->getBoundary());
+ $msg->setBody($body);
+ var_dump($msg->isMultipart($bnd), $bnd);
+
+ $parts = $msg->splitMultipartBody();
+ var_dump(count($parts));
+ foreach ($parts->reverse() as $part) {
+ echo $part->getBody();
+ }
+ ?>
+
+Yields:
+
+ bool(true)
+ string(17) "16658735.3fe37486"
+ int(2)
+ Hello World!
--- /dev/null
+# http\Message http\Message::toCallback(callable $callback[, int $offset = 0[, int $maxlen = 0]])
+
+Stream the message through a callback.
+
+## Params:
+
+* callable $callback
+ The callback of the form function(http\Message $from, string $data).
+* Optional int $offset = 0
+ Start to stream from this offset.
+* Optional int $maxlen = 0
+ Stream at most $maxlen bytes, or all if $maxlen is less than 1.
+
+## Returns:
+
+* http\Message, self.
--- /dev/null
+# http\Message http\Message::toStream(resource $stream[, int $offset = 0[, int $maxlen = 0]])
+
+Stream the message into stream $stream, starting from $offset, streaming $maxlen at most.
+
+## Params:
+
+* resource $stream
+ The resource to write to.
+* Optional int $offset = 0
+ The starting offset.
+* Optional int $maxlen = 0
+ The maximum amount of data to stream. All content if less than 1.
+
+## Returns:
+
+* http\Message, self.
--- /dev/null
+# string http\Message::toString([bool $include_parent = false])
+
+Retrieve the message serialized to a string.
+
+## Params:
+
+* Optional bool $include_parent = false
+ Whether to include all parent messages.
+
+## Returns:
+
+* string, the HTTP message chain serialized to a string.
--- /dev/null
+# void http\Message::unserualize(string $data)
+
+Implements Serializable.
+
+## Params:
+
+* string $data
+ The serialized message.
+
--- /dev/null
+# bool http\Message::valid()
+
+Implements Iterator.
+See http\Message::current() and http\Message::rewind().
+
+## Params:
+
+None.
+
+## Returns:
+
+* bool, whether http\Message::current() would not return NULL.
projects / mdref / mdref-http / commitdiff
