MediaWiki  master
MWHttpRequest Class Reference

This wrapper class will call out to curl (if available) or fallback to regular PHP if necessary for handling internal HTTP requests. More...

Inheritance diagram for MWHttpRequest:
Collaboration diagram for MWHttpRequest:

Public Member Functions

 __construct ( $url, array $options=[], $caller=__METHOD__, Profiler $profiler=null)
 
 canFollowRedirects ()
 Returns true if the backend can follow redirects. More...
 
 execute ()
 Take care of whatever is necessary to perform the URI request. More...
 
 getContent ()
 Get the body, or content, of the response to the request. More...
 
 getCookieJar ()
 Returns the cookie jar in use. More...
 
 getFinalUrl ()
 Returns the final URL after all redirections. More...
 
 getResponseHeader ( $header)
 Returns the value of the given response header. More...
 
 getResponseHeaders ()
 Returns an associative array of response headers after the request has been executed. More...
 
 getStatus ()
 Get the integer value of the HTTP status code (e.g. More...
 
 isRedirect ()
 Returns true if the last status code was a redirect. More...
 
 read ( $fh, $content)
 A generic callback to read the body of the response from a remote server. More...
 
 setCallback ( $callback)
 Set a read callback to accept data read from the HTTP request. More...
 
 setCookie ( $name, $value, array $attr=[])
 Sets a cookie. More...
 
 setCookieJar (CookieJar $jar)
 Tells the MWHttpRequest object to use this pre-loaded CookieJar. More...
 
 setData (array $args)
 Set the parameters of the request. More...
 
 setHeader ( $name, $value)
 Set an arbitrary header. More...
 
 setLogger (LoggerInterface $logger)
 
 setOriginalRequest ( $originalRequest)
 Set information about the original request. More...
 
 setUserAgent ( $UA)
 Set the user agent. More...
 

Static Public Member Functions

static canMakeRequests ()
 Simple function to test if we can make any sort of requests at all, using cURL or fopen() More...
 
static factory ( $url, array $options=null, $caller=__METHOD__)
 Generate a new request object. More...
 
static isValidURI ( $uri)
 Check that the given URI is a valid one. More...
 

Public Attributes

const SUPPORTS_FILE_POSTS = false
 

Protected Member Functions

 doSetCallback ( $callback)
 Worker function for setting callbacks. More...
 
 getHeaderList ()
 Get an array of the headers. More...
 
 parseCookies ()
 Parse the cookies in the response headers and store them in the cookie jar. More...
 
 parseHeader ()
 Parses the headers, including the HTTP status code and any Set-Cookie headers. More...
 
 prepare ()
 
 proxySetup ()
 Take care of setting up the proxy (do nothing if "noProxy" is set) More...
 
 setStatus ()
 Sets HTTPRequest status member to a fatal value with the error message if the returned integer value of the status code was not successful (1-299) or a redirect (300-399). More...
 

Protected Attributes

 $caInfo = null
 
callable $callback
 
 $connectTimeout
 
 $content
 
CookieJar $cookieJar
 
 $followRedirects = false
 
 $headerList = []
 
 $headersOnly = null
 
LoggerInterface $logger
 
 $maxRedirects = 5
 
 $method = "GET"
 
 $noProxy = false
 
 $parsedUrl
 
 $postData = null
 
string $profileName
 
Profiler $profiler
 
 $proxy = null
 
array $reqHeaders = []
 
string [][] $respHeaders = []
 
 $respStatus = "200 Ok"
 
 $respVersion = "0.9"
 
 $sslVerifyCert = true
 
 $sslVerifyHost = true
 
StatusValue $status
 
int string $timeout = 'default'
 
 $url
 

Static Private Member Functions

static isLocalURL ( $url)
 Check if the URL can be served by localhost. More...
 

Detailed Description

This wrapper class will call out to curl (if available) or fallback to regular PHP if necessary for handling internal HTTP requests.

Renamed from HttpRequest to MWHttpRequest to avoid conflict with PHP's HTTP extension.

Definition at line 33 of file MWHttpRequest.php.

Constructor & Destructor Documentation

◆ __construct()

MWHttpRequest::__construct (   $url,
array  $options = [],
  $caller = __METHOD__,
Profiler  $profiler = null 
)
Parameters
string$urlUrl to use. If protocol-relative, will be expanded to an http:// URL
array$options(optional) extra params to pass (see HttpRequestFactory::create())

-param array{timeout?:int|string,connectTimeout?:int|string,postData?:array,proxy?:string,noProxy?:bool,sslVerifyHost?:bool,sslVerifyCert?:bool,caInfo?:string,maxRedirects?:int,followRedirects?:bool,userAgent?:string,logger?:LoggerInterface,username?:string,password?:string,originalRequest?:WebRequest|array{ip:string,userAgent:string},method?:string} $options

Parameters
string$callerThe method making this request, for profiling
Profiler | null$profilerAn instance of the profiler for profiling, or null
Exceptions
Exception

Definition at line 99 of file MWHttpRequest.php.

References $profiler, $url, $wgHTTPConnectTimeout, $wgHTTPTimeout, WebRequest\getRequestId(), StatusValue\newFatal(), StatusValue\newGood(), PROTO_HTTP, setHeader(), setOriginalRequest(), setUserAgent(), wfExpandUrl(), and wfParseUrl().

Member Function Documentation

◆ canFollowRedirects()

MWHttpRequest::canFollowRedirects ( )

Returns true if the backend can follow redirects.

Overridden by the child classes.

Returns
bool

Definition at line 640 of file MWHttpRequest.php.

◆ canMakeRequests()

static MWHttpRequest::canMakeRequests ( )
static

Simple function to test if we can make any sort of requests at all, using cURL or fopen()

Returns
bool

Definition at line 176 of file MWHttpRequest.php.

References wfIniGetBool().

Referenced by Installer\subscribeToMediaWikiAnnounce().

◆ doSetCallback()

MWHttpRequest::doSetCallback (   $callback)
protected

Worker function for setting callbacks.

Calls can originate both internally and externally via setCallback). Defaults to the internal read callback if $callback is null.

