Configuration
List of Configuration Parameters
HTTP_Request2 constructor and HTTP_Request2::setConfig() method accept the following configuration parameters. You can also use HTTP_Request2::getConfig() to get the values of these parameters. Note that using an unknown parameter name will result in an exception.
| Parameter name | Description | Expected type | Default value |
|---|---|---|---|
adapter |
Adapter to use, may also be set by HTTP_Request2::setAdapter() method. (See: Adapters) | string|object | 'HTTP_Request2_Adapter_Socket' |
connect_timeout |
Connection timeout in seconds. Exception will be thrown if connecting to remote host takes more than this number of seconds. | integer | 10 |
timeout |
Total number of seconds a request can take. Use 0 for no limit,
should be greater than connect_timeout if set. Exception will be thrown
if execution of HTTP_Request2::send()
takes more than this number of seconds. |
integer | 0 |
use_brackets |
Whether to append [] to array variable names. This is useful when performing a request to a remote PHP page which expects array parameters to have brackets, should be turned off in the other cases. | boolean | TRUE |
protocol_version |
HTTP protocol version to use, '1.0' or '1.1' |
string | '1.1' |
buffer_size |
Buffer size to use for reading and writing. Leave this at the default unless you know what you are doing. | integer | 16384 |
store_body |
Whether to store response body in response object. Set to false if receiving a huge response and using an Observer to save it. (See: Observers) | boolean | TRUE |
digest_compat_ie |
Whether to imitate behaviour of MSIE 5 and 6 in using URL without query string in digest authentication | boolean | FALSE |
local_ip |
Specifies the IP address that will be used for accessing the network, if the computer running HTTP_Request2 has more than one (since 2.2.0) | string | NULL |
| Parameter name | Description | Expected type | Default value |
|---|---|---|---|
follow_redirects |
Whether to automatically follow HTTP redirects in server response | boolean | FALSE |
max_redirects |
Maximum number of redirects to follow | integer | 5 |
strict_redirects |
Whether to keep request method on redirects via status 301 and
302 (TRUE, needed for compatibility with RFC 2616) or switch to GET
(FALSE, needed for compatibility with most browsers). Issues with Curl Adapter |
boolean | FALSE |
| Parameter name | Description | Expected type | Default value |
|---|---|---|---|
proxy |
Proxy configuration given as an URL, e.g.
'socks5://localhost:1080', URL is parsed and separate parameters
described below are set (since 2.1.0) |
string | N/A |
proxy_type |
Proxy type, either 'http' or 'socks5' (since
2.1.0) |
string | 'http' |
proxy_host |
Proxy server host | string | '' |
proxy_port |
Proxy server port | integer | '' |
proxy_user |
User name for proxy authentication | string | '' |
proxy_password |
Password for proxy authentication | string | '' |
proxy_auth_scheme |
Proxy authentication scheme, one of HTTP_Request2::AUTH_* constants | string | HTTP_Request2::AUTH_BASIC |
| Parameter name | Description | Expected type | Default value |
|---|---|---|---|
ssl_verify_peer |
Whether to verify peer's SSL certificate. Note that this is on by default, to follow
the behaviour of modern browsers and current cURL version.
Peer verification is likely to fail if you don't explicitly provide |
boolean | TRUE |
ssl_verify_host |
Whether to check that Common Name in SSL certificate matches host name. Issues with Socket Adapter. | boolean | TRUE |
ssl_cafile |
Certificate Authority file to verify the peer with (use when
ssl_verify_peer is TRUE)
You can use e.g. cURL's CA Extract tool to get such a file. |
string | NULL |
ssl_capath |
Directory holding multiple Certificate Authority files | string | NULL |
ssl_local_cert |
Name of a file containing local certificate | string | NULL |
ssl_passphrase |
Passphrase with which local certificate was encoded | string | NULL |
Proxy Configuration
While most of the configuration parameters have sane default values and generally can be left alone, you'll definitely need to configure proxy you are using to access websites.
Proxy configuration example
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setConfig(array(
'proxy_host' => 'proxy.example.com',
'proxy_port' => 3128,
'proxy_user' => 'luser',
'proxy_password' => 'sekret',
'proxy_auth_scheme' => HTTP_Request2::AUTH_DIGEST
));
// Now you can perform requests
?>
SSL peer verification issues
For SSL peer verification to work, OpenSSL library (used under the hood by both Curl and Socket adapter) needs certificate authority files. However it does not include any such files itself, expecting OS distributions compiling OpenSSL library to provide proper default locations.
Unfortunately OpenSSL extension of PHP below version 5.6 does not
try to use the distribution-default values for CA file / CA path when explicit ones
are not provided. Curl extension, however, does use these defaults, so you can sometimes
be able to use 'verify_peer' without setting 'ssl_cafile'
for Curl adapter, but not for Socket one (see e.g. bug #18480 and bug #19351).
For versions of PHP below 5.6 the only solution is to provide 'ssl_cafile'
and / or 'ssl_capath' for every request if using
Socket adapter. Curl adapter will or
will not be able to use the defaults depending on distribution, additionally you can set
curl.cainfo parameter in php.ini on PHP 5.3.7+
(it contains the default value for CURLOPT_CAINFO setting to which
'ssl_cafile' setting is mapped).
PHP version 5.6 will finally enable peer verification by default
for 'ssl' stream wrapper, so it will also provide more possibilities for
using default values:
- PHP will use defaults compiled into the OpenSSL library by distribution.
-
openssl.cafileandopenssl.capathsettings inphp.iniwill provide default values for'cafile'and'capath'SSL stream context options ('ssl_cafile'and'ssl_capath'settings map to these in Socket adapter).