wppaste
WordPress

Requests::request( string|WpOrg\Requests\Stringable $url, array $headers = [], array|null $data = [], string $type = self::GET, array $options = [] ): WpOrg\Requests\Response

Source
wp-includes/Requests/src/Requests.php:434
Main interface for HTTP requests

Description

This method initiates a request and sends it via a transport before parsing.

The $options parameter takes an associative array with the following options:

  • timeout: How long should we wait for a response? Note: for cURL, a minimum of 1 second applies, as DNS resolution operates at second-resolution only.
    (float, seconds with a millisecond precision, default: 10, example: 0.01)
  • connect_timeout: How long should we wait while trying to connect? (float, seconds with a millisecond precision, default: 10, example: 0.01)
  • useragent: Useragent to send to the server (string, default: php-requests/$version)
  • follow_redirects: Should we follow 3xx redirects? (boolean, default: true)
  • redirects: How many times should we redirect before erroring? (integer, default: 10)
  • blocking: Should we block processing on this request? (boolean, default: true)
  • filename: File to stream the body to instead.
    (string|boolean, default: false)
  • auth: Authentication handler or array of user/password details to use for Basic authentication (\WpOrg\Requests\Auth|array|boolean, default: false)
  • proxy: Proxy details to use for proxy by-passing and authentication (\WpOrg\Requests\Proxy|array|string|boolean, default: false)
  • max_bytes: Limit for the response body size.
    (integer|boolean, default: false)
  • idn: Enable IDN parsing (boolean, default: true)
  • transport: Custom transport. Either a class name, or a transport object. Defaults to the first working transport from \WpOrg\Requests\Requests::getTransport() (string|\WpOrg\Requests\Transport, default: \WpOrg\Requests\Requests::getTransport())
  • hooks: Hooks handler.
    (\WpOrg\Requests\HookManager, default: new WpOrg\Requests\Hooks())
  • verify: Should we verify SSL certificates? Allows passing in a custom certificate file as a string. (Using true uses the system-wide root certificate store instead, but this may have different behaviour across transports.) (string|boolean, default: certificates/cacert.pem)
  • verifyname: Should we verify the common name in the SSL certificate? (boolean, default: true)
  • data_format: How should we send the $data parameter? (string, one of 'query' or 'body', default: 'query' for HEAD/GET/DELETE, 'body' for POST/PUT/OPTIONS/PATCH)

Compatibility

WordPress
core
PHP
7.4–8.6-dev
  • 6.7.7
  • 6.8.8
  • 6.9.7
  • 7.0.4
  • 7.1.0

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$urlstring|WpOrg\Requests\Stringable
URL to request
$headersarrayoptional
Extra headers to send with the requestDefault: []
$dataarray|nulloptional
Data to send either as a query string for GET/HEAD requests, or in the body for POST requestsDefault: []
$typestringoptional
HTTP request type (use Requests constants)Default: self::GET
$optionsarrayoptional
Options for the request (see description for more information)Default: []

Return value

WpOrg\Requests\Response

Performance profile

How much work a call to Requests::request() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class
Trivial

Touches nothing outside its own arguments.

Scaling
Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions
18–83

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 116.

Plugin surface
None

Nothing here hands control to plugin code.

Called by
0

Nothing in core calls this; the cost is only what you spend yourself.

What one call costs · 4 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost Requests::request() can have, taken from its control-flow graph on PHP 8.5.

WhenInstructionsCalls it makes
always18–24::InputValidator(), ::InvalidArgument()
!empty($options)74–76::InputValidator(), ::get_default_options(), array_merge(), ::set_defaults(), ->request(), ::parse_response()
!empty($options)79–81::InputValidator(), ::get_default_options(), array_merge(), ::set_defaults(), ->dispatch(), ->request(), ::parse_response()
empty($options)81–83::InputValidator(), ::get_default_options(), array_merge(), ::set_defaults(), stripos(), ::get_transport(), ->request(), ::parse_response()

Across PHP versions

Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 116 instructions, 18–83 executed per call, 6 branches. The work does not change between versions.

An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.

Uses · 7

  • stripos()
  • \WpOrg\Requests\Utility\InputValidator::is_string_or_stringable()
  • \WpOrg\Requests\Exception\InvalidArgument::create()
  • \WpOrg\Requests\Requests::get_default_options()
  • \WpOrg\Requests\Requests::set_defaults()
  • \WpOrg\Requests\Requests::get_transport()
  • \WpOrg\Requests\Requests::parse_response()

Source code

View on Trac View on GitHub 

	public static function request($url, $headers = [], $data = [], $type = self::GET, $options = []) {		if (InputValidator::is_string_or_stringable($url) === false) {			throw InvalidArgument::create(1, '$url', 'string|Stringable', gettype($url));		} 		if (is_string($type) === false) {			throw InvalidArgument::create(4, '$type', 'string', gettype($type));		} 		if (is_array($options) === false) {			throw InvalidArgument::create(5, '$options', 'array', gettype($options));		} 		if (empty($options['type'])) {			$options['type'] = $type;		} 		$options = array_merge(self::get_default_options(), $options); 		self::set_defaults($url, $headers, $data, $type, $options); 		$options['hooks']->dispatch('requests.before_request', [&$url, &$headers, &$data, &$type, &$options]); 		if (!empty($options['transport'])) {			$transport = $options['transport']; 			if (is_string($options['transport'])) {				$transport = new $transport();			}		} else {			$need_ssl     = (stripos($url, 'https://') === 0);			$capabilities = [Capability::SSL => $need_ssl];			$transport    = self::get_transport($capabilities);		} 		$response = $transport->request($url, $headers, $data, $options); 		$options['hooks']->dispatch('requests.before_parse', [&$response, $url, $headers, $data, $type, $options]); 		return self::parse_response($response, $url, $headers, $data, $options);	}

Changelog

Unchanged from 6.7.7 through 7.1.0.

  1. 6.7.7
  2. 6.8.8
  3. 6.9.7
  4. 7.0.4
  5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data
Generated from the wordpress-develop 7.0.4 tag, from src/wp-includes/Requests/src/Requests.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.
Corrections
Something wrong on this page? Report it and it gets fixed in the next regeneration.