From e4a2e73d1119e4315d25a840d031238d7889f468 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Wed, 14 Sep 2022 13:06:53 +0000 Subject: [PATCH] Docs: Correct `@return` value for `wp_get_http_headers()`. Following the update to replace the HTTP API internals with Requests library in WordPress 4.6, the return value of `wp_remote_retrieve_headers()` has changed from a simple array to an object which implements `ArrayAccess`. Since `wp_get_http_headers()` directly returns the result of `wp_remote_retrieve_headers()`, its return value should reflect that change. Includes: * Updating the return value for the deprecated `wp_get_http()` function, which also directly returns the result of `wp_remote_retrieve_headers()`. * Minor DocBlock formatting changes for some other HTTP API functions per the documentation standards. Follow-up to [2416], [6390], [8092], [9013], [37428], [37989], [38730]. Props mhkuu. See #54225, #55646. git-svn-id: https://develop.svn.wordpress.org/trunk@54157 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/deprecated.php | 2 +- src/wp-includes/functions.php | 2 +- src/wp-includes/http.php | 16 ++++++++++------ 3 files changed, 12 insertions(+), 8 deletions(-) diff --git a/src/wp-includes/deprecated.php b/src/wp-includes/deprecated.php index 37bbadc62e..0a3d0f3092 100644 --- a/src/wp-includes/deprecated.php +++ b/src/wp-includes/deprecated.php @@ -3654,7 +3654,7 @@ function post_permalink( $post = 0 ) { * @param string|bool $file_path Optional. File path to write request to. Default false. * @param int $red Optional. The number of Redirects followed, Upon 5 being hit, * returns false. Default 1. - * @return bool|string False on failure and string of headers if HEAD request. + * @return \Requests_Utility_CaseInsensitiveDictionary|false Headers on success, false on failure. */ function wp_get_http( $url, $file_path = false, $red = 1 ) { _deprecated_function( __FUNCTION__, '4.4.0', 'WP_Http' ); diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php index 9b999e656b..9690e6128b 100644 --- a/src/wp-includes/functions.php +++ b/src/wp-includes/functions.php @@ -978,7 +978,7 @@ function do_enclose( $content, $post ) { * * @param string $url URL to retrieve HTTP headers from. * @param bool $deprecated Not Used. - * @return string|false Headers on success, false on failure. + * @return \Requests_Utility_CaseInsensitiveDictionary|false Headers on success, false on failure. */ function wp_get_http_headers( $url, $deprecated = false ) { if ( ! empty( $deprecated ) ) { diff --git a/src/wp-includes/http.php b/src/wp-includes/http.php index 0ef297921d..f77d9a69a7 100644 --- a/src/wp-includes/http.php +++ b/src/wp-includes/http.php @@ -205,7 +205,8 @@ function wp_remote_head( $url, $args = array() ) { * @see \Requests_Utility_CaseInsensitiveDictionary * * @param array|WP_Error $response HTTP response. - * @return array|\Requests_Utility_CaseInsensitiveDictionary The headers of the response. Empty array if incorrect parameter given. + * @return \Requests_Utility_CaseInsensitiveDictionary|array The headers of the response, or empty array + * if incorrect parameter given. */ function wp_remote_retrieve_headers( $response ) { if ( is_wp_error( $response ) || ! isset( $response['headers'] ) ) { @@ -245,7 +246,7 @@ function wp_remote_retrieve_header( $response, $header ) { * @since 2.7.0 * * @param array|WP_Error $response HTTP response. - * @return int|string The response code as an integer. Empty string on incorrect parameter given. + * @return int|string The response code as an integer. Empty string if incorrect parameter given. */ function wp_remote_retrieve_response_code( $response ) { if ( is_wp_error( $response ) || ! isset( $response['response'] ) || ! is_array( $response['response'] ) ) { @@ -263,7 +264,7 @@ function wp_remote_retrieve_response_code( $response ) { * @since 2.7.0 * * @param array|WP_Error $response HTTP response. - * @return string The response message. Empty string on incorrect parameter given. + * @return string The response message. Empty string if incorrect parameter given. */ function wp_remote_retrieve_response_message( $response ) { if ( is_wp_error( $response ) || ! isset( $response['response'] ) || ! is_array( $response['response'] ) ) { @@ -295,7 +296,8 @@ function wp_remote_retrieve_body( $response ) { * @since 4.4.0 * * @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. + * @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'] ) ) { @@ -312,7 +314,8 @@ function wp_remote_retrieve_cookies( $response ) { * * @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. + * @return WP_Http_Cookie|string The `WP_Http_Cookie` object, or empty string + * if the cookie is not present in the response. */ function wp_remote_retrieve_cookie( $response, $name ) { $cookies = wp_remote_retrieve_cookies( $response ); @@ -337,7 +340,8 @@ function wp_remote_retrieve_cookie( $response, $name ) { * * @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. + * @return string The value of the cookie, or empty string + * if the cookie is not present in the response. */ function wp_remote_retrieve_cookie_value( $response, $name ) { $cookie = wp_remote_retrieve_cookie( $response, $name );