MediaWiki  master
MultiHttpClient Class Reference

Class to handle multiple HTTP requests. More...

Inheritance diagram for MultiHttpClient:
Collaboration diagram for MultiHttpClient:

Public Member Functions

 __construct (array $options)
 
 __destruct ()
 
 run (array $req, array $opts=[])
 Execute an HTTP(S) request. More...
 
 runMulti (array $reqs, array $opts=[])
 Execute a set of HTTP(S) requests. More...
 
 setLogger (LoggerInterface $logger)
 Register a logger. More...
 

Public Attributes

const TIMEOUT_ACCURACY_FACTOR = 0.1
 

Protected Member Functions

 getCurlHandle (array &$req, array $opts)
 
 getCurlMulti (array $opts)
 
 isCurlEnabled ()
 Determines if the curl extension is available. More...
 

Protected Attributes

string null $caBundlePath
 SSL certificates path. More...
 
resource $cmh
 curl_multi_init() handle More...
 
float $connTimeout = 10
 
LoggerInterface $logger
 
int $maxConnsPerHost = 50
 
string null $proxy
 proxy More...
 
float $reqTimeout = 900
 
bool $usePipelining = false
 
string $userAgent = 'wikimedia/multi-http-client v1.0'
 

Private Member Functions

 getSelectTimeout ( $opts)
 Get a suitable select timeout for the given options. More...
 
 normalizeRequests (array &$reqs)
 Normalize request information. More...
 
 runMultiCurl (array $reqs, array $opts)
 Execute a set of HTTP(S) requests concurrently. More...
 
 runMultiHttp (array $reqs, array $opts=[])
 Execute a set of HTTP(S) requests sequentially. More...
 

Detailed Description

Class to handle multiple HTTP requests.

If curl is available, requests will be made concurrently. Otherwise, they will be made serially.

HTTP request maps are arrays that use the following format:

  • method : GET/HEAD/PUT/POST/DELETE
  • url : HTTP/HTTPS URL
  • query : <query parameter field/value associative array> (uses RFC 3986)
  • headers : <header name/value associative array>
  • body : source to get the HTTP request body from; this can simply be a string (always), a resource for PUT requests, and a field/value array for POST request; array bodies are encoded as multipart/form-data and strings use application/x-www-form-urlencoded (headers sent automatically)
  • stream : resource to stream the HTTP response body to
  • proxy : HTTP proxy to use
  • flags : map of boolean flags which supports:
    • relayResponseHeaders : write out header via header() Request maps can use integer index 0 instead of 'method' and 1 instead of 'url'.
Since
1.23

Definition at line 52 of file MultiHttpClient.php.

Constructor & Destructor Documentation

◆ __construct()

MultiHttpClient::__construct ( array  $options)
Parameters
array$options
  • connTimeout : default connection timeout (seconds)
  • reqTimeout : default request timeout (seconds)
  • proxy : HTTP proxy to use
  • usePipelining : whether to use HTTP pipelining if possible (for all hosts)
  • maxConnsPerHost : maximum number of concurrent connections (per host)
  • userAgent : The User-Agent header value to send
  • logger : a \Psr\Log\LoggerInterface instance for debug logging
  • caBundlePath : path to specific Certificate Authority bundle (if any)
Exceptions
Exception

Definition at line 89 of file MultiHttpClient.php.

◆ __destruct()

MultiHttpClient::__destruct ( )

Definition at line 593 of file MultiHttpClient.php.

Member Function Documentation

◆ getCurlHandle()

MultiHttpClient::getCurlHandle ( array &  $req,
array  $opts 
)
protected
Parameters
array&$reqHTTP request map

@phan-param array{url:string,proxy?:?string,query:mixed,method:string,body:string|resource,headers:string[],stream?:resource,flags:array} $req

Parameters
array$opts
  • connTimeout : default connection timeout
  • reqTimeout : default request timeout
Returns
resource
Exceptions
Exception

