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

   1 # pecl/http
   2
   3 ## About:
   4
   5 Extended HTTP support. Again.
   6
   7 * Introduces the http namespace.
   8 * PHP stream based message bodies.
   9 * Encapsulated env request/response.
  10 * Modular client support.
  11
  12 ## Installation:
  13
  14 This extension is hosted at [PECL](http://pecl.php.net) and can be installed with [PEAR](http://pear.php.net)'s pecl command:
  15
  16     # pecl install pecl_http
  17
  18 ## Dependencies:
  19
  20 pecl/http depends on a number of system libraries and PHP extensions for special features.
  21
  22 #### Required system libraries:
  23
  24 The following system libraries are required to build this extension:
  25
  26 =zlib=
  27         Provides gzip/zlib/deflate encoding.
  28         Configure: `--with-http-zlib-dir`
  29         Minimum version: 1.2.0.4
  30         Install on Debian: `apt-get install zlib1g-dev`
  31
  32
  33 #### Optional system libraries:
  34
  35 The following system libraries are optional and provide additional features:
  36
  37 =libcurl=
  38         Provides HTTP request functionality.
  39         Configure: `--with-http-libcurl-dir`
  40         Minimum version: 7.18.2
  41         Install on Debian: `apt-get install libcurl4-openssl-dev`
  42
  43 =libbrotli=
  44         Provides brotli encoding.
  45         Configure: `--with-http-libbrotli-dir`
  46         Minimum version: 1.0
  47         Install on Debian: `apt-get install libbrotli-dev`
  48
  49 =libevent=
  50         Internal event loop support for the HTTP client.
  51         Configure: `--with-http-libevent-dir`
  52         Minimum version: none
  53         Install on Debian: `apt-get install libevent-dev`
  54
  55 =libicu=
  56         Provides IDNA2003 and/or IDNA2008 support in URLs.
  57         Configure: `--with-http-libicu-dir`
  58         Minimum version: none
  59         Install on Debian: `apt-get install libicu-dev`
  60
  61 =libidn=
  62         Provides IDNA2003 support in URLs.
  63         Configure: `--with-http-libidn-dir`
  64         Minimum version: none
  65         Install on Debian: `apt-get install libidn11-dev`
  66
  67 =libidn2=
  68         Provides IDNA2008 support in URLs.
  69         Configure: `--with-http-libidn2-dir`
  70         Minimum version: none
  71         Install on Debian: `apt-get install libidn2-0-dev`
  72
  73 =libidnkit=
  74         Provides IDNA2003 support in URLs. Conflicts with libidnkit2.
  75         Configure: `--with-http-libidnkit-dir`
  76         Minimum version: none
  77         Install on Debian: N/A
  78
  79 =libidnkit2=
  80         Provides IDNA2008 support in URLs. Conflicts with libidnkit.
  81         Configure: `--with-http-libidnkit2-dir`
  82         Minimum version: none
  83         Install on Debian: N/A
  84
  85 ##### A note on IDNA libraries:
  86
  87 If configured with multiple IDNA libraries' support, there's a run-time precedence of ICU over GNU libidn, which in turn has precendence over idnkit. If neither IDNA2008, nor IDNA2003 is explicitly requested, IDNA2008 has precendence.
  88
  89 ##### A note on the CURL library:
  90
  91 There are usually different styles of SSL support for libcurl available, so you can choose between 'openssl' and f.e. 'nss' or 'gnutls' when installing libcurl.
  92
  93 ### PHP extensions:
  94
  95 This extension unconditionally depends on the pre-loaded presence of the following PHP extensions:
  96
  97 * raphf
  98 * propro
  99 * spl
 100
 101
 102 If configured ```--with-http-shared-deps``` (default) it depends on the pre-loaded presence of the following extensions, as long as they were available at build time:
 103
 104 * hash
 105 * iconv
 106 * json (only until < 2.4.0)
 107
 108 Please ensure that all extension on which pecl/http depends, are loaded before it, e.g in your `php.ini`:
 109
 110         ; obligatory deps
 111         extension = raphf.so
 112         extension = propro.so
 113
 114         ; if shared deps were enabled
 115         extension = hash.so
 116         extension = iconv.so
 117         extension = json.so
 118
 119         ; finally load pecl/http
 120         extension = http.so
 121
 122 ## Conflicts:
 123
 124 pecl/http-v2 conflicts with the following extensions:
 125
 126 * http-v1
 127 * event (only until <= 2.0.3)
 128
 129 ## INI Directives:
 130
 131 * http.etag.mode = "crc32b"
 132   Default hash method for dynamic response payloads to generate an ETag.
 133
 134 ## Stream Filters:
 135
 136 The http extension registers the ```http.*``` namespace for its stream filters. Provided stream filters are:
 137
 138 * http.chunked_decode
 139   Decode a stream encoded with chunked transfer encoding.
 140 * http.chunked_encode
 141   Encode a stream with chunked transfer encoding.
 142 * http.inflate
 143   Decode a stream encoded with deflate/zlib/gzip encoding.
 144 * http.deflate
 145   Encode a stream with deflate/zlib/gzip encoding.
 146
 147 ## Changelog:
 148
 149 0. v2.0.4
 150         * Dropped the pecl/event conflict.
 151 0. v2.4.0
 152         * Dropped the ext/json dependency.
 153 0. v2.4.2
 154         * Added libidn2 and libicu as fallback for IDNA support.
 155 0. v2.6.0, v3.1.0
 156         * Added idnkit-1 IDNA2003 support.
 157         * Added idnkit-2 IDNA2008 support.
 158         * Added ICU IDNA2008 support.
 159         * Added explicit configuration options for each IDNA library.
 160 0. v3.2.0
 161         * Added brotli encoding support.