Configuration

Configuration – Configuration parameters for HTTP_Request2

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.

Common parameters
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
Redirect parameters
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
Proxy parameters
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
SSL parameters
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 ssl_cafile and/or ssl_capath, especially with Socket adapter.
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.cafile and openssl.capath settings in php.ini will provide default values for 'cafile' and 'capath' SSL stream context options ('ssl_cafile' and 'ssl_capath' settings map to these in Socket adapter).