Parameters
callable | null$callback
Exceptions
InvalidArgumentException

Definition at line 348 of file MWHttpRequest.php.

References $callback.

Referenced by prepare(), and setCallback().

◆ execute()

MWHttpRequest::execute ( )

Take care of whatever is necessary to perform the URI request.

Returns
Status
Note
currently returns Status for B/C

Definition at line 378 of file MWHttpRequest.php.

◆ factory()

static MWHttpRequest::factory (   $url,
array  $options = null,
  $caller = __METHOD__ 
)
static

Generate a new request object.

Deprecated:
since 1.34, use HttpRequestFactory instead
Parameters
string$urlUrl to use
array | null$options(optional) extra params to pass (see HttpRequestFactory::create())
string$callerThe method making this request, for profiling
Exceptions
DomainException
Returns
MWHttpRequest
See also
MWHttpRequest::__construct

Definition at line 190 of file MWHttpRequest.php.

References $url.

Referenced by ForeignResourceManager\fetch(), ForeignAPIRepo\httpGet(), Parser\interwikiTransclude(), SpecialUploadStash\outputRemoteScaledThumb(), UploadFromUrl\reallyFetchFile(), Installer\subscribeToMediaWikiAnnounce(), and wfProxyThumbnailRequest().

◆ getContent()

MWHttpRequest::getContent ( )

Get the body, or content, of the response to the request.

Returns
string

Definition at line 203 of file MWHttpRequest.php.

References $content.

◆ getCookieJar()

MWHttpRequest::getCookieJar ( )

Returns the cookie jar in use.

Returns
CookieJar

Definition at line 537 of file MWHttpRequest.php.

References $cookieJar, and parseHeader().

◆ getFinalUrl()

MWHttpRequest::getFinalUrl ( )

Returns the final URL after all redirections.

