WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
John Blackbourn 2019-10-12 18:05:04 +00:00
parent 634242343c
commit 41d6b80d03
4 changed files with 56 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
wp-includes/class-http.php
View File

@ -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 * 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 * 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` 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 * `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. * are supported, eg `*.wordpress.org` will allow for all subdomains of `wordpress.org` to be contacted.
* *
* @since 2.8.0 * @since 2.8.0
* @link https://core.trac.wordpress.org/ticket/8927 Allow preventing external requests. * @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. // Don't block requests back to ourselves by default.
if ( 'localhost' == $check['host'] || ( isset( $home['host'] ) && $home['host'] == $check['host'] ) ) { 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 * @since 2.8.0
* *
* @param bool $block Whether to block local requests through proxy. * @param bool $block Whether to block local requests. Default false.
* Default false.
*/ */
return apply_filters( 'block_local_requests', false ); return apply_filters( 'block_local_requests', false );
} }
@ -993,10 +994,11 @@ class WP_Http {
* *
* @since 3.7.0 * @since 3.7.0
* *
* @param string $url The URL which was requested. * @param string $url The URL which was requested.
* @param array $args The Arguments which were used to make the request. * @param array $args The arguments which were used to make the request.
* @param array $response The Response of the HTTP 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. * @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 ) { public static function handle_redirects( $url, $args, $response ) {
// If no redirects are present, or, redirects were not requested, perform no action. // If no redirects are present, or, redirects were not requested, perform no action.

4
wp-includes/class-wp-http-requests-response.php
View File

@ -133,7 +133,7 @@ class WP_HTTP_Requests_Response extends WP_HTTP_Response {
* *
* @since 4.6.0 * @since 4.6.0
* *
* @return mixed Response data. * @return string Response data.
*/ */
public function get_data() { public function get_data() {
return $this->response->body; return $this->response->body;
@ -144,7 +144,7 @@ class WP_HTTP_Requests_Response extends WP_HTTP_Response {
* *
* @since 4.6.0 * @since 4.6.0
* *
* @param mixed $data Response data. * @param string $data Response data.
*/ */
public function set_data( $data ) { public function set_data( $data ) {
$this->response->body = $data; $this->response->body = $data;

82
wp-includes/http.php
View File

@ -39,7 +39,7 @@ function _wp_http_get_object() {
* @see wp_remote_request() For more information on the response array format. * @see wp_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information. * @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. * @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 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_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information. * @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. * @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 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_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information. * @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. * @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 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_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information. * @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. * @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 or WP_Error on failure.
*/ */
function wp_safe_remote_head( $url, $args = array() ) { 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 'GET' for wp_remote_get()
* - Default 'POST' for wp_remote_post() * - Default 'POST' for wp_remote_post()
* - Default 'HEAD' for wp_remote_head() * - Default 'HEAD' for wp_remote_head()
* *
* @since 2.7.0 * @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. * @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() ) { function wp_remote_request( $url, $args = array() ) {
$http = _wp_http_get_object(); $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_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information. * @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. * @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 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_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information. * @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. * @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 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_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information. * @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. * @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 or WP_Error on failure.
*/ */
@ -212,7 +206,7 @@ function wp_remote_head( $url, $args = array() ) {
* *
* @see \Requests_Utility_CaseInsensitiveDictionary * @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. * @return array|\Requests_Utility_CaseInsensitiveDictionary The headers of the response. Empty array if incorrect parameter given.
*/ */
function wp_remote_retrieve_headers( $response ) { function wp_remote_retrieve_headers( $response ) {
@ -228,8 +222,8 @@ function wp_remote_retrieve_headers( $response ) {
* *
* @since 2.7.0 * @since 2.7.0
* *
* @param array $response * @param array|WP_Error $response HTTP response.
* @param string $header Header name to retrieve value from. * @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. * @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 ) { function wp_remote_retrieve_header( $response, $header ) {
@ -251,7 +245,7 @@ function wp_remote_retrieve_header( $response, $header ) {
* *
* @since 2.7.0 * @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. * @return int|string The response code as an integer. Empty string on incorrect parameter given.
*/ */
function wp_remote_retrieve_response_code( $response ) { function wp_remote_retrieve_response_code( $response ) {
@ -269,7 +263,7 @@ function wp_remote_retrieve_response_code( $response ) {
* *
* @since 2.7.0 * @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. * @return string The response message. Empty string on incorrect parameter given.
*/ */
function wp_remote_retrieve_response_message( $response ) { function wp_remote_retrieve_response_message( $response ) {
@ -285,7 +279,7 @@ function wp_remote_retrieve_response_message( $response ) {
* *
* @since 2.7.0 * @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. * @return string The body of the response. Empty string if no body or incorrect parameter given.
*/ */
function wp_remote_retrieve_body( $response ) { function wp_remote_retrieve_body( $response ) {
@ -301,8 +295,8 @@ function wp_remote_retrieve_body( $response ) {
* *
* @since 4.4.0 * @since 4.4.0
* *
* @param array $response HTTP response. * @param array|WP_Error $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. * @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 ) { function wp_remote_retrieve_cookies( $response ) {
if ( is_wp_error( $response ) || empty( $response['cookies'] ) ) { if ( is_wp_error( $response ) || empty( $response['cookies'] ) ) {
@ -317,8 +311,8 @@ function wp_remote_retrieve_cookies( $response ) {
* *
* @since 4.4.0 * @since 4.4.0
* *
* @param array $response HTTP response. * @param array|WP_Error $response HTTP response.
* @param string $name The name of the cookie to retrieve. * @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. Empty string if the cookie isn't present in the response.
*/ */
function wp_remote_retrieve_cookie( $response, $name ) { function wp_remote_retrieve_cookie( $response, $name ) {
@ -342,8 +336,8 @@ function wp_remote_retrieve_cookie( $response, $name ) {
* *
* @since 4.4.0 * @since 4.4.0
* *
* @param array $response HTTP response. * @param array|WP_Error $response HTTP response.
* @param string $name The name of the cookie to retrieve. * @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. Empty string if the cookie isn't present in the response.
*/ */
function wp_remote_retrieve_cookie_value( $response, $name ) { function wp_remote_retrieve_cookie_value( $response, $name ) {

2
wp-includes/version.php
View File

@ -13,7 +13,7 @@
* *
* @global string $wp_version * @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. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.