IntenseWebs/WordPress
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs: Fix and improve inline documentation for the HTTP API.

Browse Source 
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
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
* 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.

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
*
* @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;

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_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 ) {

2
wp-includes/version.php
View File

@@ -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.