git.m6w6.name Git - mdref/mdref-http/blob - http/Params.md

   1 # class http\Params implements ArrayAccess
   2
   3 Parse, interpret and compose HTTP (header) parameters.
   4
   5 ## Changelog:
   6
   7 Version | Change
   8 --------|-------
   9 2.1.0   | Added [RFC5987](http://tools.ietf.org/html/rfc5987) support
  10 2.5.0   | Added [RFC5988](http://tools.ietf.org/html/rfc5987) support
  11
  12 ## Example:
  13
  14         <?php
  15
  16         $u = urlencode("ü");
  17         $s = urlencode("ß");
  18
  19         $t = "p1*=utf-8'de's$u$s,p2*=utf-8''hei$s;a1*=utf-8''a$s;a2*=utf-8''e$s;a3=no,p3=not";
  20         $p = new http\Params($t);
  21
  22         var_dump($p->params, $p->toString());
  23
  24         ?>
  25
  26 Yields:
  27
  28         array(3) {
  29                 ["p1"]=>
  30                 array(2) {
  31                         ["*rfc5987*"]=>
  32                         array(1) {
  33                           ["de"]=>
  34                           string(5) "süß"
  35                         }
  36                         ["arguments"]=>
  37                         array(0) {
  38                         }
  39                 }
  40                 ["p2"]=>
  41                 array(2) {
  42                         ["*rfc5987*"]=>
  43                         array(1) {
  44                           [""]=>
  45                           string(5) "heiß"
  46                         }
  47                         ["arguments"]=>
  48                         array(2) {
  49                                 ["*rfc5987*"]=>
  50                                 array(2) {
  51                                         ["a1"]=>
  52                                         array(1) {
  53                                           [""]=>
  54                                           string(3) "aß"
  55                                         }
  56                                         ["a2"]=>
  57                                         array(1) {
  58                                           [""]=>
  59                                           string(3) "eß"
  60                                         }
  61                                 }
  62                                 ["a3"]=>
  63                                 string(2) "no"
  64                         }
  65                 }
  66                 ["p3"]=>
  67                 array(2) {
  68                         ["value"]=>
  69                         string(3) "not"
  70                         ["arguments"]=>
  71                         array(0) {
  72                         }
  73                 }
  74         }
  75         string(98) "p1*=utf-8'de's%C3%BC%C3%9F,p2*=utf-8''hei%C3%9F;a1*=utf-8''a%C3%9F;a2*=utf-8''e%C3%9F;a3=no,p3=not"
  76
  77 ## Web Linking Example:
  78
  79         $link = <<<EOF
  80         Link: </TheBook/chapter2>;
  81                          rel="previous"; title*=UTF-8'de'letztes%20Kapitel,
  82                          </TheBook/chapter4>;
  83                          rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel
  84         EOF;
  85
  86         $p = current(http\Header::parse($link, "http\\Header"))->getParams(
  87                 http\Params::DEF_PARAM_SEP,
  88                 http\Params::DEF_ARG_SEP,
  89                 http\Params::DEF_VAL_SEP,
  90                 http\Params::PARSE_RFC5988 | http\Params::PARSE_ESCAPED
  91         );
  92
  93         var_dump($p->params);
  94         var_dump((string)$p);
  95
  96 Yields:
  97
  98         array(2) {
  99           ["/TheBook/chapter2"]=>
 100           array(2) {
 101                 ["value"]=>
 102                 bool(true)
 103                 ["arguments"]=>
 104                 array(2) {
 105                   ["rel"]=>
 106                   string(8) "previous"
 107                   ["*rfc5987*"]=>
 108                   array(1) {
 109                         ["title"]=>
 110                         array(1) {
 111                           ["de"]=>
 112                           string(15) "letztes Kapitel"
 113                         }
 114                   }
 115                 }
 116           }
 117           ["/TheBook/chapter4"]=>
 118           array(2) {
 119                 ["value"]=>
 120                 bool(true)
 121                 ["arguments"]=>
 122                 array(2) {
 123                   ["rel"]=>
 124                   string(4) "next"
 125                   ["*rfc5987*"]=>
 126                   array(1) {
 127                         ["title"]=>
 128                         array(1) {
 129                           ["de"]=>
 130                           string(17) "nächstes Kapitel"
 131                         }
 132                   }
 133                 }
 134           }
 135         }
 136         string(139) "</TheBook/chapter2>;rel="previous";title*=utf-8'de'letztes%20Kapitel,</TheBook/chapter4>;rel="next";title*=utf-8'de'n%C3%A4chstes%20Kapitel"
 137
 138 ## Constants:
 139
 140 * DEF_PARAM_SEP
 141   The default parameter separator (",").
 142 * DEF_ARG_SEP
 143   The default argument separator (";").
 144 * DEF_VAL_SEP
 145   The default value separator ("=").
 146 * COOKIE_PARAM_SEP
 147   Empty param separator to parse cookies.
 148 * PARSE_RAW
 149   Do not interpret the parsed parameters.
 150 * PARSE_DEFAULT
 151   Interpret input as default formatted parameters.
 152 * PARSE_URLENCODED
 153   Urldecode single units of parameters, arguments and values.
 154 * PARSE_DIMENSION
 155   Parse sub dimensions indicated by square brackets.
 156 * PARSE_QUERY
 157   Parse URL querystring (same as http\Params::PARSE_URLENCODED|http\Params::PARSE_DIMENSION).
 158 * PARSE_RFC5987
 159   Parse [RFC5987](http://tools.ietf.org/html/rfc5987) style encoded character set and language information embedded in HTTP header params.
 160 * PARSE_RFC5988
 161   Parse [RFC5988](http://tools.ietf.org/html/rfc5988) (Web Linking) tags of Link headers.
 162
 163 ## Properties:
 164
 165 * public array $params = NULL
 166   The (parsed) parameters.
 167 * public array $param_sep = http\Params::DEF_PARAM_SEP
 168   The parameter separator(s).
 169 * public array $arg_sep = http\Params::DEF_ARG_SEP
 170   The argument separator(s).
 171 * public array $val_sep = http\Params::DEF_VAL_SEP
 172   The value separator(s).
 173 * public int $flags = http\Params::PARSE_DEFAULT
 174   The modus operandi of the parser. See http\Params::PARSE_* constants.