WP_Http::request( string $url, string|array $args = array() ): array|WP_Error

Description

Compatibility

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

Parameters

$urlstring

The request URL.

$argsstring|arrayoptional

Array or string of HTTP request arguments.Default: array()

• $methodstringdefault: 'GET'

  Request method. Accepts 'GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'TRACE', 'OPTIONS', or 'PATCH'. Some transports technically allow others, but should not be assumed.

• $timeoutfloatdefault: 5

  How long the connection should stay open in seconds.

• $redirectionintdefault: 5

  Number of allowed redirects. Not supported by all transports.

• $httpversionstringdefault: '1.0'

  Version of the HTTP protocol to use. Accepts '1.0' and '1.1'.

• $userstringdefault: 'WordPress/' . get_bloginfo( 'version' ) . '; ' . get_bloginfo( 'url' )

  -agent User-agent value sent.

• $reject_unsafe_urlsbooldefault: false

  Whether to pass URLs through wp_http_validate_url().

• $blockingbooldefault: true

  Whether the calling code requires the result of the request. If set to false, the request will be sent to the remote server, and processing returned to the calling code immediately, the caller will know if the request succeeded or failed, but will not receive any response from the remote server.

• $headersstring|arraydefault: empty array

  Array or string of headers to send with the request.

• $cookiesarraydefault: empty array

  List of cookies to send with the request.

• $bodystring|arraydefault: null

  Body to send with the request.

• $compressbooldefault: false

  Whether to compress the $body when sending the request.

• $decompressbooldefault: true

  Whether to decompress a compressed response. If set to false and compressed content is returned in the response anyway, it will need to be separately decompressed.

• $sslverifybooldefault: true

  Whether to verify SSL for the request.

• $sslcertificatesstringdefault: ABSPATH . WPINC . '/certificates/ca-bundle.crt'

  Absolute path to an SSL certificate .crt file.

• $streambooldefault: false

  Whether to stream to a file. If set to true and no filename was given, it will be dropped it in the WP temp dir and its name will be set using the basename of the URL.

• $filenamestringdefault: null

  Filename of the file to write to when streaming. $stream must be set to true.

• $limit_response_sizeintdefault: null

  Size in bytes to limit the response to.

Return value

array|WP_Error

Array of response data, or a WP_Error instance upon error.

• $headers\WpOrg\Requests\Utility\CaseInsensitiveDictionary

  Response headers keyed by name.

• $bodystring

  Response body.

• $responsearray

  Array of HTTP response data.

  • $codeint|false

    HTTP response status code.

  • $messagestring|false

    HTTP response message. } @type WP_HTTP_Cookie[] $cookies Array of cookies set by the server.

  • $filenamestring|null

    Optional. Filename of the response.

  • $http_responseWP_HTTP_Requests_Response|null

    Response object.

Performance profile

How much work a call to WP_Http::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

Moderate

Reads stored settings via get_option(), cached per request but not free on a cold cache.

Scaling

Constant

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

Instructions

113–279

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

Plugin surface

10 hooks

Third-party callbacks on 'http_request_timeout', 'http_request_redirection_count', 'http_request_version' run inside this call, and their cost is not bounded by anything here.

Called by

3

3 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• optionoption read or writeget_option()one call below WP_Http::request()

Further down the call graph this can also reach cache, serialize, query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 33 distinct outcomes

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

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 13

13 hooks fire while WP_Http::request() runs, in this order:

1. 1
   apply_filters( http_request_timeout )filterline 176 (+12 into the body)

   Filters the timeout value for an HTTP request.

2. 2
   apply_filters( http_request_redirection_count )filterline 186 (+22 into the body)

   Filters the number of redirects allowed during an HTTP request.

3. 3
   apply_filters( http_request_version )filterline 196 (+32 into the body)

   Filters the version of the HTTP protocol used in a request.

4. 4
   apply_filters( http_headers_useragent )filterline 206 (+42 into the body)

   Filters the user agent value sent with an HTTP request.

5. 5
   apply_filters( http_request_reject_unsafe_urls )filterline 216 (+52 into the body)

   Filters whether to pass URLs through wp_http_validate_url() in an HTTP request.

6. 6
   apply_filters( http_request_args )filterline 247 (+83 into the body)

   Filters the arguments used in an HTTP request.

7. 7
   apply_filters( pre_http_request )filterline 272 (+108 into the body)

   Filters the preemptive return value of an HTTP request.

8. 8
   do_action( http_api_debug )actionline 292 (+128 into the body)

   Fires after an HTTP API response is received and before the response is returned.

9. 9
   do_action( http_api_debug )actionline 299 (+135 into the body)

   Fires after an HTTP API response is received and before the response is returned.

