From: Michael Wallner <mike@php.net>
Date: Thu, 31 Oct 2013 14:54:56 +0000 (+0100)
Subject: flush
X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=d5af35badf0c029ba85f9b53b78bcd5a01907a8d;p=mdref%2Fmdref-http

flush
---

diff --git a/http.md b/http.md
index e06a5bc..f439b0d 100644
--- a/http.md
+++ b/http.md
@@ -1,6 +1,17 @@
 # pecl/http v2
 
-This documentation is work-in-progress.
+> **Note:** This documentation is work-in-progress.
+
+## About
+
+Extended HTTP support. Again. Keep in mind that it's got the major version 2, because it's incompatible with pecl_http v1.
+
+* Introduces the http namespace.
+* Message bodies have been remodeled to use PHP temporary streams instead of in-memory buffers.
+* The utterly misunderstood HttpResponse class has been reimplemented as http\Env\Response inheriting http\Message.
+* Currently, there's only one Exception class left, http\Exception.
+* Errors triggered by the extension can be configured statically by http\Object::$defaultErrorHandling or inherited http\Object->errorHandling.
+* The request ecosystem has been modularized to support different libraries, though for the moment only libcurl is supported.
 
 ## INI Directives:
 
diff --git a/http/Env/Request.md b/http/Env/Request.md
index 63de534..57dc787 100644
--- a/http/Env/Request.md
+++ b/http/Env/Request.md
@@ -1,5 +1,9 @@
 # class http\Env\Request extends http\Message
 
+The http\Env\Request class' instances represent the server's current HTTP request.
+
+See http\Message for inherited members.
+
 ## Constants:
 
 None.
diff --git a/http/Env/Request/__construct.md b/http/Env/Request/__construct.md
index 307d73a..0e57072 100644
--- a/http/Env/Request/__construct.md
+++ b/http/Env/Request/__construct.md
@@ -1,7 +1,12 @@
-# void http\Env\Request::__construct(void)
+# void http\Env\Request::__construct()
 
-Instantiate the server's current HTTP request.
+Create an instance of the server's current HTTP request.
+
+Upon construction, the http\Env\Request acquires http\QueryString instances of  query paramters ($\_GET) and form parameters ($\_POST).
+
+It also compiles an array of uploaded files ($\_FILES) more comprehensive than the original $\_FILES array, see http\Env\Request::getFiles() for that matter.
 
 ## Params:
 
 None.
