From 7823a35136269030a351b68b8ae8ee5026696aea Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Wed, 30 Oct 2013 10:02:36 +0100 Subject: [PATCH] initialize --- http/Env.md | 11 +++++ http/Env/Request.md | 14 ++++++ http/Env/Request/__construct.md | 0 http/Env/getRequestBody.md | 16 +++++++ http/Env/getRequestHeader.md | 14 ++++++ http/Env/getResponseCode.md | 12 +++++ http/Env/getResponseHeader.md | 14 ++++++ http/Env/getResponseStatusForAllCodes.md | 15 +++++++ http/Env/getResponseStatusForCode.md | 14 ++++++ http/Env/negotiate.md | 21 +++++++++ http/Env/negotiateCharset.md | 17 +++++++ http/Env/negotiateContentType.md | 56 ++++++++++++++++++++++++ http/Env/negotiateEncoding.md | 17 +++++++ http/Env/negotiateLanguage.md | 17 +++++++ http/Env/setResoponseCode.md | 12 +++++ http/Env/setResponseHeader.md | 18 ++++++++ http/Header.md | 23 ++++++++++ http/Header/__construct.md | 14 ++++++ http/Header/__toString.md | 11 +++++ http/Header/getParams.md | 18 ++++++++ http/Header/match.md | 14 ++++++ http/Header/negotiate.md | 21 +++++++++ http/Header/parse.md | 14 ++++++ http/Header/serialize.md | 11 +++++ http/Header/toString.md | 11 +++++ http/Header/unserialize.md | 9 ++++ http/Params.md | 37 ++++++++++++++++ http/Params/__construct.md | 21 +++++++++ http/Params/__toString.md | 12 +++++ http/Params/offsetExists.md | 12 +++++ http/Params/offsetGet.md | 12 +++++ http/Params/offsetSet.md | 11 +++++ http/Params/offsetUnset.md | 9 ++++ http/Params/toArray.md | 11 +++++ http/Params/toString.md | 11 +++++ 35 files changed, 550 insertions(+) create mode 100644 http/Env.md create mode 100644 http/Env/Request.md create mode 100644 http/Env/Request/__construct.md create mode 100644 http/Env/getRequestBody.md create mode 100644 http/Env/getRequestHeader.md create mode 100644 http/Env/getResponseCode.md create mode 100644 http/Env/getResponseHeader.md create mode 100644 http/Env/getResponseStatusForAllCodes.md create mode 100644 http/Env/getResponseStatusForCode.md create mode 100644 http/Env/negotiate.md create mode 100644 http/Env/negotiateCharset.md create mode 100644 http/Env/negotiateContentType.md create mode 100644 http/Env/negotiateEncoding.md create mode 100644 http/Env/negotiateLanguage.md create mode 100644 http/Env/setResoponseCode.md create mode 100644 http/Env/setResponseHeader.md create mode 100644 http/Header.md create mode 100644 http/Header/__construct.md create mode 100644 http/Header/__toString.md create mode 100644 http/Header/getParams.md create mode 100644 http/Header/match.md create mode 100644 http/Header/negotiate.md create mode 100644 http/Header/parse.md create mode 100644 http/Header/serialize.md create mode 100644 http/Header/toString.md create mode 100644 http/Header/unserialize.md create mode 100644 http/Params.md create mode 100644 http/Params/__construct.md create mode 100644 http/Params/__toString.md create mode 100644 http/Params/offsetExists.md create mode 100644 http/Params/offsetGet.md create mode 100644 http/Params/offsetSet.md create mode 100644 http/Params/offsetUnset.md create mode 100644 http/Params/toArray.md create mode 100644 http/Params/toString.md diff --git a/http/Env.md b/http/Env.md new file mode 100644 index 0000000..d75dbf2 --- /dev/null +++ b/http/Env.md @@ -0,0 +1,11 @@ +# class http\Env extends http\Object + +The http\Env class provides static methods to manipulate and inspect the server's current request's HTTP environment. + +## Request startup + +The http\Env module overrides PHP's builtin POST data parser to be run also if +the request method is not POST. Additionally it will handle +```application/json``` payloads if ```ext/json``` is available. Successfully +parsed JSON will be put right into the $_POST array. + diff --git a/http/Env/Request.md b/http/Env/Request.md new file mode 100644 index 0000000..5c4b32f --- /dev/null +++ b/http/Env/Request.md @@ -0,0 +1,14 @@ +# class http\Env\Request extends http\Message + +## Constants: + +> None. + +## Properties: + +* ```protected $query = NULL``` + The request's query parameters. ($_GET) +* ```protected $form = NULL``` + The request's form parameters. ($_POST) +* ```protected $files = NULL``` + The request's form uploads. ($_FILES) diff --git a/http/Env/Request/__construct.md b/http/Env/Request/__construct.md new file mode 100644 index 0000000..e69de29 diff --git a/http/Env/getRequestBody.md b/http/Env/getRequestBody.md new file mode 100644 index 0000000..512128d --- /dev/null +++ b/http/Env/getRequestBody.md @@ -0,0 +1,16 @@ +# static http\Message\Body http\Env::getRequestBody([string $body_class_name]) + +Retreive the current HTTP request's body. + +## Parameters: + +* Optional ```string $body_class_name``` + A user class extending http\Body. + +## Returns: + +* ```http\Message\Body``` instance representing the request body + +## Throws: + +* http\Exception diff --git a/http/Env/getRequestHeader.md b/http/Env/getRequestHeader.md new file mode 100644 index 0000000..b33718b --- /dev/null +++ b/http/Env/getRequestHeader.md @@ -0,0 +1,14 @@ +# static mixed http\Env::getRequestHeader([string $header_name]) + +Retrieve one or all headers of the current HTTP request. + +## Parameters: + +* Optional ```string $header_name``` + The key of a header to retrieve. + +## Returns: + +* ```NULL```, if $header_name was not found +* ```string```, the compound header when $header_name was found +* ```array``` of all headers if $header_name was not specified diff --git a/http/Env/getResponseCode.md b/http/Env/getResponseCode.md new file mode 100644 index 0000000..11feca8 --- /dev/null +++ b/http/Env/getResponseCode.md @@ -0,0 +1,12 @@ +# static int http\Env::getResponseCode() + +Get the HTTP response code to send. + +## Parameters: + +> None. + +## Returns: + +* ```int```, the HTTP response code. + diff --git a/http/Env/getResponseHeader.md b/http/Env/getResponseHeader.md new file mode 100644 index 0000000..c30a4d7 --- /dev/null +++ b/http/Env/getResponseHeader.md @@ -0,0 +1,14 @@ +# static mixed http\Env::getResponseHeader([string $header_name]) + +Get one or all HTTP response headers to be sent. + +## Parameters: + +* Optional ```string $header_name``` + The name of the response header to retrieve. + +## Returns: + +* ```string```, the compound value of the response header to send +* ```NULL```, if the header was not found +* ```array```, of all response headers, if $header_name was not specified diff --git a/http/Env/getResponseStatusForAllCodes.md b/http/Env/getResponseStatusForAllCodes.md new file mode 100644 index 0000000..2e37783 --- /dev/null +++ b/http/Env/getResponseStatusForAllCodes.md @@ -0,0 +1,15 @@ +# static array http\Env::getResponseStatusForAllCodes() + +Retrieve a list of all known HTTP response status. + +## Parameters: + +> None. + +## Returns: + +* ```array``` mapping of the form \[ + ... + ```int $code``` => ```string $status``` + ... + \] diff --git a/http/Env/getResponseStatusForCode.md b/http/Env/getResponseStatusForCode.md new file mode 100644 index 0000000..d2bfa85 --- /dev/null +++ b/http/Env/getResponseStatusForCode.md @@ -0,0 +1,14 @@ +# static string http\Env::getResponseStatusForCode(int $code) + +Retrieve the string representation of specified HTTP response code. + +## Parameters: + +* ```int $code``` + The HTTP response code to get the string representation for. + +## Returns: + +* ```string```, the HTTP response status message +* empty ```string```, if no message for this code was found + diff --git a/http/Env/negotiate.md b/http/Env/negotiate.md new file mode 100644 index 0000000..0230bc6 --- /dev/null +++ b/http/Env/negotiate.md @@ -0,0 +1,21 @@ +# static string http\Env::negotiate(string $params, array $supported[, string $prim_typ_sep[, array &$result]]) + +Generic negotiator. For specific client negotiation see http\Env::negotiateContentType() and related methods. + +> ***NOTE:*** The first elemement of $supported serves as a default if no operand matches. + +## Params: + +* ```string $params``` + HTTP header parameter's value to negotiate. +* ```array $supported``` + List of supported negotiation operands. +* Optional ```string $prim_typ_sep``` + A "primary type separator", i.e. that would be a hyphen for content language negotiation (en-US, de-DE, etc.). +* Optional reference ```array &$result``` + Out parameter recording negotiation results. + +## Returns: + +* ```NULL```, if negotiation fails. +* ```string```, the closest match negotiated, or the default (first entry of $supported). diff --git a/http/Env/negotiateCharset.md b/http/Env/negotiateCharset.md new file mode 100644 index 0000000..20cc01b --- /dev/null +++ b/http/Env/negotiateCharset.md @@ -0,0 +1,17 @@ +# static string http\Env::negotiateCharset(array $supported[, array &$result) + +Negotiate the client's preferred character set. + +> ***NOTE:*** The first elemement of $supported character sets serves as a default if no character set matches. + +## Params: + +* ```array $supported``` + List of supported content character sets. +* Optional reference ```array &$result``` + Out parameter recording negotiation results. + +## Returns: + +* ```NULL```, if negotiation fails. +* ```string```, the negotiated character set. diff --git a/http/Env/negotiateContentType.md b/http/Env/negotiateContentType.md new file mode 100644 index 0000000..510e33f --- /dev/null +++ b/http/Env/negotiateContentType.md @@ -0,0 +1,56 @@ +# static string http\Env::negotiateContentType(array $supported[, array &$result) + +Negotiate the client's preferred MIME content type. + +> ***NOTE:*** The first elemement of $supported content types serves as a default if no content-type matches. + +## Params: + +* ```array $supported``` + List of supported MIME content types. +* Optional reference ```array &$result``` + Out parameter recording negotiation results. + +## Returns: + +* ```NULL```, if negotiation fails. +* ```string```, the negotiated content type. + +## Example: + +A client indicates his accepted MIME content types by sending an ```Accept``` +header. The static ```http\Env``` class provides a facility to negotiate the +client's preferred content type: + + + +Running this script should give the following output: + + string(9) "text/html" + array(3) { + 'text/html' => + float(0.99) + 'text/plain' => + float(0.98) + 'application/json' => + float(0.1) + } + + + diff --git a/http/Env/negotiateEncoding.md b/http/Env/negotiateEncoding.md new file mode 100644 index 0000000..4c070b7 --- /dev/null +++ b/http/Env/negotiateEncoding.md @@ -0,0 +1,17 @@ +# static string http\Env::negotiateEncoding(array $supported[, array &$result) + +Negotiate the client's preferred encoding. + +> ***NOTE:*** The first elemement of $supported encodings serves as a default if no encoding matches. + +## Params: + +* ```array $supported``` + List of supported content encodings. +* Optional reference ```array &$result``` + Out parameter recording negotiation results. + +## Returns: + +* ```NULL```, if negotiation fails. +* ```string```, the negotiated encoding. diff --git a/http/Env/negotiateLanguage.md b/http/Env/negotiateLanguage.md new file mode 100644 index 0000000..3baf48a --- /dev/null +++ b/http/Env/negotiateLanguage.md @@ -0,0 +1,17 @@ +# static string http\Env::negotiateLanguage(array $supported[, array &$result) + +Negotiate the client's preferred language. + +> ***NOTE:*** The first elemement of $supported languages serves as a default if no language matches. + +## Params: + +* ```array $supported``` + List of supported content languages. +* Optional reference ```array &$result``` + Out parameter recording negotiation results. + +## Returns: + +* ```NULL```, if negotiation fails. +* ```string```, the negotiated language. diff --git a/http/Env/setResoponseCode.md b/http/Env/setResoponseCode.md new file mode 100644 index 0000000..376a13d --- /dev/null +++ b/http/Env/setResoponseCode.md @@ -0,0 +1,12 @@ +# static bool http\Env::setResponseCode(int $code) + +Set the HTTP response code to send. + +## Params: + +* ```int $code``` + The HTTP response status code. + +## Returns: + +* ```bool``` Success. diff --git a/http/Env/setResponseHeader.md b/http/Env/setResponseHeader.md new file mode 100644 index 0000000..69adfa3 --- /dev/null +++ b/http/Env/setResponseHeader.md @@ -0,0 +1,18 @@ +# static bool http\Env::setResponseHeader(string $header_name, [mixed $header_value = NULL[, int $response_code = 0[, bool $replace = true]]] + +Set a response header, either replacing a prior set header, or appending the new header value, depending on $replace. + +If no $header_value is specified, or $header_value is ```NULL```, then a previously set header with the same key will be deleted from the list. + +If $response_code is not ```0```, the response status code is updated accordingly. + +## Parameters: + +* ```string $header_name```, the name of the response header. +* Optional ```mixed $header_value```, the header value. +* Optional ```int $response_code```, any HTTP response status code to set. +* Optional ```bool $replace```, whether to replace a previously set response header with the same name. + +## Returns: + +* ```bool``` Success. diff --git a/http/Header.md b/http/Header.md new file mode 100644 index 0000000..101b0dc --- /dev/null +++ b/http/Header.md @@ -0,0 +1,23 @@ +# class http\Header extends http\Object implements Serializable + +The http\Header class provides methods to manipulate, match, negotiate and serialize HTTP headers. + +## Constants: + +* ```MATCH_LOOSE``` + None of the following match constraints applies. +* ```MATCH_CASE``` + Perform case sensitive matching. +* ```MATCH_WORD``` + Match only on word boundaries (according by CTYPE alpha-numeric). +* ```MATCH_FULL``` + Match the complete string. +* ```MATCH_STRICT``` + Case sensitively match the full string (same as ```MATCH_CASE|MATCH_FULL```). + +## Properties: + +* ```public $name = NULL``` + The name of the HTTP header. +* ```public $value = NULL``` + The value of the HTTP header. diff --git a/http/Header/__construct.md b/http/Header/__construct.md new file mode 100644 index 0000000..c477ab3 --- /dev/null +++ b/http/Header/__construct.md @@ -0,0 +1,14 @@ +# void http\Header::__construct([string $name[, mixed $value]]) + +Create an http\Header instance for use of simple matching or negotiation. If the value of the header is an array it may be compounded to a single comma separated string. + +## Params: + +* Optional ```string $name``` + The HTTP header name. +* Optional ```mixed $value``` + The value of the header. + +# Throws: + +* http\Exception diff --git a/http/Header/__toString.md b/http/Header/__toString.md new file mode 100644 index 0000000..602768a --- /dev/null +++ b/http/Header/__toString.md @@ -0,0 +1,11 @@ +# string http\Header::__toString() + +String cast handler. Alias of http\Header::serialize(). + +## Params: + +> None. + +## Returns: + +* ```string```, the serialized form of the HTTP header (i.e. "Name: value"). diff --git a/http/Header/getParams.md b/http/Header/getParams.md new file mode 100644 index 0000000..d3645c2 --- /dev/null +++ b/http/Header/getParams.md @@ -0,0 +1,18 @@ +# http\Params http\Header::getParams([mixed $ps = ","[, mixed $as = ";"[, mixed $vs = "="[, int $flags = http\Params::PARSE_DEFAULT]]]]) + +Create a parameter list out of the HTTP header value. + +## Params: + +* Optional ```mixed $ps``` + The parameter separator(s). +* Optional ```mixed $as``` + The argument separator(s). +* Optional ```mixed``` + The value separator(s). +* Optional ```int $flags``` + The modus operandi. See http\Params constants. + +## Returns: + +* ```http\Params``` instance diff --git a/http/Header/match.md b/http/Header/match.md new file mode 100644 index 0000000..7635cd2 --- /dev/null +++ b/http/Header/match.md @@ -0,0 +1,14 @@ +# bool http\Header::match(string $value[, int $flags = http\Header::MATCH_LOOSE]) + +Match the HTTP header's value against provided $value according to $flags. + +## Params: + +* ```string $value``` + The comparison value. +* Optional ```int $flags``` + The modus operandi. See http\Header constants. + +## Returns: + +* ```bool```, whether $value matches the header value according to $flags. diff --git a/http/Header/negotiate.md b/http/Header/negotiate.md new file mode 100644 index 0000000..af0547f --- /dev/null +++ b/http/Header/negotiate.md @@ -0,0 +1,21 @@ +# string http\Header::negotiate(array $supported[, array &$result]) + +Negotiate the header's value against a list of supported values in $supported. +Negotiation operation is adopted according to the header name, i.e. if the +header being negotiated is ```Accept```, then a slash is used as primary type +separator, and if the header is ```Accept-Language``` respectively, a hyphen is +used instead. + +> ***NOTE:*** The first elemement of $supported serves as a default if no operand matches. + +## Params: + +* ```array $supported``` + The list of supported values to negotiate. +* Optional reference ```array &$result``` + Out parameter recording the negotiation results. + +## Returns: + +* ```NULL```, if negotiation fails. +* ```string```, the closest match negotiated, or the default (first entry of $supported). diff --git a/http/Header/parse.md b/http/Header/parse.md new file mode 100644 index 0000000..c1965c1 --- /dev/null +++ b/http/Header/parse.md @@ -0,0 +1,14 @@ +# static array http\Header::parse(string $header[, string $header_class = null]) + +Parse HTTP headers. + +## Params: + +* ```string $header``` + The complete string of headers. +* Optional ```string $header_class``` + A class extending http\Header. + +## Returns: + +* ```array``` of parsed headers, where the elements are instances of $header_class if specified. diff --git a/http/Header/serialize.md b/http/Header/serialize.md new file mode 100644 index 0000000..2afe46e --- /dev/null +++ b/http/Header/serialize.md @@ -0,0 +1,11 @@ +# string http\Header::serialize() + +Implements Serializable. + +## Params: + +> None. + +## Returns: + +* ```string```, serialized representation of HTTP header (i.e. "Name: value") diff --git a/http/Header/toString.md b/http/Header/toString.md new file mode 100644 index 0000000..2eec780 --- /dev/null +++ b/http/Header/toString.md @@ -0,0 +1,11 @@ +# string http\Header::toString() + +Convenience method. Alias of http\Header::serialize(). + +## Params: + +> None. + +## Returns: + +* ```string```, the serialized form of the HTTP header (i.e. "Name: value"). diff --git a/http/Header/unserialize.md b/http/Header/unserialize.md new file mode 100644 index 0000000..2ccd6c4 --- /dev/null +++ b/http/Header/unserialize.md @@ -0,0 +1,9 @@ +# void http\Header::unserialize(string $serialized) + +Implements Serializable. + +## Params: + +* ```string $serialized``` + The serialized HTTP header (i.e. "Name: value") + diff --git a/http/Params.md b/http/Params.md new file mode 100644 index 0000000..f479223 --- /dev/null +++ b/http/Params.md @@ -0,0 +1,37 @@ +# class http\Params extends http\Object implements ArrayAccess + +Parse, interpret and compose HTTP (header) parameters. + +## Constants: + +* ```DEF_PARAM_SEP``` + The default parameter separator (","). +* ```DEF_ARG_SEP``` + The default argument separator (";"). +* ```DEF_VAL_SEP``` + The default value separator ("="). +* ```COOKIE_PARAM_SEP``` + TBD +* ```PARSE_RAW``` + Do not interpret the parsed parameters. +* ```PARSE_DEFAULT``` + Interpret input as default formatted parameters. +* ```PARSE_URLENCODED``` + Urldecode single units of parameters, arguments and values. +* ```PARSE_DIMENSION``` + Parse sub dimensions indicated by square brackets. +* ```PARSE_QUERY``` + Parse URL query string (same as http\Params::PARSE_URLENCODED|http\Params::PARSE_DIMENSION). + +## Properties: + +* ```public $params = NULL``` + The (parsed) parameters. +* ```public $param_sep = http\Header::DEF_PARAM_SEP``` + The parameter separator(s). +* ```public $arg_sep = http\Header::DEF_ARG_SEP``` + The argument separator(s). +* ```public $val_sep = http\Header::DEF_VAL_SEP``` + The value separator(s). +* ```public $flags = http\Params::PARSE_DEFAULT``` + The modus operandi of the parser. See http\Params::PARSE_* constants. diff --git a/http/Params/__construct.md b/http/Params/__construct.md new file mode 100644 index 0000000..76034a9 --- /dev/null +++ b/http/Params/__construct.md @@ -0,0 +1,21 @@ +# void http\Params::__construct([mixed $params = NULL[, mixed $ps = http\Params::DEF_PARAM_SEP[, mixed $as = http\Params::DEF_ARG_SEP[, mixed $vs = http\Params::DEF_VAL_SEP[, int $flags = http\Params::PARSE_DEFAULT]]]]]) + +Instantiate a new HTTP (header) parameter set. + +## Params: + +* Optional ```mixed $params``` + Pre-parsed parameters or a string to be parsed. +* Optional ```mixed $ps``` + The parameter separator(s). +* Optional ```mixed $as``` + The argument separator(s). +* Optional ```mixed $vs``` + The value separator(s). +* Optional ```int $flags``` + The modus operandi. See http\Params::PARSE_* constants. + +## Throws: + +* http\Exception + diff --git a/http/Params/__toString.md b/http/Params/__toString.md new file mode 100644 index 0000000..c1bd91c --- /dev/null +++ b/http/Params/__toString.md @@ -0,0 +1,12 @@ +# string http\Params::__toString() + +String cast handler. Alias of http\Params::toString(). +Returns a stringified version of the parameters. + +## Params: + +> None. + +## Returns: + +* ```string``` version of the parameters. diff --git a/http/Params/offsetExists.md b/http/Params/offsetExists.md new file mode 100644 index 0000000..b3d7b29 --- /dev/null +++ b/http/Params/offsetExists.md @@ -0,0 +1,12 @@ +# bool http\Params::offsetExists(string $name) + +Implements ArrayAccess. + +## Params: + +* ```string $name``` + The offset to look after. + +## Returns: + +* ```bool``` Existence. diff --git a/http/Params/offsetGet.md b/http/Params/offsetGet.md new file mode 100644 index 0000000..cc96a9a --- /dev/null +++ b/http/Params/offsetGet.md @@ -0,0 +1,12 @@ +# mixed http\Params::offsetGet(string $name) + +Implements ArrayAccess. + +## Params: + +* ```string $name``` + The offset to retrieve. + +## Returns: + +* ```mixed```, contents at offset. diff --git a/http/Params/offsetSet.md b/http/Params/offsetSet.md new file mode 100644 index 0000000..4a24d41 --- /dev/null +++ b/http/Params/offsetSet.md @@ -0,0 +1,11 @@ +# void http\Params::offsetSet(string $name, mixed $value) + +Implements ArrayAccess. + +## Params: + +* ```string $name``` + The offset to modify. +* ```mixed $value``` + The value to set. + diff --git a/http/Params/offsetUnset.md b/http/Params/offsetUnset.md new file mode 100644 index 0000000..4c5af78 --- /dev/null +++ b/http/Params/offsetUnset.md @@ -0,0 +1,9 @@ +# void http\Params::offsetUnset(string $name) + +Implements ArrayAccess. + +## Params: + +* ```string $name``` + The offset to delete. + diff --git a/http/Params/toArray.md b/http/Params/toArray.md new file mode 100644 index 0000000..e7ca841 --- /dev/null +++ b/http/Params/toArray.md @@ -0,0 +1,11 @@ +# array http\Params::toArray() + +Convenience method that simply returns http\Params::$params. + +## Params: + +> None. + +## Returns: + +* ```array``` of paramters. diff --git a/http/Params/toString.md b/http/Params/toString.md new file mode 100644 index 0000000..34400be --- /dev/null +++ b/http/Params/toString.md @@ -0,0 +1,11 @@ +# string http\Params::toString() + +Returns a stringified version of the parameters. + +## Params: + +> None. + +## Returns: + +* ```string``` version of the parameters. -- 2.30.2