MediaWiki master
Wikimedia\Http\MultiHttpClient Class Reference

Class to handle multiple HTTP requests. More...

Inherits LoggerAwareInterface.

Collaboration diagram for Wikimedia\Http\MultiHttpClient:

Public Member Functions

 __construct (array $options)
 Since 1.35, callers should use HttpRequestFactory::createMultiClient() to get a client object with appropriately configured timeouts instead of constructing a MultiHttpClient directly.
 
 __destruct ()
 
 run (array $req, array $opts=[])
 Execute an HTTP(S) request.
 
 runMulti (array $reqs, array $opts=[])
 Execute a set of HTTP(S) requests.
 
 setLogger (LoggerInterface $logger)
 Register a logger.
 

Protected Member Functions

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

Protected Attributes

string null $caBundlePath
 SSL certificates path.
 
resource object null $cmh = null
 @phpcs:ignore MediaWiki.Commenting.PropertyDocumentation.ObjectTypeHintVar curl_multi_init() handle, initialized in getCurlMulti()
 
float $connTimeout = 10
 
array array $headers = []
 
string false $localProxy = false
 
string[] $localVirtualHosts = []
 
LoggerInterface $logger
 
int $maxConnsPerHost = 50
 
float $maxConnTimeout = INF
 
float $maxReqTimeout = INF
 
string null $proxy
 proxy
 
float $reqTimeout = 30
 
bool $usePipelining = false
 
string $userAgent = 'wikimedia/multi-http-client v1.1'
 

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.35, callers should use HttpRequestFactory::createMultiClient() to get a client object with appropriately configured timeouts.

Since
1.23

Definition at line 58 of file MultiHttpClient.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\Http\MultiHttpClient::__construct ( array $options)

Since 1.35, callers should use HttpRequestFactory::createMultiClient() to get a client object with appropriately configured timeouts instead of constructing a MultiHttpClient directly.

Parameters
array$options
  • connTimeout : default connection timeout (seconds)
  • reqTimeout : default request timeout (seconds)
  • maxConnTimeout : maximum connection timeout (seconds)
  • maxReqTimeout : maximum request timeout (seconds)
  • proxy : HTTP proxy to use
  • localProxy : Reverse proxy to use for domains in localVirtualHosts
  • localVirtualHosts : Domains that are configured as virtual hosts on the same machine
  • 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)
  • headers : an array of default headers to send with every request
  • telemetry : a \Wikimedia\Http\RequestTelemetry instance to track telemetry data
Exceptions

\Exception

Definition at line 122 of file MultiHttpClient.php.

◆ __destruct()

Wikimedia\Http\MultiHttpClient::__destruct ( )

Definition at line 809 of file MultiHttpClient.php.

Member Function Documentation

◆ getCurlHandle()

Wikimedia\Http\MultiHttpClient::getCurlHandle ( array & $req,
array $opts )
protected
Parameters
array&$reqHTTP request map @phpcs:ignore Generic.Files.LineLength
array$opts
  • connTimeout : default connection timeout
  • reqTimeout : default request timeout
  • httpVersion: default HTTP version @phpcs:ignore MediaWiki.Commenting.FunctionComment.ObjectTypeHintReturn
Returns
resource|object
Exceptions

\Exception

Definition at line 363 of file MultiHttpClient.php.

References $header, Wikimedia\Http\MultiHttpClient\$headers, $matches, $url, and Wikimedia\Http\MultiHttpClient\$userAgent.

◆ getCurlMulti()

Wikimedia\Http\MultiHttpClient::getCurlMulti ( array $opts)
protected
Parameters
array$opts@phpcs:ignore MediaWiki.Commenting.FunctionComment.ObjectTypeHintReturn
Returns
resource|object
Exceptions

\Exception

Definition at line 496 of file MultiHttpClient.php.

References Wikimedia\Http\MultiHttpClient\$cmh, and Wikimedia\Http\MultiHttpClient\$maxConnsPerHost.

◆ isCurlEnabled()

Wikimedia\Http\MultiHttpClient::isCurlEnabled ( )
protected

Determines if the curl extension is available.

Returns
bool true if curl is available, false otherwise.

Definition at line 238 of file MultiHttpClient.php.

Referenced by Wikimedia\Http\MultiHttpClient\runMulti().

◆ run()

Wikimedia\Http\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:
    [ $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)
  • httpVersion : One of 'v1.0', 'v1.1', 'v2' or 'v2.0'. Leave empty to use PHP/curl's default
    Returns
    array Response array for request

Definition at line 165 of file MultiHttpClient.php.

References Wikimedia\Http\MultiHttpClient\runMulti().

◆ runMulti()

Wikimedia\Http\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:
    [ $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)
  • httpVersion : One of 'v1.0', 'v1.1', 'v2' or 'v2.0'. Leave empty to use PHP/curl's default
Returns
array[] $reqs With response array populated for each
Exceptions

\Exception

Definition at line 200 of file MultiHttpClient.php.

References Wikimedia\Http\MultiHttpClient\$connTimeout, Wikimedia\Http\MultiHttpClient\$maxConnTimeout, Wikimedia\Http\MultiHttpClient\$maxReqTimeout, Wikimedia\Http\MultiHttpClient\$reqTimeout, and Wikimedia\Http\MultiHttpClient\isCurlEnabled().

Referenced by Wikimedia\Http\MultiHttpClient\run().

◆ setLogger()

Wikimedia\Http\MultiHttpClient::setLogger ( LoggerInterface $logger)

Register a logger.

Parameters
LoggerInterface$logger

Definition at line 805 of file MultiHttpClient.php.

Member Data Documentation

◆ $caBundlePath

string null Wikimedia\Http\MultiHttpClient::$caBundlePath
protected

SSL certificates path.

Definition at line 67 of file MultiHttpClient.php.

◆ $cmh

resource object null Wikimedia\Http\MultiHttpClient::$cmh = null
protected

@phpcs:ignore MediaWiki.Commenting.PropertyDocumentation.ObjectTypeHintVar curl_multi_init() handle, initialized in getCurlMulti()

Definition at line 65 of file MultiHttpClient.php.

Referenced by Wikimedia\Http\MultiHttpClient\getCurlMulti().

◆ $connTimeout

float Wikimedia\Http\MultiHttpClient::$connTimeout = 10
protected

Definition at line 69 of file MultiHttpClient.php.

Referenced by Wikimedia\Http\MultiHttpClient\runMulti().

◆ $headers

array array Wikimedia\Http\MultiHttpClient::$headers = []
protected

Definition at line 91 of file MultiHttpClient.php.

Referenced by Wikimedia\Http\MultiHttpClient\getCurlHandle().

◆ $localProxy

string false Wikimedia\Http\MultiHttpClient::$localProxy = false
protected

Definition at line 83 of file MultiHttpClient.php.

◆ $localVirtualHosts

string [] Wikimedia\Http\MultiHttpClient::$localVirtualHosts = []
protected

Definition at line 85 of file MultiHttpClient.php.

◆ $logger

LoggerInterface Wikimedia\Http\MultiHttpClient::$logger
protected

Definition at line 89 of file MultiHttpClient.php.

◆ $maxConnsPerHost

int Wikimedia\Http\MultiHttpClient::$maxConnsPerHost = 50
protected

Definition at line 79 of file MultiHttpClient.php.

Referenced by Wikimedia\Http\MultiHttpClient\getCurlMulti().

◆ $maxConnTimeout

float Wikimedia\Http\MultiHttpClient::$maxConnTimeout = INF
protected

Definition at line 71 of file MultiHttpClient.php.

Referenced by Wikimedia\Http\MultiHttpClient\runMulti().

◆ $maxReqTimeout

float Wikimedia\Http\MultiHttpClient::$maxReqTimeout = INF
protected

Definition at line 75 of file MultiHttpClient.php.

Referenced by Wikimedia\Http\MultiHttpClient\runMulti().

◆ $proxy

string null Wikimedia\Http\MultiHttpClient::$proxy
protected

proxy

Definition at line 81 of file MultiHttpClient.php.

◆ $reqTimeout

float Wikimedia\Http\MultiHttpClient::$reqTimeout = 30
protected

Definition at line 73 of file MultiHttpClient.php.

Referenced by Wikimedia\Http\MultiHttpClient\runMulti().

◆ $usePipelining

bool Wikimedia\Http\MultiHttpClient::$usePipelining = false
protected

Definition at line 77 of file MultiHttpClient.php.

◆ $userAgent

string Wikimedia\Http\MultiHttpClient::$userAgent = 'wikimedia/multi-http-client v1.1'
protected

Definition at line 87 of file MultiHttpClient.php.

Referenced by Wikimedia\Http\MultiHttpClient\getCurlHandle().


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