From d5af35badf0c029ba85f9b53b78bcd5a01907a8d Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Thu, 31 Oct 2013 15:54:56 +0100 Subject: [PATCH] flush --- http.md | 13 +++++++- http/Env/Request.md | 4 +++ http/Env/Request/__construct.md | 9 ++++-- http/Env/Request/getFiles.md | 45 +++++++++++++++++++++++++++ http/Env/Request/getForm.md | 25 +++++++++++++++ http/Env/Request/getQuery.md | 25 +++++++++++++++ http/Exception.md | 3 ++ http/QueryString.md | 28 +++++++++++++++++ http/QueryString/__construct.md | 30 ++++++++++++++++++ http/QueryString/getGlobalInstance.md | 15 +++++++++ http/QueryString/getIterator.md | 15 +++++++++ 11 files changed, 209 insertions(+), 3 deletions(-) create mode 100644 http/Env/Request/getFiles.md create mode 100644 http/Env/Request/getForm.md create mode 100644 http/Env/Request/getQuery.md create mode 100644 http/Exception.md create mode 100644 http/QueryString.md create mode 100644 http/QueryString/__construct.md create mode 100644 http/QueryString/getGlobalInstance.md create mode 100644 http/QueryString/getIterator.md 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 -- 2.30.2