WordPress.org
Get WordPress

Make WordPress Core

Changeset 46468


Ignore:
Timestamp:
10/12/2019 06:03:22 PM (5 years ago)
Author:
johnbillion
Message:

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

See #47110

Location:
trunk/src/wp-includes
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-http.php

    r46424 r46468  
    823823
    824824    /**
    825      * Block requests through the proxy.
     825     * Determines whether an HTTP API request to the given URL should be blocked.
    826826     *
    827827     * Those who are behind a proxy and want to prevent access to certain hosts may do so. This will
    828      * prevent plugins from working and core functionality, if you don't include api.wordpress.org.
    829      *
    830      * You block external URL requests by defining WP_HTTP_BLOCK_EXTERNAL as true in your wp-config.php
     828     * prevent plugins from working and core functionality, if you don't include `api.wordpress.org`.
     829     *
     830     * You block external URL requests by defining `WP_HTTP_BLOCK_EXTERNAL` as true in your `wp-config.php`
    831831     * file and this will only allow localhost and your site to make requests. The constant
    832      * WP_ACCESSIBLE_HOSTS will allow additional hosts to go through for requests. The format of the
    833      * WP_ACCESSIBLE_HOSTS constant is a comma separated list of hostnames to allow, wildcard domains
    834      * are supported, eg *.wordpress.org will allow for all subdomains of wordpress.org to be contacted.
     832     * `WP_ACCESSIBLE_HOSTS` will allow additional hosts to go through for requests. The format of the
     833     * `WP_ACCESSIBLE_HOSTS` constant is a comma separated list of hostnames to allow, wildcard domains
     834     * are supported, eg `*.wordpress.org` will allow for all subdomains of `wordpress.org` to be contacted.
    835835     *
    836836     * @since 2.8.0
    … …  
    860860        if ( 'localhost' == $check['host'] || ( isset( $home['host'] ) && $home['host'] == $check['host'] ) ) {
    861861            /**
    862              * Filters whether to block local requests through the proxy.
     862             * Filters whether to block local HTTP API requests.
     863             *
     864             * A local request is one to `localhost` or to the same host as the site itself.
    863865             *
    864866             * @since 2.8.0
    865867             *
    866              * @param bool $block Whether to block local requests through proxy.
    867              *                    Default false.
     868             * @param bool $block Whether to block local requests. Default false.
    868869             */
    869870            return apply_filters( 'block_local_requests', false );
    … …  
    994995     * @since 3.7.0
    995996     *
    996      * @param string $url The URL which was requested.
    997      * @param array $args The Arguments which were used to make the request.
    998      * @param array $response The Response of the HTTP request.
    999      * @return false|object False if no redirect is present, a WP_HTTP or WP_Error result otherwise.
     997     * @param string $url      The URL which was requested.
     998     * @param array  $args     The arguments which were used to make the request.
     999     * @param array  $response The response of the HTTP request.
     1000     * @return false|WP_Error|array False if no redirect is present, a WP_Error object if there's an error, or an HTTP
     1001     *                              API response array if the redirect is successfully followed.
    10001002     */
    10011003    public static function handle_redirects( $url, $args, $response ) {

  • trunk/src/wp-includes/class-wp-http-requests-response.php

    r46424 r46468  
    134134     * @since 4.6.0
    135135     *
    136      * @return mixed Response data.
     136     * @return string Response data.
    137137     */
    138138    public function get_data() {
    … …  
    145145     * @since 4.6.0
    146146     *
    147      * @param mixed $data Response data.
     147     * @param string $data Response data.
    148148     */
    149149    public function set_data( $data ) {

  • trunk/src/wp-includes/http.php

    r46424 r46468  
    4040 * @see WP_Http::request() For default arguments information.
    4141 *
    42  * @param string $url  Site URL to retrieve.
     42 * @param string $url  URL to retrieve.
    4343 * @param array  $args Optional. Request arguments. Default empty array.
    4444 * @return WP_Error|array The response or WP_Error on failure.
    … …  
    6161 * @see WP_Http::request() For default arguments information.
    6262 *
    63  * @param string $url  Site URL to retrieve.
     63 * @param string $url  URL to retrieve.
    6464 * @param array  $args Optional. Request arguments. Default empty array.
    6565 * @return WP_Error|array The response or WP_Error on failure.
    … …  
    8282 * @see WP_Http::request() For default arguments information.
    8383 *
    84  * @param string $url  Site URL to retrieve.
     84 * @param string $url  URL to retrieve.
    8585 * @param array  $args Optional. Request arguments. Default empty array.
    8686 * @return WP_Error|array The response or WP_Error on failure.
    … …  
    103103 * @see WP_Http::request() For default arguments information.
    104104 *
    105  * @param string $url Site URL to retrieve.
    106  * @param array $args Optional. Request arguments. Default empty array.
     105 * @param string $url URL to retrieve.
     106 * @param array  $args Optional. Request arguments. Default empty array.
    107107 * @return WP_Error|array The response or WP_Error on failure.
    108108 */
    … …  
    114114
    115115/**
    116  * Retrieve the raw response from the HTTP request.
    117  *
    118  * The array structure is a little complex:
    119  *
    120  *     $res = array(
    121  *         'headers'  => array(),
    122  *         'response' => array(
    123  *             'code'    => int,
    124  *             'message' => string
    125  *         )
    126  *     );
    127  *
    128  * All of the headers in $res['headers'] are with the name as the key and the
    129  * value as the value. So to get the User-Agent, you would do the following.
    130  *
    131  *     $user_agent = $res['headers']['user-agent'];
    132  *
    133  * The body is the raw response content and can be retrieved from $res['body'].
    134  *
    135  * This function is called first to make the request and there are other API
    136  * functions to abstract out the above convoluted setup.
    137  *
    138  * Request method defaults for helper functions:
     116 * Performs an HTTP request and returns its response.
     117 *
     118 * There are other API functions available which abstract away the HTTP method:
     119 *
    139120 *  - Default 'GET'  for wp_remote_get()
    140121 *  - Default 'POST' for wp_remote_post()
    … …  
    143124 * @since 2.7.0
    144125 *
    145  * @see WP_Http::request() For additional information on default arguments.
    146  *
    147  * @param string $url  Site URL to retrieve.
     126 * @see WP_Http::request() For information on default arguments.
     127 *
     128 * @param string $url  URL to retrieve.
    148129 * @param array  $args Optional. Request arguments. Default empty array.
    149  * @return WP_Error|array The response or WP_Error on failure.
     130 * @return WP_Error|array {
     131 *     The response array or a WP_Error on failure.
     132 *
     133 *     @type string[]                       $headers       Array of response headers keyed by their name.
     134 *     @type string                         $body          Response body.
     135 *     @type array                          $response      {
     136 *         Data about the HTTP response.
     137 *
     138 *         @type int|false    $code    HTTP response code.
     139 *         @type string|false $message HTTP response message.
     140 *     }
     141 *     @type WP_HTTP_Cookie[]               $cookies       Array of response cookies.
     142 *     @type WP_HTTP_Requests_Response|null $http_response Raw HTTP response object.
     143 * }
    150144 */
    151145function wp_remote_request( $url, $args = array() ) {
    … …  
    162156 * @see WP_Http::request() For default arguments information.
    163157 *
    164  * @param string $url  Site URL to retrieve.
     158 * @param string $url  URL to retrieve.
    165159 * @param array  $args Optional. Request arguments. Default empty array.
    166160 * @return WP_Error|array The response or WP_Error on failure.
    … …  
    179173 * @see WP_Http::request() For default arguments information.
    180174 *
    181  * @param string $url  Site URL to retrieve.
     175 * @param string $url  URL to retrieve.
    182176 * @param array  $args Optional. Request arguments. Default empty array.
    183177 * @return WP_Error|array The response or WP_Error on failure.
    … …  
    196190 * @see WP_Http::request() For default arguments information.
    197191 *
    198  * @param string $url  Site URL to retrieve.
     192 * @param string $url  URL to retrieve.
    199193 * @param array  $args Optional. Request arguments. Default empty array.
    200194 * @return WP_Error|array The response or WP_Error on failure.
    … …  
    213207 * @see \Requests_Utility_CaseInsensitiveDictionary
    214208 *
    215  * @param array $response HTTP response.
     209 * @param array|WP_Error $response HTTP response.
    216210 * @return array|\Requests_Utility_CaseInsensitiveDictionary The headers of the response. Empty array if incorrect parameter given.
    217211 */
    … …  
    229223 * @since 2.7.0
    230224 *
    231  * @param array  $response
    232  * @param string $header Header name to retrieve value from.
     225 * @param array|WP_Error $response HTTP response.
     226 * @param string         $header  Header name to retrieve value from.
    233227 * @return string The header value. Empty string on if incorrect parameter given, or if the header doesn't exist.
    234228 */
    … …  
    252246 * @since 2.7.0
    253247 *
    254  * @param array $response HTTP response.
     248 * @param array|WP_Error $response HTTP response.
    255249 * @return int|string The response code as an integer. Empty string on incorrect parameter given.
    256250 */
    … …  
    270264 * @since 2.7.0
    271265 *
    272  * @param array $response HTTP response.
     266 * @param array|WP_Error $response HTTP response.
    273267 * @return string The response message. Empty string on incorrect parameter given.
    274268 */
    … …  
    286280 * @since 2.7.0
    287281 *
    288  * @param array $response HTTP response.
     282 * @param array|WP_Error $response HTTP response.
    289283 * @return string The body of the response. Empty string if no body or incorrect parameter given.
    290284 */
    … …  
    302296 * @since 4.4.0
    303297 *
    304  * @param array $response HTTP response.
    305  * @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.
     298 * @param array|WP_Error $response HTTP response.
     299 * @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.
    306300 */
    307301function wp_remote_retrieve_cookies( $response ) {
    … …  
    318312 * @since 4.4.0
    319313 *
    320  * @param array  $response HTTP response.
    321  * @param string $name     The name of the cookie to retrieve.
     314 * @param array|WP_Error $response HTTP response.
     315 * @param string         $name     The name of the cookie to retrieve.
    322316 * @return WP_Http_Cookie|string The `WP_Http_Cookie` object. Empty string if the cookie isn't present in the response.
    323317 */
    … …  
    343337 * @since 4.4.0
    344338 *
    345  * @param array  $response HTTP response.
    346  * @param string $name     The name of the cookie to retrieve.
     339 * @param array|WP_Error $response HTTP response.
     340 * @param string         $name     The name of the cookie to retrieve.
    347341 * @return string The value of the cookie. Empty string if the cookie isn't present in the response.
    348342 */
Note: See TracChangeset for help on using the changeset viewer.