--- /dev/null
+# class http\Message extends http\Object implements Countable, Serializable, Iterator
--- /dev/null
+# class http\Message\Body extends http\Object implements Serializable
+
+The message body, represented as a PHP (temporary) stream.
+
+> **Note:** Currently, http\Message\Body::addForm() creates multipart/form-data bodies.
+
+## Constants:
+
+None.
+
+## Properties:
+
+None.
--- /dev/null
+# void http\Message\Body::__construct([resource $stream = NULL])
+
+Create a new message body, optionally referencing $stream.
+
+## Params:
+
+* Optional resource $stream = NULL
+ A stream to be used as message body.
+
+## Throws:
+
+* http\Exception.
+
+## Example:
+
+ <?php
+ ob_end_clean();
+
+ $body = new http\Message\Body(fopen(__FILE__, "r"));
+ $resp = new http\Env\Response;
+ $resp->setContentType("text/plain");
+ $resp->setBody($body);
+ $resp->send();
+ ?>
+
+Yields:
+
+ Accept-Ranges: bytes
+ X-Powered-By: PHP/5.5.5
+ Content-Type: text/plain
+ ETag: "138042e-527b5a0a-1b2"
+ Last-Modified: Thu, 07 Nov 2013 09:14:50 GMT
+
+ # void http\Message\Body::__construct([resource $stream = NULL])
+
+ Create a new message body, optionally referencing $stream.
+ ...
--- /dev/null
+# string http\Message\Body::__toString()
+
+String cast handler.
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the message body.
+
+## Example:
+
+ <?php
+ $body = new http\Message\Body;
+ $body->append("this\nis\nan\nexample!\n");
+ echo $body;
+ ?>
+
+Yields:
+
+ this
+ is
+ an
+ example!
--- /dev/null
+# http\Message\Body http\Message\Body::addForm([array $fields = NULL[, array $files = NULL]])
+
+Add form fields and files to the message body.
+
+> **Note:** Currently, http\Message\Body::addForm() creates "multipart/form-data" bodies.
+
+## Params:
+
+* array $fields = NULL
+ List of form fields to add.
+
+* array $files = NULL
+ List of form files to add.
+
+$fields must look like:
+
+ [
+ "field_name" => "value",
+ "multi_field" => [
+ "value1",
+ "value2"
+ ]
+ ]
+
+$files must look like:
+
+ [
+ [
+ "name" => "field_name",
+ "type" => "content/type",
+ "file" => "/path/to/file.ext"
+ ], [
+ "name" => "field_name2",
+ "type" => "text/plain",
+ "file" => "file.ext",
+ "data" => "string"
+ ], [
+ "name" => "field_name3",
+ "type" => "image/jpeg",
+ "file" => "file.ext",
+ "data" => fopen("/home/mike/Pictures/mike.jpg","r")
+ ]
+
+As you can see, a file structure must contain a "file" entry, which holds a file path, and an optional "data" entry, which may either contain a resource to read from or the actual data as string.
+
+## Returns:
+
+* http\Message\Body, self.
+
+## Example:
+
+ <?php
+ $body = new http\Message\Body;
+ $body->addForm([
+ "field_name" => "value",
+ "multi_field" => [
+ "value1",
+ "value2"
+ ]
+ ], [
+ [
+ "name" => "field_name",
+ "type" => "application/octet-stream",
+ "file" => "/run/gpm.pid"
+ ], [
+ "name" => "field_name2",
+ "type" => "text/plain",
+ "file" => "signature.txt",
+ "data" => "-- \nMike\n"
+ ], [
+ "name" => "field_name3",
+ "type" => "image/jpeg",
+ "file" => "picture.jpg",
+ "data" => fopen("/home/mike/Pictures/mike.jpg","r")
+ ]
+ ]);
+
+ echo $body;
+ ?>
+
+Yields:
+
+ --32260b4b.3fea9114
+ Content-Disposition: form-data; name="field_name"
+
+ value
+ --32260b4b.3fea9114
+ Content-Disposition: form-data; name="multi_field[0]"
+
+ value1
+ --32260b4b.3fea9114
+ Content-Disposition: form-data; name="multi_field[1]"
+
+ value2
+ --32260b4b.3fea9114
+ Content-Disposition: form-data; name="field_name"; filename="gpm.pid"
+ Content-Transfer-Encoding: binary
+ Content-Type: application/octet-stream
+
+ 316
+
+ --32260b4b.3fea9114
+ Content-Disposition: form-data; name="field_name2"; filename="signature.txt"
+ Content-Transfer-Encoding: binary
+ Content-Type: text/plain
+
+ --
+ Mike
+
+ --32260b4b.3fea9114
+ Content-Disposition: form-data; name="field_name3"; filename="picture.jpg"
+ Content-Transfer-Encoding: binary
+ Content-Type: image/jpeg
+
+ ...JPEG...
+ --32260b4b.3fea9114--
--- /dev/null
+# http\Message\Body http\Message\Body::addPart(http\Message $part)
+
+Add a part to a multipart body.
+
+## Params:
+
+* http\Message $part
+ The message part.
+
+## Returns:
+
+* http\Message\Body, self.
+
+## Example:
+
+ <?php
+ $multi = new http\Message\Body;
+ $multi->addPart(new http\Message("Content-type: text/plain\n\nHello part 1!"));
+ $multi->addPart(new http\Message("Content-type: text/plain\n\nHello part 2!"));
+
+ echo $multi;
+ ?>
+
+Yields:
+
+ --8a72b190.3fe908df
+ Content-Type: text/plain
+ Content-Length: 13
+
+ Hello part 1!
+ --8a72b190.3fe908df
+ Content-Type: text/plain
+ Content-Length: 13
+
+ Hello part 2!
+ --8a72b190.3fe908df--
--- /dev/null
+# http\Message\Body http\Message\Body::append(string $data)
+
+Append plain bytes to the message body.
+
+## Params:
+
+* string $data
+ The data to append to the body.
+
+## Returns:
+
+* http\Message\Body, self.
--- /dev/null
+# string http\Message\Body::etag()
+
+Retrieve the ETag of the body.
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, an Apache style ETag of inode, mtime and size in hex concatenated by hyphens if the message body stream is stat-able.
+* string, a content hash (which algorithm is determined by INI http.etag.mode) if the stream is not stat-able.
+* false, if http.etag.mode is not a known hash algorithm.
+
+## Example:
+
+ <?php
+ $temp = (new http\Message\Body)->etag();
+ $file = (new http\Message\Body(fopen(__FILE__,"r")))->etag();
+
+ ini_set("http.etag.mode", "bogus");
+ $fail = (new http\Message\Body)->etag();
+
+ var_dump(compact("temp", "file", "fail"));
+ ?>
+
+Yields:
+
+ array(3) {
+ ["temp"]=>
+ string(8) "00000000"
+ ["file"]=>
+ string(20) "138043f-527b91d5-28c"
+ ["fail"]=>
+ bool(false)
+ }
--- /dev/null
+# resource http\Message\Body::getResource()
+
+Retrieve the underlying stream resource.
+
+## Params:
+
+None.
+
+## Returns:
+
+* resource, the underlying stream.
+
+## Example:
+
+ <?php
+ $body = new http\Message\Body;
+ var_dump($body->getResource());
+ ?>
+
+Yields:
+
+ resource(5) of type (stream)
--- /dev/null
+# string http\Message\Body::serialize()
+
+Implements Serializable.
+Alias of http\Message\Body::__toString().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, serialized message body.
--- /dev/null
+# mixed http\Message\Body::stat([string $field = NULL])
+
+Stat size, atime, mtime and/or ctime.
+
+## Params:
+
+* Optional string $field = NULL
+ A single stat field to retrieve.
+
+## Returns:
+
+* int, the requested stat field.
+* object, stdClass instance holding all four stat fields.
+
+## Example:
+
+ <?php
+ $body = new http\Message\Body(fopen(__FILE__, "r"));
+ var_dump($body->stat(), $body->stat()->size, $body->stat("s"));
+ ?>
+
+Yields:
+
+ object(stdClass)#2 (4) {
+ ["size"]=>
+ int(661)
+ ["atime"]=>
+ int(1383830756)
+ ["mtime"]=>
+ int(1383830753)
+ ["ctime"]=>
+ int(1383830753)
+ }
+ int(661)
+ int(661)
--- /dev/null
+# http\Message\Body http\Message\Body::toCallback(callable $callback[, int $offset = 0[, int $maxlen = 0]])
+
+Stream the message body through a callback.
+
+## Params:
+
+* callable $callback
+ The callback of the form function(http\MessageBody $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\Body, self.
--- /dev/null
+# http\Message\Body http\Message\Body::toStream(resource $stream[, int $offset = 0[, int $maxlen = 0]])
+
+Stream the message body into antother 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\Body, self.
--- /dev/null
+# string http\Message\Body::toString()
+
+Retrieve the message body serialized to a string.
+Alias of http\Message\Body::__toString().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, message body.
--- /dev/null
+# void http\Message\Body::unserialize(string $serialized)
+
+Implements Serializable.
+
+## Params:
+
+* string $serialized
+ The serialized message body.
+
projects / mdref / mdref-http / commitdiff
