Class to handle multiple HTTP requests. More...

Inherits LoggerAwareInterface.

Collaboration diagram for Wikimedia\Http\MultiHttpClient:

[legend]

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=[], string $caller=__METHOD__)
	Execute an HTTP(S) request.

	runMulti (array $reqs, array $opts=[], string $caller=__METHOD__)
	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
	curl_multi_init() handle, initialized in getCurlMulti()

float	$connTimeout = 10

array	$headers = []

string false	$localProxy = false

string[]	$localVirtualHosts = []

LoggerInterface	$logger

int	$maxConnsPerHost = 50

float	$maxConnTimeout = INF

float	$maxReqTimeout = INF

string null	$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 45 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 108 of file MultiHttpClient.php.

◆ __destruct()

Wikimedia\Http\MultiHttpClient::__destruct ( )

Definition at line 865 of file MultiHttpClient.php.

Member Function Documentation

◆ getCurlHandle()

Wikimedia\Http\MultiHttpClient::getCurlHandle	(	array &	$req,
		array	$opts )

protected

Parameters

array	&$req	HTTP request map
array	$opts	connTimeout : default connection timeout reqTimeout : default request timeout httpVersion: default HTTP version

Returns: resource|object

Exceptions

\Exception

Definition at line 374 of file MultiHttpClient.php.

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

◆ getCurlMulti()

Wikimedia\Http\MultiHttpClient::getCurlMulti ( array $opts )

protected

Parameters

array $opts

Returns: resource|object

Exceptions

\Exception

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

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

◆ run()

Wikimedia\Http\MultiHttpClient::run	(	array	$req,
		array	$opts = [],
		string	$caller = __METHOD__ )

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 $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
Parameters

string $caller The method making this request, for attribution in logs

Returns
array Response array for request

Definition at line 152 of file MultiHttpClient.php.

References Wikimedia\Http\MultiHttpClient\runMulti().

◆ runMulti()

Wikimedia\Http\MultiHttpClient::runMulti	(	array	$reqs,
		array	$opts = [],
		string	$caller = __METHOD__ )

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[]	$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
string	$caller	The method making these requests, for attribution in logs

Returns: array[] $reqs With response array populated for each

Exceptions

\Exception

Definition at line 188 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.

Definition at line 861 of file MultiHttpClient.php.

Member Data Documentation

◆ $caBundlePath

string null Wikimedia\Http\MultiHttpClient::$caBundlePath

protected

SSL certificates path.

Definition at line 54 of file MultiHttpClient.php.

◆ $cmh

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

protected

curl_multi_init() handle, initialized in getCurlMulti()

Definition at line 52 of file MultiHttpClient.php.

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

◆ $connTimeout

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

protected

Definition at line 56 of file MultiHttpClient.php.

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

◆ $headers

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

protected

Definition at line 77 of file MultiHttpClient.php.

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

◆ $localProxy

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

protected

Definition at line 70 of file MultiHttpClient.php.

◆ $localVirtualHosts

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

protected

Definition at line 72 of file MultiHttpClient.php.

◆ $logger

LoggerInterface Wikimedia\Http\MultiHttpClient::$logger

protected

Definition at line 76 of file MultiHttpClient.php.

◆ $maxConnsPerHost

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

protected

Definition at line 66 of file MultiHttpClient.php.

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

◆ $maxConnTimeout

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

protected

Definition at line 58 of file MultiHttpClient.php.

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

◆ $maxReqTimeout

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

protected

Definition at line 62 of file MultiHttpClient.php.

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

◆ $proxy

string null Wikimedia\Http\MultiHttpClient::$proxy

protected

Definition at line 68 of file MultiHttpClient.php.

◆ $reqTimeout

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

protected

Definition at line 60 of file MultiHttpClient.php.

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

◆ $usePipelining

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

protected

Definition at line 64 of file MultiHttpClient.php.

◆ $userAgent

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

protected

Definition at line 74 of file MultiHttpClient.php.

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

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

includes/libs/Http/MultiHttpClient.php

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

◆ __destruct()

Member Function Documentation

◆ getCurlHandle()

◆ getCurlMulti()

◆ isCurlEnabled()

◆ run()

◆ runMulti()

◆ setLogger()

Member Data Documentation

◆ $caBundlePath

◆ $cmh

◆ $connTimeout

◆ $headers

◆ $localProxy

◆ $localVirtualHosts

◆ $logger

◆ $maxConnsPerHost

◆ $maxConnTimeout

◆ $maxReqTimeout

◆ $proxy

◆ $reqTimeout

◆ $usePipelining

◆ $userAgent