Relative values of the "Location" header are incorrect as stated in RFC, however they do happen and modern browsers support them. This function loops backwards through all locations in order to build the proper absolute URI - Marooned at wikia-inc.com

Note that the multiple Location: headers are an artifact of CURL – they shouldn't actually get returned this way. Rewrite this when T31232 is taken care of (high-level redirect handling rewrite).

Returns
string

Definition at line 598 of file MWHttpRequest.php.

References $url, and getResponseHeaders().

Referenced by parseCookies().

◆ getHeaderList()

MWHttpRequest::getHeaderList ( )
protected

Get an array of the headers.

Returns
array

Definition at line 301 of file MWHttpRequest.php.

Referenced by CurlHttpRequest\execute(), and PhpHttpRequest\execute().

◆ getResponseHeader()

MWHttpRequest::getResponseHeader (   $header)

Returns the value of the given response header.

Parameters
string$headercase-insensitive
Returns
string|null

Definition at line 508 of file MWHttpRequest.php.

References $header, and parseHeader().

Referenced by PhpHttpRequest\execute().

◆ getResponseHeaders()

MWHttpRequest::getResponseHeaders ( )

Returns an associative array of response headers after the request has been executed.

Because some headers (e.g. Set-Cookie) can appear more than once the, each value of the associative array is an array of the values given. Header names are always in lowercase.

Returns
array

Definition at line 494 of file MWHttpRequest.php.

References $respHeaders, and parseHeader().

Referenced by getFinalUrl().

◆ getStatus()

MWHttpRequest::getStatus ( )

Get the integer value of the HTTP status code (e.g.

200 for "200 Ok") (see RFC2616, section 10, http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for a list of status codes.)

Returns
int

Definition at line 458 of file MWHttpRequest.php.

References $respStatus, and parseHeader().

◆ isLocalURL()

static MWHttpRequest::isLocalURL (   $url)
staticprivate

Check if the URL can be served by localhost.

Parameters
string$urlFull url to check
Returns
bool

Definition at line 244 of file MWHttpRequest.php.

References $matches, $url, $wgCommandLineMode, and $wgLocalVirtualHosts.

◆ isRedirect()

MWHttpRequest::isRedirect ( )

Returns true if the last status code was a redirect.

Returns
bool

Definition at line 471 of file MWHttpRequest.php.

References parseHeader().

Referenced by PhpHttpRequest\execute().

◆ isValidURI()

static MWHttpRequest::isValidURI (   $uri)
static

Check that the given URI is a valid one.

This hardcodes a small set of protocols only, because we want to deterministically reject protocols not supported by all HTTP-transport methods.

