From 41d6b80d03629dba3460fb67663704fca381623c Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Sat, 12 Oct 2019 18:05:04 +0000 Subject: [PATCH] Docs: Fix and improve inline documentation for the HTTP API. See #47110 Built from https://develop.svn.wordpress.org/trunk@46468 git-svn-id: http://core.svn.wordpress.org/trunk@46266 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-http.php | 28 ++++--- .../class-wp-http-requests-response.php | 4 +- wp-includes/http.php | 82 +++++++++---------- wp-includes/version.php | 2 +- 4 files changed, 56 insertions(+), 60 deletions(-) diff --git a/wp-includes/class-http.php b/wp-includes/class-http.php index 00fd2ad849..b78e890413 100644 --- a/wp-includes/class-http.php +++ b/wp-includes/class-http.php @@ -822,16 +822,16 @@ class WP_Http { } /** - * Block requests through the proxy. + * Determines whether an HTTP API request to the given URL should be blocked. * * Those who are behind a proxy and want to prevent access to certain hosts may do so. This will - * prevent plugins from working and core functionality, if you don't include api.wordpress.org. + * prevent plugins from working and core functionality, if you don't include `api.wordpress.org`. * - * You block external URL requests by defining WP_HTTP_BLOCK_EXTERNAL as true in your wp-config.php + * You block external URL requests by defining `WP_HTTP_BLOCK_EXTERNAL` as true in your `wp-config.php` * file and this will only allow localhost and your site to make requests. The constant - * WP_ACCESSIBLE_HOSTS will allow additional hosts to go through for requests. The format of the - * WP_ACCESSIBLE_HOSTS constant is a comma separated list of hostnames to allow, wildcard domains - * are supported, eg *.wordpress.org will allow for all subdomains of wordpress.org to be contacted. + * `WP_ACCESSIBLE_HOSTS` will allow additional hosts to go through for requests. The format of the + * `WP_ACCESSIBLE_HOSTS` constant is a comma separated list of hostnames to allow, wildcard domains + * are supported, eg `*.wordpress.org` will allow for all subdomains of `wordpress.org` to be contacted. * * @since 2.8.0 * @link https://core.trac.wordpress.org/ticket/8927 Allow preventing external requests. @@ -859,12 +859,13 @@ class WP_Http { // Don't block requests back to ourselves by default. if ( 'localhost' == $check['host'] || ( isset( $home['host'] ) && $home['host'] == $check['host'] ) ) { /** - * Filters whether to block local requests through the proxy. + * Filters whether to block local HTTP API requests. + * + * A local request is one to `localhost` or to the same host as the site itself. * * @since 2.8.0 * - * @param bool $block Whether to block local requests through proxy. - * Default false. + * @param bool $block Whether to block local requests. Default false. */ return apply_filters( 'block_local_requests', false ); } @@ -993,10 +994,11 @@ class WP_Http { * * @since 3.7.0 * - * @param string $url The URL which was requested. - * @param array $args The Arguments which were used to make the request. - * @param array $response The Response of the HTTP request. - * @return false|object False if no redirect is present, a WP_HTTP or WP_Error result otherwise. + * @param string $url The URL which was requested. + * @param array $args The arguments which were used to make the request. + * @param array $response The response of the HTTP request. + * @return false|WP_Error|array False if no redirect is present, a WP_Error object if there's an error, or an HTTP + * API response array if the redirect is successfully followed. */ public static function handle_redirects( $url, $args, $response ) { // If no redirects are present, or, redirects were not requested, perform no action. diff --git a/wp-includes/class-wp-http-requests-response.php b/wp-includes/class-wp-http-requests-response.php index 2c836f6c15..45f83e2c7a 100644 --- a/wp-includes/class-wp-http-requests-response.php +++ b/wp-includes/class-wp-http-requests-response.php @@ -133,7 +133,7 @@ class WP_HTTP_Requests_Response extends WP_HTTP_Response { * * @since 4.6.0 * - * @return mixed Response data. + * @return string Response data. */ public function get_data() { return $this->response->body; @@ -144,7 +144,7 @@ class WP_HTTP_Requests_Response extends WP_HTTP_Response { * * @since 4.6.0 * - * @param mixed $data Response data. + * @param string $data Response data. */ public function set_data( $data ) { $this->response->body = $data; diff --git a/wp-includes/http.php b/wp-includes/http.php index 73eaefa603..36922da60e 100644 --- a/wp-includes/http.php +++ b/wp-includes/http.php @@ -39,7 +39,7 @@ function _wp_http_get_object() { * @see wp_remote_request() For more information on the response array format. * @see WP_Http::request() For default arguments information. * - * @param string $url Site URL to retrieve. + * @param string $url URL to retrieve. * @param array $args Optional. Request arguments. Default empty array. * @return WP_Error|array The response or WP_Error on failure. */ @@ -60,7 +60,7 @@ function wp_safe_remote_request( $url, $args = array() ) { * @see wp_remote_request() For more information on the response array format. * @see WP_Http::request() For default arguments information. * - * @param string $url Site URL to retrieve. + * @param string $url URL to retrieve. * @param array $args Optional. Request arguments. Default empty array. * @return WP_Error|array The response or WP_Error on failure. */ @@ -81,7 +81,7 @@ function wp_safe_remote_get( $url, $args = array() ) { * @see wp_remote_request() For more information on the response array format. * @see WP_Http::request() For default arguments information. * - * @param string $url Site URL to retrieve. + * @param string $url URL to retrieve. * @param array $args Optional. Request arguments. Default empty array. * @return WP_Error|array The response or WP_Error on failure. */ @@ -102,8 +102,8 @@ function wp_safe_remote_post( $url, $args = array() ) { * @see wp_remote_request() For more information on the response array format. * @see WP_Http::request() For default arguments information. * - * @param string $url Site URL to retrieve. - * @param array $args Optional. Request arguments. Default empty array. + * @param string $url URL to retrieve. + * @param array $args Optional. Request arguments. Default empty array. * @return WP_Error|array The response or WP_Error on failure. */ function wp_safe_remote_head( $url, $args = array() ) { @@ -113,40 +113,34 @@ function wp_safe_remote_head( $url, $args = array() ) { } /** - * Retrieve the raw response from the HTTP request. + * Performs an HTTP request and returns its response. * - * The array structure is a little complex: + * There are other API functions available which abstract away the HTTP method: * - * $res = array( - * 'headers' => array(), - * 'response' => array( - * 'code' => int, - * 'message' => string - * ) - * ); - * - * All of the headers in $res['headers'] are with the name as the key and the - * value as the value. So to get the User-Agent, you would do the following. - * - * $user_agent = $res['headers']['user-agent']; - * - * The body is the raw response content and can be retrieved from $res['body']. - * - * This function is called first to make the request and there are other API - * functions to abstract out the above convoluted setup. - * - * Request method defaults for helper functions: * - Default 'GET' for wp_remote_get() * - Default 'POST' for wp_remote_post() * - Default 'HEAD' for wp_remote_head() * * @since 2.7.0 * - * @see WP_Http::request() For additional information on default arguments. + * @see WP_Http::request() For information on default arguments. * - * @param string $url Site URL to retrieve. + * @param string $url URL to retrieve. * @param array $args Optional. Request arguments. Default empty array. - * @return WP_Error|array The response or WP_Error on failure. + * @return WP_Error|array { + * The response array or a WP_Error on failure. + * + * @type string[] $headers Array of response headers keyed by their name. + * @type string $body Response body. + * @type array $response { + * Data about the HTTP response. + * + * @type int|false $code HTTP response code. + * @type string|false $message HTTP response message. + * } + * @type WP_HTTP_Cookie[] $cookies Array of response cookies. + * @type WP_HTTP_Requests_Response|null $http_response Raw HTTP response object. + * } */ function wp_remote_request( $url, $args = array() ) { $http = _wp_http_get_object(); @@ -161,7 +155,7 @@ function wp_remote_request( $url, $args = array() ) { * @see wp_remote_request() For more information on the response array format. * @see WP_Http::request() For default arguments information. * - * @param string $url Site URL to retrieve. + * @param string $url URL to retrieve. * @param array $args Optional. Request arguments. Default empty array. * @return WP_Error|array The response or WP_Error on failure. */ @@ -178,7 +172,7 @@ function wp_remote_get( $url, $args = array() ) { * @see wp_remote_request() For more information on the response array format. * @see WP_Http::request() For default arguments information. * - * @param string $url Site URL to retrieve. + * @param string $url URL to retrieve. * @param array $args Optional. Request arguments. Default empty array. * @return WP_Error|array The response or WP_Error on failure. */ @@ -195,7 +189,7 @@ function wp_remote_post( $url, $args = array() ) { * @see wp_remote_request() For more information on the response array format. * @see WP_Http::request() For default arguments information. * - * @param string $url Site URL to retrieve. + * @param string $url URL to retrieve. * @param array $args Optional. Request arguments. Default empty array. * @return WP_Error|array The response or WP_Error on failure. */ @@ -212,7 +206,7 @@ function wp_remote_head( $url, $args = array() ) { * * @see \Requests_Utility_CaseInsensitiveDictionary * - * @param array $response HTTP response. + * @param array|WP_Error $response HTTP response. * @return array|\Requests_Utility_CaseInsensitiveDictionary The headers of the response. Empty array if incorrect parameter given. */ function wp_remote_retrieve_headers( $response ) { @@ -228,8 +222,8 @@ function wp_remote_retrieve_headers( $response ) { * * @since 2.7.0 * - * @param array $response - * @param string $header Header name to retrieve value from. + * @param array|WP_Error $response HTTP response. + * @param string $header Header name to retrieve value from. * @return string The header value. Empty string on if incorrect parameter given, or if the header doesn't exist. */ function wp_remote_retrieve_header( $response, $header ) { @@ -251,7 +245,7 @@ function wp_remote_retrieve_header( $response, $header ) { * * @since 2.7.0 * - * @param array $response HTTP response. + * @param array|WP_Error $response HTTP response. * @return int|string The response code as an integer. Empty string on incorrect parameter given. */ function wp_remote_retrieve_response_code( $response ) { @@ -269,7 +263,7 @@ function wp_remote_retrieve_response_code( $response ) { * * @since 2.7.0 * - * @param array $response HTTP response. + * @param array|WP_Error $response HTTP response. * @return string The response message. Empty string on incorrect parameter given. */ function wp_remote_retrieve_response_message( $response ) { @@ -285,7 +279,7 @@ function wp_remote_retrieve_response_message( $response ) { * * @since 2.7.0 * - * @param array $response HTTP response. + * @param array|WP_Error $response HTTP response. * @return string The body of the response. Empty string if no body or incorrect parameter given. */ function wp_remote_retrieve_body( $response ) { @@ -301,8 +295,8 @@ function wp_remote_retrieve_body( $response ) { * * @since 4.4.0 * - * @param array $response HTTP response. - * @return array An array of `WP_Http_Cookie` objects from the response. Empty array if there are none, or the response is a WP_Error. + * @param array|WP_Error $response HTTP response. + * @return WP_Http_Cookie[] An array of `WP_Http_Cookie` objects from the response. Empty array if there are none, or the response is a WP_Error. */ function wp_remote_retrieve_cookies( $response ) { if ( is_wp_error( $response ) || empty( $response['cookies'] ) ) { @@ -317,8 +311,8 @@ function wp_remote_retrieve_cookies( $response ) { * * @since 4.4.0 * - * @param array $response HTTP response. - * @param string $name The name of the cookie to retrieve. + * @param array|WP_Error $response HTTP response. + * @param string $name The name of the cookie to retrieve. * @return WP_Http_Cookie|string The `WP_Http_Cookie` object. Empty string if the cookie isn't present in the response. */ function wp_remote_retrieve_cookie( $response, $name ) { @@ -342,8 +336,8 @@ function wp_remote_retrieve_cookie( $response, $name ) { * * @since 4.4.0 * - * @param array $response HTTP response. - * @param string $name The name of the cookie to retrieve. + * @param array|WP_Error $response HTTP response. + * @param string $name The name of the cookie to retrieve. * @return string The value of the cookie. Empty string if the cookie isn't present in the response. */ function wp_remote_retrieve_cookie_value( $response, $name ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index 826facd032..a7bb745117 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.3-beta3-46467'; +$wp_version = '5.3-beta3-46468'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.