10. 10
    do_action( http_api_debug )actionline 316 (+152 into the body)

    Fires after an HTTP API response is received and before the response is returned.

11. 11
    apply_filters( https_ssl_verify )filterline 392 (+228 into the body)

    Filters whether SSL should be verified for non-local requests.

12. 12
    do_action( http_api_debug )actionline 435 (+271 into the body)

    Fires after an HTTP API response is received and before the response is returned.

13. 13
    apply_filters( http_response )filterline 462 (+298 into the body)

    Filters a successful HTTP API response immediately before the response is returned.

Uses · 21

• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_bloginfo()Retrieves information about the current site.
• wp_parse_args()Merges user defined arguments into defaults array.
• wp_http_validate_url()Validates a URL for safe use in the HTTP API.
• wp_kses_bad_protocol()Sanitizes a string and removed disallowed URL protocols.
• __()Retrieves the translation of $text.
• do_action()Calls the callback functions that have been added to an action hook.
• get_temp_dir()Determines a writable directory for temporary files.
• wp_is_writable()Determines if a directory is writable.
• mbstring_binary_safe_encoding()Sets the mbstring internal encoding to a binary safe encoding when func_overload is enabled.
• reset_mbstring_encoding()Resets the mbstring internal encoding to a users previously set encoding.
• is_wp_error()Checks whether the given variable is a WordPress Error.

Used by · 3

• WP_Http::get()Uses the GET HTTP method.
• WP_Http::head()Uses the HEAD HTTP method.
• WP_Http::post()Uses the POST HTTP method.

Source code

View on Trac ↗View on GitHub ↗

164	public function request( $url, $args = array() ) {165		$defaults = array(166			'method'              => 'GET',167			/**168			 * Filters the timeout value for an HTTP request.169			 *170			 * @since 2.7.0171			 * @since 5.1.0 The `$url` parameter was added.172			 *173			 * @param float  $timeout_value Time in seconds until a request times out. Default 5.174			 * @param string $url           The request URL.175			 */176			'timeout'             => apply_filters( 'http_request_timeout', 5, $url ),177			/**178			 * Filters the number of redirects allowed during an HTTP request.179			 *180			 * @since 2.7.0181			 * @since 5.1.0 The `$url` parameter was added.182			 *183			 * @param int    $redirect_count Number of redirects allowed. Default 5.184			 * @param string $url            The request URL.185			 */186			'redirection'         => apply_filters( 'http_request_redirection_count', 5, $url ),187			/**188			 * Filters the version of the HTTP protocol used in a request.189			 *190			 * @since 2.7.0191			 * @since 5.1.0 The `$url` parameter was added.192			 *193			 * @param string $version Version of HTTP used. Accepts '1.0' and '1.1'. Default '1.0'.194			 * @param string $url     The request URL.195			 */196			'httpversion'         => apply_filters( 'http_request_version', '1.0', $url ),197			/**198			 * Filters the user agent value sent with an HTTP request.199			 *200			 * @since 2.7.0201			 * @since 5.1.0 The `$url` parameter was added.202			 *203			 * @param string $user_agent WordPress user agent string.204			 * @param string $url        The request URL.205			 */206			'user-agent'          => apply_filters( 'http_headers_useragent', 'WordPress/' . get_bloginfo( 'version' ) . '; ' . get_bloginfo( 'url' ), $url ),207			/**208			 * Filters whether to pass URLs through wp_http_validate_url() in an HTTP request.209			 *210			 * @since 3.6.0211			 * @since 5.1.0 The `$url` parameter was added.212			 *213			 * @param bool   $pass_url Whether to pass URLs through wp_http_validate_url(). Default false.214			 * @param string $url      The request URL.215			 */216			'reject_unsafe_urls'  => apply_filters( 'http_request_reject_unsafe_urls', false, $url ),217			'blocking'            => true,218			'headers'             => array(),219			'cookies'             => array(),220			'body'                => null,221			'compress'            => false,222			'decompress'          => true,223			'sslverify'           => true,224			'sslcertificates'     => ABSPATH . WPINC . '/certificates/ca-bundle.crt',225			'stream'              => false,226			'filename'            => null,227			'limit_response_size' => null,228		);229 230		// Pre-parse for the HEAD checks.231		$args = wp_parse_args( $args );232 233		// By default, HEAD requests do not cause redirections.234		if ( isset( $args['method'] ) && 'HEAD' === $args['method'] ) {235			$defaults['redirection'] = 0;236		}237 238		$parsed_args = wp_parse_args( $args, $defaults );239		/**240		 * Filters the arguments used in an HTTP request.241		 *242		 * @since 2.7.0243		 *

Changelog

Introduced in 2.7.0. 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 6.7.7 tag, from src/wp-includes/class-wp-http.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.