From: Michael Wallner <mike@php.net>
Date: Thu, 7 Nov 2013 13:32:40 +0000 (+0100)
Subject: http\Message\Body
X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=b58f881f1bfba679372b1cf51d14228a00ab22d1;p=mdref%2Fmdref-http

http\Message\Body
---

diff --git a/http/Message.md b/http/Message.md
new file mode 100644
index 0000000..ce7603d
--- /dev/null
+++ b/http/Message.md
@@ -0,0 +1 @@
+# class http\Message extends http\Object implements Countable, Serializable, Iterator
diff --git a/http/Message/Body.md b/http/Message/Body.md
new file mode 100644
index 0000000..01c3479
--- /dev/null
+++ b/http/Message/Body.md
@@ -0,0 +1,13 @@
+# 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.
diff --git a/http/Message/Body/__construct.md b/http/Message/Body/__construct.md
new file mode 100644
index 0000000..2ef43e0
--- /dev/null
+++ b/http/Message/Body/__construct.md
@@ -0,0 +1,37 @@
+# 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.
+    ...
diff --git a/http/Message/Body/__toString.md b/http/Message/Body/__toString.md
new file mode 100644
index 0000000..7d121aa
--- /dev/null
+++ b/http/Message/Body/__toString.md
@@ -0,0 +1,26 @@
+# 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!
diff --git a/http/Message/Body/addForm.md b/http/Message/Body/addForm.md
new file mode 100644
index 0000000..d71fda9
--- /dev/null
+++ b/http/Message/Body/addForm.md
@@ -0,0 +1,116 @@
+# 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--
diff --git a/http/Message/Body/addPart.md b/http/Message/Body/addPart.md
new file mode 100644
index 0000000..8a2f8a7
--- /dev/null
+++ b/http/Message/Body/addPart.md
@@ -0,0 +1,36 @@
+# 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--
diff --git a/http/Message/Body/append.md b/http/Message/Body/append.md
new file mode 100644
index 0000000..126b7c7
--- /dev/null
+++ b/http/Message/Body/append.md
@@ -0,0 +1,12 @@
+# 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.
diff --git a/http/Message/Body/etag.md b/http/Message/Body/etag.md
new file mode 100644
index 0000000..a7d319d
--- /dev/null
+++ b/http/Message/Body/etag.md
@@ -0,0 +1,36 @@
+# 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)
+    }
diff --git a/http/Message/Body/getResource.md b/http/Message/Body/getResource.md
new file mode 100644
index 0000000..7aa15b7
--- /dev/null
+++ b/http/Message/Body/getResource.md
@@ -0,0 +1,22 @@
+# 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)
diff --git a/http/Message/Body/serialize.md b/http/Message/Body/serialize.md
new file mode 100644
index 0000000..0fa801c
--- /dev/null
+++ b/http/Message/Body/serialize.md
@@ -0,0 +1,12 @@
+# string http\Message\Body::serialize()
+
+Implements Serializable.
+Alias of http\Message\Body::__toString().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, serialized message body.
diff --git a/http/Message/Body/stat.md b/http/Message/Body/stat.md
new file mode 100644
index 0000000..dc18b36
--- /dev/null
+++ b/http/Message/Body/stat.md
@@ -0,0 +1,35 @@
+# 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)
diff --git a/http/Message/Body/toCallback.md b/http/Message/Body/toCallback.md
new file mode 100644
index 0000000..dab219a
--- /dev/null
+++ b/http/Message/Body/toCallback.md
@@ -0,0 +1,16 @@
+# 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.
diff --git a/http/Message/Body/toStream.md b/http/Message/Body/toStream.md
new file mode 100644
index 0000000..4f04d51
--- /dev/null
+++ b/http/Message/Body/toStream.md
@@ -0,0 +1,16 @@
+# 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.
diff --git a/http/Message/Body/toString.md b/http/Message/Body/toString.md
new file mode 100644
index 0000000..6856ffa
--- /dev/null
+++ b/http/Message/Body/toString.md
@@ -0,0 +1,12 @@
+# 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.
diff --git a/http/Message/Body/unserialize.md b/http/Message/Body/unserialize.md
new file mode 100644
index 0000000..1f44a83
--- /dev/null
+++ b/http/Message/Body/unserialize.md
@@ -0,0 +1,9 @@
+# void http\Message\Body::unserialize(string $serialized)
+
+Implements Serializable.
+
+## Params:
+
+* string $serialized  
+  The serialized message body.
+