Definition at line 283 of file MultiHttpClient.php.

References $header, $matches, and $userAgent.

Referenced by runMultiCurl().

◆ getCurlMulti()

MultiHttpClient::getCurlMulti ( array  $opts)
protected
Parameters
array$opts
Returns
resource
Exceptions
Exception

Definition at line 411 of file MultiHttpClient.php.

References $cmh, $maxConnsPerHost, and $usePipelining.

Referenced by runMultiCurl().

◆ getSelectTimeout()

MultiHttpClient::getSelectTimeout (   $opts)
private

Get a suitable select timeout for the given options.

Parameters
array$opts
Returns
float

Definition at line 568 of file MultiHttpClient.php.

References $connTimeout, $reqTimeout, and TIMEOUT_ACCURACY_FACTOR.

Referenced by runMultiCurl().

◆ isCurlEnabled()

MultiHttpClient::isCurlEnabled ( )
protected

Determines if the curl extension is available.

Returns
bool true if curl is available, false otherwise.

Definition at line 180 of file MultiHttpClient.php.

Referenced by runMulti().

◆ normalizeRequests()

MultiHttpClient::normalizeRequests ( array &  $reqs)
private

Normalize request information.

Parameters
array[]&$reqsthe requests to normalize

Definition at line 523 of file MultiHttpClient.php.

Referenced by runMulti().

◆ run()

MultiHttpClient::run ( array  $req,
array  $opts = [] 
)

Execute an HTTP(S) request.

This method returns a response map of:

  • code : HTTP response code or 0 if there was a serious error
  • reason : HTTP response reason (empty if there was a serious error)
  • headers : <header name/value associative array>
  • body : HTTP response body or resource (if "stream" was set)
  • error : Any error string The map also stores integer-indexed copies of these values. This lets callers do:
    list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $http->run( $req );
    Parameters
    array$reqHTTP request array
    array$opts
  • connTimeout : connection timeout per request (seconds)
  • reqTimeout : post-connection timeout per request (seconds)
  • usePipelining : whether to use HTTP pipelining if possible (for all hosts)
  • maxConnsPerHost : maximum number of concurrent connections (per host)
    Returns
    array Response array for request

Definition at line 131 of file MultiHttpClient.php.

References runMulti().

◆ runMulti()

MultiHttpClient::runMulti ( array  $reqs,
array  $opts = [] 
)

Execute a set of HTTP(S) requests.

If curl is available, requests will be made concurrently. Otherwise, they will be made serially.

The maps are returned by this method with the 'response' field set to a map of:

  • code : HTTP response code or 0 if there was a serious error
  • reason : HTTP response reason (empty if there was a serious error)
  • headers : <header name/value associative array>
  • body : HTTP response body or resource (if "stream" was set)
  • error : Any error string The map also stores integer-indexed copies of these values. This lets callers do:
    list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $req['response'];
    All headers in the 'headers' field are normalized to use lower case names. This is true for the request headers and the response headers. Integer-indexed method/URL entries will also be changed to use the corresponding string keys.
Parameters
array[]$reqsMap of HTTP request arrays
array$optsOptions
  • connTimeout : connection timeout per request (seconds)
  • reqTimeout : post-connection timeout per request (seconds)
  • usePipelining : whether to use HTTP pipelining if possible (for all hosts)
  • maxConnsPerHost : maximum number of concurrent connections (per host)
Returns
array[] $reqs With response array populated for each
Exceptions
Exception

Definition at line 164 of file MultiHttpClient.php.

References $connTimeout, $reqTimeout, isCurlEnabled(), normalizeRequests(), runMultiCurl(), and runMultiHttp().

Referenced by run().

◆ runMultiCurl()

MultiHttpClient::runMultiCurl ( array  $reqs,
array  $opts 
)
private

Execute a set of HTTP(S) requests concurrently.