"file://" specifically must not be allowed, for security reasons (see https://www.mediawiki.org/wiki/Special:Code/MediaWiki/r67684).

Todo:
FIXME this is wildly inaccurate and fails to actually check most stuff
Since
1.34
Parameters
string$uriURI to check for validity
Returns
bool

Definition at line 690 of file MWHttpRequest.php.

Referenced by Http\isValidURI().

◆ parseCookies()

MWHttpRequest::parseCookies ( )
protected

Parse the cookies in the response headers and store them in the cookie jar.

Definition at line 569 of file MWHttpRequest.php.

References $url, and getFinalUrl().

Referenced by GuzzleHttpRequest\parseHeader(), and parseHeader().

◆ parseHeader()

MWHttpRequest::parseHeader ( )
protected

Parses the headers, including the HTTP status code and any Set-Cookie headers.

This function expects the headers to be found in an array in the member variable headerList.

Definition at line 406 of file MWHttpRequest.php.

References $header, and parseCookies().

Referenced by CurlHttpRequest\execute(), PhpHttpRequest\execute(), getCookieJar(), getResponseHeader(), getResponseHeaders(), getStatus(), isRedirect(), and setStatus().

◆ prepare()

MWHttpRequest::prepare ( )
protected

Definition at line 382 of file MWHttpRequest.php.

References doSetCallback(), proxySetup(), and setUserAgent().

Referenced by CurlHttpRequest\execute(), and PhpHttpRequest\execute().

◆ proxySetup()

MWHttpRequest::proxySetup ( )
protected

Take care of setting up the proxy (do nothing if "noProxy" is set)

Returns
void

Definition at line 222 of file MWHttpRequest.php.

References $wgHTTPProxy.

Referenced by prepare().

◆ read()

MWHttpRequest::read (   $fh,
  $content 
)

A generic callback to read the body of the response from a remote server.

Parameters
resource$fh
string$content
Returns
int

Definition at line 367 of file MWHttpRequest.php.

References $content.

◆ setCallback()

MWHttpRequest::setCallback (   $callback)

Set a read callback to accept data read from the HTTP request.

By default, data is appended to an internal buffer which can be retrieved through $req->getContent().

To handle data as it comes in – especially for large files that would not fit in memory – you can instead set your own callback, in the form function($resource, $buffer) where the first parameter is the low-level resource being read (implementation specific), and the second parameter is the data buffer.

You MUST return the number of bytes handled in the buffer; if fewer bytes are reported handled than were passed to you, the HTTP fetch will be aborted.

Parameters
callable | null$callback
Exceptions
InvalidArgumentException

Definition at line 337 of file MWHttpRequest.php.

References doSetCallback().

◆ setCookie()

MWHttpRequest::setCookie (   $name,
  $value,
array  $attr = [] 
)

Sets a cookie.

Used before a request to set up any individual cookies. Used internally after a request to parse the Set-Cookie headers.

See also
Cookie::set
Parameters
string$name
string$value
array$attr

Definition at line 554 of file MWHttpRequest.php.

References CookieJar\setCookie().

◆ setCookieJar()

MWHttpRequest::setCookieJar ( CookieJar  $jar)

Tells the MWHttpRequest object to use this pre-loaded CookieJar.

To read response cookies from the jar, getCookieJar must be called first.

Parameters
CookieJar$jar

Definition at line 528 of file MWHttpRequest.php.

◆ setData()

MWHttpRequest::setData ( array  $args)

Set the parameters of the request.

Parameters
array$args
Todo:
overload the args param

Definition at line 213 of file MWHttpRequest.php.

References $args.

◆ setHeader()

MWHttpRequest::setHeader (   $name,
  $value 
)

Set an arbitrary header.

Parameters
string$name
string$value

Definition at line 292 of file MWHttpRequest.php.

Referenced by __construct(), and setUserAgent().

◆ setLogger()

MWHttpRequest::setLogger ( LoggerInterface  $logger)
Parameters
LoggerInterface$logger

Definition at line 167 of file MWHttpRequest.php.

References $logger.

◆ setOriginalRequest()

MWHttpRequest::setOriginalRequest (   $originalRequest)

Set information about the original request.

This can be useful for endpoints/API modules which act as a proxy for some service, and throttling etc. needs to happen in that service. Calling this will result in the X-Forwarded-For and X-Original-User-Agent headers being set.

Parameters
WebRequest | array$originalRequestWhen in array form, it's expected to have the keys 'ip' and 'userAgent'.
Note
IP/user agent is personally identifiable information, and should only be set when the privacy policy of the request target is compatible with that of the MediaWiki installation.

Definition at line 656 of file MWHttpRequest.php.

Referenced by __construct().

◆ setStatus()

MWHttpRequest::setStatus ( )
protected

Sets HTTPRequest status member to a fatal value with the error message if the returned integer value of the status code was not successful (1-299) or a redirect (300-399).

See RFC2616, section 10, http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for a list of status codes.

Definition at line 437 of file MWHttpRequest.php.

References parseHeader().

Referenced by CurlHttpRequest\execute(), PhpHttpRequest\execute(), and GuzzleHttpRequest\execute().

◆ setUserAgent()

MWHttpRequest::setUserAgent (   $UA)

Set the user agent.

Parameters
string$UA

Definition at line 283 of file MWHttpRequest.php.

References setHeader().

Referenced by __construct(), and prepare().

Member Data Documentation

◆ $caInfo

MWHttpRequest::$caInfo = null
protected

◆ $callback

callable MWHttpRequest::$callback
protected

◆ $connectTimeout

MWHttpRequest::$connectTimeout
protected

Definition at line 58 of file MWHttpRequest.php.

Referenced by GuzzleHttpRequest\execute().

◆ $content

MWHttpRequest::$content
protected

Definition at line 41 of file MWHttpRequest.php.

Referenced by getContent(), read(), and CurlHttpRequest\readHeader().

◆ $cookieJar

CookieJar MWHttpRequest::$cookieJar
protected

Definition at line 63 of file MWHttpRequest.php.

Referenced by getCookieJar().

◆ $followRedirects

MWHttpRequest::$followRedirects = false
protected

Definition at line 57 of file MWHttpRequest.php.

◆ $headerList

MWHttpRequest::$headerList = []
protected

Definition at line 65 of file MWHttpRequest.php.

◆ $headersOnly

MWHttpRequest::$headersOnly = null
protected

Definition at line 42 of file MWHttpRequest.php.

◆ $logger

LoggerInterface MWHttpRequest::$logger
protected

Definition at line 87 of file MWHttpRequest.php.

Referenced by setLogger().

◆ $maxRedirects

MWHttpRequest::$maxRedirects = 5
protected

Definition at line 56 of file MWHttpRequest.php.

Referenced by CurlHttpRequest\execute(), and GuzzleHttpRequest\execute().

◆ $method

MWHttpRequest::$method = "GET"
protected

Definition at line 49 of file MWHttpRequest.php.

Referenced by CurlHttpRequest\execute(), and PhpHttpRequest\execute().

◆ $noProxy

MWHttpRequest::$noProxy = false
protected

Definition at line 45 of file MWHttpRequest.php.

◆ $parsedUrl

MWHttpRequest::$parsedUrl
protected

Definition at line 53 of file MWHttpRequest.php.

Referenced by PhpHttpRequest\urlToTcp().

◆ $postData

MWHttpRequest::$postData = null
protected

◆ $profileName

string MWHttpRequest::$profileName
protected

Definition at line 82 of file MWHttpRequest.php.

◆ $profiler

Profiler MWHttpRequest::$profiler
protected

Definition at line 77 of file MWHttpRequest.php.

Referenced by GuzzleHttpRequest\__construct(), and __construct().

◆ $proxy

MWHttpRequest::$proxy = null
protected

Definition at line 44 of file MWHttpRequest.php.

Referenced by CurlHttpRequest\execute(), and GuzzleHttpRequest\execute().

◆ $reqHeaders

array MWHttpRequest::$reqHeaders = []
protected

Definition at line 51 of file MWHttpRequest.php.

Referenced by GuzzleHttpRequest\execute().

◆ $respHeaders

string [][] MWHttpRequest::$respHeaders = []
protected

Definition at line 69 of file MWHttpRequest.php.

Referenced by getResponseHeaders().

◆ $respStatus

MWHttpRequest::$respStatus = "200 Ok"
protected

Definition at line 67 of file MWHttpRequest.php.

Referenced by getStatus().

◆ $respVersion

MWHttpRequest::$respVersion = "0.9"
protected

Definition at line 66 of file MWHttpRequest.php.

◆ $sslVerifyCert

MWHttpRequest::$sslVerifyCert = true
protected

Definition at line 47 of file MWHttpRequest.php.

Referenced by CurlHttpRequest\execute(), and PhpHttpRequest\execute().

◆ $sslVerifyHost

MWHttpRequest::$sslVerifyHost = true
protected

Definition at line 46 of file MWHttpRequest.php.

◆ $status

StatusValue MWHttpRequest::$status
protected

Definition at line 72 of file MWHttpRequest.php.

◆ $timeout

int string MWHttpRequest::$timeout = 'default'
protected

◆ $url

◆ SUPPORTS_FILE_POSTS

const MWHttpRequest::SUPPORTS_FILE_POSTS = false

Definition at line 34 of file MWHttpRequest.php.


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