+
diff --git a/http/Env/Request/getFiles.md b/http/Env/Request/getFiles.md
new file mode 100644
index 0000000..82776b9
--- /dev/null
+++ b/http/Env/Request/getFiles.md
@@ -0,0 +1,45 @@
+# array http\Env\Request::getFiles()
+
+Retrieve the uploaded files list ($_FILES).
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, the consolidated upload files array.
+
+## Example:
+
+Here's an example how the original $_FILES array and the http\Env\Request's files array compare:
+
+	$r = new http\Env\Request;
+	$f = array();
+
+	foreach ($_FILES as $name => $data) {
+		foreach ((array) $data["tmp_name"] as $i => $file) {
+			$f[$name][$i] = array(
+				"file" => $file,
+				"name" => $data["name"][$i],
+				"size" => $data["size"][$i],
+				"type" => $data["type"][$i],
+				"error"=> $data["error"][$i]
+			);
+		}
+	}
+	assert($f == $r->getFiles());
+
+You can see that the second and third dimensions are swapped and ```tmp_name``` became ```file```, e.g:
+
+    array(
+		"upload" => array(
+			array(
+				"file" => "/tmp/phpXXXXXX",
+				"name" => "picture.jpeg",
+				"size" => 12345,
+				"type" => "image/jpeg",
+				"error"=> 0
+			)
+		)
+	);
diff --git a/http/Env/Request/getForm.md b/http/Env/Request/getForm.md
new file mode 100644
index 0000000..2ccdd26
--- /dev/null
+++ b/http/Env/Request/getForm.md
@@ -0,0 +1,25 @@
+# mixed http\Env\Request::getForm([string $name = NULL[, mixed $type = NULL[, mixed $defval = NULL[, bool $delete = false]]]])
+
+Retrieve a form value ($_POST).
+
+See http\QueryString::get() and http\QueryString::TYPE_* constants.
+
+## Params:
+
+* Optional string $name = NULL  
+  The key to retrieve the value for.
+* Optional mixed $type = NULL  
+  The type to cast the value to. See http\QueryString::TYPE_* constants.
+* Optional mixed $defval = NULL  
+  The default value to return if the key $name does not exist.
+* Optional bool $delete = false  
+  Whether to delete the entry from the querystring after retrieval.
+
+
+## Returns:
+
+* http\QueryString, if called without arguments.
+* string, the whole querystring if $name is of zero length.
+* mixed, $defval if the key $name does not exist.
+* mixed, the querystring value cast to $type if $type was specified and the key $name exists.
+* string, the querystring value if the key $name exists and $type is not specified or equals http\QueryString::TYPE_STRING.
diff --git a/http/Env/Request/getQuery.md b/http/Env/Request/getQuery.md
new file mode 100644
index 0000000..9196261
--- /dev/null
+++ b/http/Env/Request/getQuery.md
@@ -0,0 +1,25 @@
+# mixed http\Env\Request::getQuery([string $name = NULL[, mixed $type = NULL[, mixed $defval = NULL[, bool $delete = false]]]])
+
+Retrieve an URL query value ($_GET).
+
+See http\QueryString::get() and http\QueryString::TYPE_* constants.
+
+## Params:
+
+* Optional string $name = NULL  
+  The key to retrieve the value for.
+* Optional mixed $type = NULL  
+  The type to cast the value to. See http\QueryString::TYPE_* constants.
+* Optional mixed $defval = NULL  
+  The default value to return if the key $name does not exist.
+* Optional bool $delete = false  
+  Whether to delete the entry from the querystring after retrieval.
+
+
+## Returns:
+
+* http\QueryString, if called without arguments.
+* string, the whole querystring if $name is of zero length.
+* mixed, $defval if the key $name does not exist.
+* mixed, the querystring value cast to $type if $type was specified and the key $name exists.
+* string, the querystring value if the key $name exists and $type is not specified or equals http\QueryString::TYPE_STRING.
diff --git a/http/Exception.md b/http/Exception.md
new file mode 100644
index 0000000..7c18655
--- /dev/null
+++ b/http/Exception.md
@@ -0,0 +1,3 @@
+# class http\Exception extends Exception
+
+The http extension's Exception.
diff --git a/http/QueryString.md b/http/QueryString.md
new file mode 100644
index 0000000..9541a35
--- /dev/null
+++ b/http/QueryString.md
@@ -0,0 +1,28 @@
+# class http\QueryString extends http\Object implements Serializable, ArrayAccess, IteratorAggregate
+
+The http\QueryString class provides versatile facilities to retrieve, use and manipulate query strings and form data.
+
+## Constants:
+
+* TYPE_BOOL  
+  Cast requested value to bool.
+* TYPE_INT  
+  Cast requested value to int.
+* TYPE_FLOAT  
+  Cast requested value to float.
+* TYPE_STRING  
+  Cast requested value to string.
+* TYPE_ARRAY  
+  Cast requested value to an array.
+* TYPE_OBJECT  
+  Cast requested value to an object.
+
+
+## Properties:
+
+* private $instance = NULL  
+  The global instance. See http\QueryString::getGlobalInstance().
+* private $queryArray = NULL  
+  The data array.
+
+
diff --git a/http/QueryString/__construct.md b/http/QueryString/__construct.md
new file mode 100644
index 0000000..8a1140b
--- /dev/null
+++ b/http/QueryString/__construct.md
@@ -0,0 +1,30 @@
+# void http\QueryString::__construct([mixed $params = NULL])
+
+Create an independent querystring instance.
+
+## Params:
+
+* Optional mixed $params = NULL  
+  The query parameters to use or parse.
+  
+## Throws:
+
+* http\Exception
+
+## Example:
+
+    $qs = new http\QueryString("foo=bar&a[]=1&a[]=2");
+    print_r($qs->toArray());
+
+Would yield:
+
+    Array
+    (
+        [foo] => bar
+        [a] => Array
+            (
+                [0] => 1
+                [1] => 2
+            )
+    
+    )
diff --git a/http/QueryString/getGlobalInstance.md b/http/QueryString/getGlobalInstance.md
new file mode 100644
index 0000000..1db996a
--- /dev/null
+++ b/http/QueryString/getGlobalInstance.md
@@ -0,0 +1,15 @@
+# static http\QueryString http\QueryString::getGlobalInstance()
+
+Retrieve the global querystring instance referencing $_GET.
+
+## Params:
+
+None.
+
+## Returns:
+
+* http\QueryString, the http\QueryString::$instance
+
+## Throws:
+
+* http\Exception
diff --git a/http/QueryString/getIterator.md b/http/QueryString/getIterator.md
new file mode 100644
index 0000000..ab37865
--- /dev/null
+++ b/http/QueryString/getIterator.md
@@ -0,0 +1,15 @@
+# Iterator http\QueryString::getIterator()
+
+Implements IteratorAggregate.
+
+## Params:
+
+None.
+
+## Returns:
+
+* ```RecursiveArrayIterator```
+
+## Throws:
+
+* http\Exception