# 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:
# 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.
-# 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.
+
--- /dev/null
+# 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
+ )
+ )
+ );
--- /dev/null
+# 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.
--- /dev/null
+# 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.
--- /dev/null
+# class http\Exception extends Exception
+
+The http extension's Exception.
--- /dev/null
+# 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.
+
+
--- /dev/null
+# 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
+ )
+
+ )
--- /dev/null
+# 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
--- /dev/null
+# Iterator http\QueryString::getIterator()
+
+Implements IteratorAggregate.
+
+## Params:
+
+None.
+
+## Returns:
+
+* ```RecursiveArrayIterator```
+
+## Throws:
+
+* http\Exception
projects / mdref / mdref-http / commitdiff