See also
MultiHttpClient::runMulti()
Parameters
array[]$reqsMap of HTTP request arrays
array$opts
  • connTimeout : connection timeout per request (seconds)
  • reqTimeout : post-connection timeout per request (seconds)
  • usePipelining : whether to use HTTP pipelining if possible
  • maxConnsPerHost : maximum number of concurrent connections (per host)

@phan-param array{connTimeout?:int,reqTimeout?:int,usePipelining?:bool,maxConnsPerHost?:int} $opts

Returns
array $reqs With response array populated for each
Exceptions
ExceptionPhanTypeInvalidDimOffset

Definition at line 202 of file MultiHttpClient.php.

References getCurlHandle(), getCurlMulti(), and getSelectTimeout().

Referenced by runMulti().

◆ runMultiHttp()

MultiHttpClient::runMultiHttp ( array  $reqs,
array  $opts = [] 
)
private

Execute a set of HTTP(S) requests sequentially.

See also
MultiHttpClient::runMulti()
Todo:
Remove dependency on MediaWikiServices: use a separate HTTP client library or copy code from PhpHttpRequest
Parameters
array$reqsMap of HTTP request arrays

@phan-param array<int,array{url:string,query:array,method:string,body:string,proxy?:?string,headers?:string[]}> $reqs

Parameters
array$opts
  • connTimeout : connection timeout per request (seconds)
  • reqTimeout : post-connection timeout per request (seconds) @phan-param array{connTimeout:int,reqTimeout:int} $opts
Returns
array $reqs With response array populated for each
Exceptions
Exception

Definition at line 451 of file MultiHttpClient.php.

References $caBundlePath, $connTimeout, $logger, $proxy, $reqTimeout, and $userAgent.

Referenced by runMulti().

◆ setLogger()

MultiHttpClient::setLogger ( LoggerInterface  $logger)

Register a logger.

Parameters
LoggerInterface$logger

Definition at line 589 of file MultiHttpClient.php.

References $logger.

Member Data Documentation

◆ $caBundlePath

string null MultiHttpClient::$caBundlePath
protected

SSL certificates path.

Definition at line 56 of file MultiHttpClient.php.

Referenced by runMultiHttp().

◆ $cmh

resource MultiHttpClient::$cmh
protected

curl_multi_init() handle

Definition at line 54 of file MultiHttpClient.php.

Referenced by getCurlMulti().

◆ $connTimeout

float MultiHttpClient::$connTimeout = 10
protected

Definition at line 58 of file MultiHttpClient.php.

Referenced by getSelectTimeout(), runMulti(), and runMultiHttp().

◆ $logger

LoggerInterface MultiHttpClient::$logger
protected

Definition at line 70 of file MultiHttpClient.php.

Referenced by runMultiHttp(), and setLogger().

◆ $maxConnsPerHost

int MultiHttpClient::$maxConnsPerHost = 50
protected

Definition at line 64 of file MultiHttpClient.php.

Referenced by getCurlMulti().

◆ $proxy

string null MultiHttpClient::$proxy
protected

proxy

Definition at line 66 of file MultiHttpClient.php.

Referenced by runMultiHttp().

◆ $reqTimeout

float MultiHttpClient::$reqTimeout = 900
protected

Definition at line 60 of file MultiHttpClient.php.

Referenced by getSelectTimeout(), runMulti(), and runMultiHttp().

◆ $usePipelining

bool MultiHttpClient::$usePipelining = false
protected

Definition at line 62 of file MultiHttpClient.php.

Referenced by getCurlMulti().

◆ $userAgent

string MultiHttpClient::$userAgent = 'wikimedia/multi-http-client v1.0'
protected

Definition at line 68 of file MultiHttpClient.php.

Referenced by getCurlHandle(), and runMultiHttp().

◆ TIMEOUT_ACCURACY_FACTOR

const MultiHttpClient::TIMEOUT_ACCURACY_FACTOR = 0.1

Definition at line 75 of file MultiHttpClient.php.

Referenced by getSelectTimeout().


The documentation for this class was generated from the following file: