Class to handle multiple HTTP requests. More...

Inheritance diagram for MultiHttpClient:

Collaboration diagram for 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. More...

	__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...

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

string bool	$localProxy = false

string[]	$localVirtualHosts = []

LoggerInterface	$logger

int	$maxConnsPerHost = 50

float	$maxConnTimeout = INF

float	$maxReqTimeout = INF

string null	$proxy
	proxy More...

float	$reqTimeout = 30

bool	$usePipelining = false

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

Private Member Functions
	getCurlTime ( $ch, $oldOption, $newConstName)
	Get a time in seconds, formatted with microsecond resolution, or fall back to second resolution on PHP 7.2. More...

	getSelectTimeout ( $opts)
	Get a suitable select timeout for the given options. More...

	isLocalURL ( $url)
	Check if the URL can be served by localhost. 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...

	useReverseProxy (array &$req, $proxy)

Private Attributes
const	SENSITIVE_HEADERS = '/(^\|-\|_)(authorization\|auth\|password\|cookie)($\|-\|_)/'
	Regex for headers likely to contain tokens, etc. More...

const	TIMEOUT_ACCURACY_FACTOR = 0.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 55 of file MultiHttpClient.php.

Constructor & Destructor Documentation

◆ __construct()

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)

Exceptions

Exception

Definition at line 110 of file MultiHttpClient.php.

◆ __destruct()

MultiHttpClient::__destruct ( )

Definition at line 759 of file MultiHttpClient.php.

Member Function Documentation

◆ getCurlHandle()

MultiHttpClient::getCurlHandle	(	array &	$req,
		array	$opts
	)

protected

Parameters

array	&$req	HTTP request map @phpcs:ignore Generic.Files.LineLength
array	$opts	connTimeout : default connection timeout reqTimeout : default request timeout httpVersion: default HTTP version

Returns: resource

Exceptions

Exception

Definition at line 349 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 478 of file MultiHttpClient.php.

References $cmh, $maxConnsPerHost, and $usePipelining.

Referenced by runMultiCurl().

◆ getCurlTime()

MultiHttpClient::getCurlTime	(	$ch,
		$oldOption,
		$newConstName
	)

private

Get a time in seconds, formatted with microsecond resolution, or fall back to second resolution on PHP 7.2.

Parameters

resource	$ch
int	$oldOption
string	$newConstName

Returns: string

Definition at line 510 of file MultiHttpClient.php.

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 734 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 228 of file MultiHttpClient.php.

Referenced by runMulti().

◆ isLocalURL()

MultiHttpClient::isLocalURL ( $url )

private

Check if the URL can be served by localhost.

Note: this is mostly a copy of MWHttpRequest::isLocalURL()

Parameters

string $url Full url to check

Returns: bool

Definition at line 694 of file MultiHttpClient.php.

References $matches.

Referenced by normalizeRequests().

◆ normalizeRequests()

MultiHttpClient::normalizeRequests ( array & $reqs )

private

Normalize request information.

Parameters

array[] &$reqs the requests to normalize

Definition at line 607 of file MultiHttpClient.php.

References $header, isLocalURL(), and useReverseProxy().

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 $req HTTP 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 155 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[]	$reqs	Map of HTTP request arrays
array	$opts	Options 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 190 of file MultiHttpClient.php.

References $connTimeout, $maxConnTimeout, $maxReqTimeout, $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[]	$reqs	Map 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) httpVersion: : HTTP version to use

Returns: array $reqs With response array populated for each

Exceptions

Exception

Definition at line 251 of file MultiHttpClient.php.

References getCurlHandle(), getCurlMulti(), getCurlTime(), 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: rewrite using Guzzle T202352

Parameters

array	$reqs	Map of HTTP request arrays @phpcs:ignore Generic.Files.LineLength
array	$opts	connTimeout : connection timeout per request (seconds) reqTimeout : post-connection timeout per request (seconds)

Returns: array $reqs With response array populated for each

Exceptions

Exception

Definition at line 533 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 755 of file MultiHttpClient.php.

References $logger.

◆ useReverseProxy()

MultiHttpClient::useReverseProxy	(	array &	$req,
			$proxy
	)

private

Definition at line 662 of file MultiHttpClient.php.

References $proxy, wfAssembleUrl(), and wfParseUrl().

Referenced by normalizeRequests().

Member Data Documentation

◆ $caBundlePath

string null MultiHttpClient::$caBundlePath

protected

SSL certificates path.

Definition at line 61 of file MultiHttpClient.php.

Referenced by runMultiHttp().

◆ $cmh

resource MultiHttpClient::$cmh

protected

curl_multi_init() handle

Definition at line 59 of file MultiHttpClient.php.

Referenced by getCurlMulti().

◆ $connTimeout

float MultiHttpClient::$connTimeout = 10

protected

Definition at line 63 of file MultiHttpClient.php.

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

◆ $localProxy

string bool MultiHttpClient::$localProxy = false

protected

Definition at line 77 of file MultiHttpClient.php.

◆ $localVirtualHosts

string [] MultiHttpClient::$localVirtualHosts = []

protected

Definition at line 79 of file MultiHttpClient.php.

◆ $logger

LoggerInterface MultiHttpClient::$logger

protected

Definition at line 83 of file MultiHttpClient.php.

Referenced by runMultiHttp(), and setLogger().

◆ $maxConnsPerHost

int MultiHttpClient::$maxConnsPerHost = 50

protected

Definition at line 73 of file MultiHttpClient.php.

Referenced by getCurlMulti().

◆ $maxConnTimeout

float MultiHttpClient::$maxConnTimeout = INF

protected

Definition at line 65 of file MultiHttpClient.php.

Referenced by runMulti().

◆ $maxReqTimeout

float MultiHttpClient::$maxReqTimeout = INF

protected

Definition at line 69 of file MultiHttpClient.php.

Referenced by runMulti().

◆ $proxy

string null MultiHttpClient::$proxy

protected

proxy

Definition at line 75 of file MultiHttpClient.php.

Referenced by runMultiHttp(), and useReverseProxy().

◆ $reqTimeout

float MultiHttpClient::$reqTimeout = 30

protected

Definition at line 67 of file MultiHttpClient.php.

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

◆ $usePipelining

bool MultiHttpClient::$usePipelining = false

protected

Definition at line 71 of file MultiHttpClient.php.

Referenced by getCurlMulti().

◆ $userAgent

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

protected

Definition at line 81 of file MultiHttpClient.php.

Referenced by getCurlHandle(), and runMultiHttp().

◆ SENSITIVE_HEADERS

private

Regex for headers likely to contain tokens, etc.

that we want to redact from logs

Definition at line 57 of file MultiHttpClient.php.

◆ TIMEOUT_ACCURACY_FACTOR

const MultiHttpClient::TIMEOUT_ACCURACY_FACTOR = 0.1

private

Definition at line 88 of file MultiHttpClient.php.

Referenced by getSelectTimeout().

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

includes/libs/http/MultiHttpClient.php

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

◆ __destruct()

Member Function Documentation

◆ getCurlHandle()

◆ getCurlMulti()

◆ getCurlTime()

◆ getSelectTimeout()

◆ isCurlEnabled()

◆ isLocalURL()

◆ normalizeRequests()

◆ run()

◆ runMulti()

◆ runMultiCurl()

◆ runMultiHttp()

◆ setLogger()

◆ useReverseProxy()

Member Data Documentation

◆ $caBundlePath

◆ $cmh

◆ $connTimeout

◆ $localProxy

◆ $localVirtualHosts

◆ $logger

◆ $maxConnsPerHost

◆ $maxConnTimeout

◆ $maxReqTimeout

◆ $proxy

◆ $reqTimeout

◆ $usePipelining

◆ $userAgent

◆ SENSITIVE_HEADERS

◆ TIMEOUT_ACCURACY_FACTOR