Make WordPress Core

Changeset 29230


Ignore:
Timestamp:
07/18/2014 10:00:51 PM (11 years ago)
Author:
DrewAPicture
Message:

Convert documentation for default arguments in WP_Http::request() to a hash notation.

Also update corresponding docs for functions that leverage its arguments.

See #28298.

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

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/class-http.php

    r29229 r29230  
    2929
    3030    /**
    31      * Send a HTTP request to a URI.
    32      *
    33      * The body and headers are part of the arguments. The 'body' argument is for the body and will
    34      * accept either a string or an array. The 'headers' argument should be an array, but a string
    35      * is acceptable. If the 'body' argument is an array, then it will automatically be escaped
    36      * using http_build_query().
    37      *
    38      * The only URI that are supported in the HTTP Transport implementation are the HTTP and HTTPS
    39      * protocols.
    40      *
    41      * The defaults are 'method', 'timeout', 'redirection', 'httpversion', 'blocking' and
    42      * 'user-agent'.
    43      *
    44      * Accepted 'method' values are 'GET', 'POST', and 'HEAD', some transports technically allow
    45      * others, but should not be assumed. The 'timeout' is used to sent how long the connection
    46      * should stay open before failing when no response. 'redirection' is used to track how many
    47      * redirects were taken and used to sent the amount for other transports, but not all transports
    48      * accept setting that value.
    49      *
    50      * The 'httpversion' option is used to sent the HTTP version and accepted values are '1.0', and
    51      * '1.1' and should be a string. The 'user-agent' option is the user-agent and is used to
    52      * replace the default user-agent, which is 'WordPress/WP_Version', where WP_Version is the
    53      * value from $wp_version.
    54      *
    55      * The 'blocking' parameter can be used to specify if the calling code requires the result of
    56      * the HTTP request. If set to false, the request will be sent to the remote server, and
    57      * processing returned to the calling code immediately, the caller will know if the request
    58      * suceeded or failed, but will not receive any response from the remote server.
     31     * Send an HTTP request to a URI.
     32     *
     33     * Please note: The only URI that are supported in the HTTP Transport implementation
     34     * are the HTTP and HTTPS protocols.
    5935     *
    6036     * @access public
    6137     * @since 2.7.0
    6238     *
    63      * @param string $url The request URL.
    64      * @param string|array $args Optional. Override the defaults.
    65      * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
     39     * @param string       $url  The request URL.
     40     * @param string|array $args {
     41     *     Optional. Array or string of HTTP request arguments.
     42     *
     43     *     @type string       $method              Request method. Accepts 'GET', 'POST', 'HEAD', or 'PUT'.
     44     *                                             Some transports technically allow others, but should not be
     45     *                                             assumed. Default 'GET'.
     46     *     @type int          $timeout             How long the connection should stay open in seconds. Default 5.
     47     *     @type int          $redirection         Number of allowed redirects. Not supported by all transports
     48     *                                             Default 5.
     49     *     @type string       $httpversion         Version of the HTTP protocol to use. Accepts '1.0' and '1.1'.
     50     *                                             Default '1.0'.
     51     *     @type string       $user-agent          User-agent value sent.
     52     *                                             Default WordPress/' . $wp_version . '; ' . get_bloginfo( 'url' ).
     53     *     @type bool         $reject_unsafe_urls  Whether to pass URLs through {@see wp_http_validate_url()}.
     54     *                                             Default false.
     55     *     @type bool         $blocking            Whether the calling code requires the result of the request.
     56     *                                             If set to false, the request will be sent to the remote server,
     57     *                                             and processing returned to the calling code immediately, the caller
     58     *                                             will know if the request succeeded or failed, but will not receive
     59     *                                             any response from the remote server. Default true.
     60     *     @type string|array $headers             Array or string of headers to send with the request.
     61     *                                             Default empty array.
     62     *     @type array        $cookies             List of cookies to send with the request. Default empty array.
     63     *     @type string|array $body                Body to send with the request. Default null.
     64     *     @type bool         $compress            Whether to compress the $body when sending the request.
     65     *                                             Default false.
     66     *     @type bool         $decompress          Whether to decompress a compressed response. If set to false and
     67     *                                             compressed content is returned in the response anyway, it will
     68     *                                             need to be separately decompressed. Default true.
     69     *     @type bool         $sslverify           Whether to verify SSL for the request. Default true.
     70     *     @type string       sslcertificates      Absolute path to an SSL certificate .crt file.
     71     *                                             Default ABSPATH . WPINC . '/certificates/ca-bundle.crt'.
     72     *     @type bool         $stream              Whether to stream to a file. If set to true and no filename was
     73     *                                             given, it will be droped it in the WP temp dir and its name will
     74     *                                             be set using the basename of the URL. Default false.
     75     *     @type string       $filename            Filename of the file to write to when streaming. $stream must be
     76     *                                             set to true. Default null.
     77     *     @type int          $limit_response_size Size in bytes to limit the response to. Default null.
     78     *
     79     * }
     80     * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
     81     *                        A WP_Error instance upon error.
    6682     */
    6783    public function request( $url, $args = array() ) {
  • trunk/src/wp-includes/http.php

    r28257 r29230  
    3535 * URL. The URL is validated to avoid redirection and request forgery attacks.
    3636 *
    37  * @see wp_remote_request() For more information on the response array format
    38  *  and default arguments.
    39  *
    4037 * @since 3.6.0
    4138 *
    42  * @param string $url Site URL to retrieve.
    43  * @param array $args Optional. Override the defaults.
     39 * @see wp_remote_request() For more information on the response array format.
     40 * @see WP_Http::request() For default arguments information.
     41 *
     42 * @param string $url  Site URL to retrieve.
     43 * @param array  $args Optional. Request arguments. Default empty array.
    4444 * @return WP_Error|array The response or WP_Error on failure.
    4545 */
     
    5656 * URL. The URL is validated to avoid redirection and request forgery attacks.
    5757 *
    58  * @see wp_remote_request() For more information on the response array format
    59  *  and default arguments.
    60  *
    6158 * @since 3.6.0
    6259 *
    63  * @param string $url Site URL to retrieve.
    64  * @param array $args Optional. Override the defaults.
     60 * @see wp_remote_request() For more information on the response array format.
     61 * @see WP_Http::request() For default arguments information.
     62 *
     63 * @param string $url  Site URL to retrieve.
     64 * @param array  $args Optional. Request arguments. Default empty array.
    6565 * @return WP_Error|array The response or WP_Error on failure.
    6666 */
     
    7777 * URL. The URL is validated to avoid redirection and request forgery attacks.
    7878 *
    79  * @see wp_remote_request() For more information on the response array format
    80  *  and default arguments.
    81  *
    8279 * @since 3.6.0
    8380 *
    84  * @param string $url Site URL to retrieve.
    85  * @param array $args Optional. Override the defaults.
     81 * @see wp_remote_request() For more information on the response array format.
     82 * @see WP_Http::request() For default arguments information.
     83 *
     84 * @param string $url  Site URL to retrieve.
     85 * @param array  $args Optional. Request arguments. Default empty array.
    8686 * @return WP_Error|array The response or WP_Error on failure.
    8787 */
     
    9898 * URL. The URL is validated to avoid redirection and request forgery attacks.
    9999 *
    100  * @see wp_remote_request() For more information on the response array format
    101  *  and default arguments.
    102  *
    103100 * @since 3.6.0
    104101 *
     102 * @see wp_remote_request() For more information on the response array format.
     103 * @see WP_Http::request() For default arguments information.
     104 *
    105105 * @param string $url Site URL to retrieve.
    106  * @param array $args Optional. Override the defaults.
     106 * @param array $args Optional. Request arguments. Default empty array.
    107107 * @return WP_Error|array The response or WP_Error on failure.
    108108 */
     
    116116 * Retrieve the raw response from the HTTP request.
    117117 *
    118  * The array structure is a little complex.
    119  *
    120  * <code>
    121  * $res = array( 'headers' => array(), 'response' => array('code' => int, 'message' => string) );
    122  * </code>
     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 *     );
    123127 *
    124128 * All of the headers in $res['headers'] are with the name as the key and the
    125129 * value as the value. So to get the User-Agent, you would do the following.
    126130 *
    127  * <code>
    128  * $user_agent = $res['headers']['user-agent'];
    129  * </code>
     131 *     $user_agent = $res['headers']['user-agent'];
    130132 *
    131133 * The body is the raw response content and can be retrieved from $res['body'].
     
    134136 * functions to abstract out the above convoluted setup.
    135137 *
    136  * List of default arguments:
    137  * 'method'      => 'GET'
     138 * Request method defaults for helper functions:
    138139 *  - Default 'GET'  for wp_remote_get()
    139140 *  - Default 'POST' for wp_remote_post()
    140141 *  - Default 'HEAD' for wp_remote_head()
    141  * 'timeout'     => 5
    142  * 'redirection' => 5
    143  * 'httpversion' => '1.0'
    144  * 'user-agent'  => 'WordPress/' . $wp_version . '; ' . get_bloginfo( 'url' )
    145  * 'blocking'    => true
    146  * 'headers'     => array()
    147  * 'cookies'     => array()
    148  * 'body'        => null
    149  * 'compress'    => false,
    150  * 'decompress'  => true,
    151  * 'sslverify'   => true,
    152  * 'stream'      => false,
    153  * 'filename'    => null
    154  *
    155  * @since 2.7.0
    156  *
    157  * @param string $url Site URL to retrieve.
    158  * @param array $args Optional. Override the defaults.
     142 *
     143 * @since 2.7.0
     144 *
     145 * @see WP_Http::request() For additional information on default arguments.
     146 *
     147 * @param string $url  Site URL to retrieve.
     148 * @param array  $args Optional. Request arguments. Default empty array.
    159149 * @return WP_Error|array The response or WP_Error on failure.
    160150 */
     
    167157 * Retrieve the raw response from the HTTP request using the GET method.
    168158 *
    169  * @see wp_remote_request() For more information on the response array format and default arguments.
    170  *
    171  * @since 2.7.0
    172  *
    173  * @param string $url Site URL to retrieve.
    174  * @param array $args Optional. Override the defaults.
     159 * @since 2.7.0
     160 *
     161 * @see wp_remote_request() For more information on the response array format.
     162 * @see WP_Http::request() For default arguments information.
     163 *
     164 * @param string $url  Site URL to retrieve.
     165 * @param array  $args Optional. Request arguments. Default empty array.
    175166 * @return WP_Error|array The response or WP_Error on failure.
    176167 */
     
    183174 * Retrieve the raw response from the HTTP request using the POST method.
    184175 *
    185  * @see wp_remote_request() For more information on the response array format and default arguments.
    186  *
    187  * @since 2.7.0
    188  *
    189  * @param string $url Site URL to retrieve.
    190  * @param array $args Optional. Override the defaults.
     176 * @since 2.7.0
     177 *
     178 * @see wp_remote_request() For more information on the response array format.
     179 * @see WP_Http::request() For default arguments information.
     180 *
     181 * @param string $url  Site URL to retrieve.
     182 * @param array  $args Optional. Request arguments. Default empty array.
    191183 * @return WP_Error|array The response or WP_Error on failure.
    192184 */
     
    199191 * Retrieve the raw response from the HTTP request using the HEAD method.
    200192 *
    201  * @see wp_remote_request() For more information on the response array format and default arguments.
    202  *
    203  * @since 2.7.0
    204  *
    205  * @param string $url Site URL to retrieve.
    206  * @param array $args Optional. Override the defaults.
     193 * @since 2.7.0
     194 *
     195 * @see wp_remote_request() For more information on the response array format.
     196 * @see WP_Http::request() For default arguments information.
     197 *
     198 * @param string $url  Site URL to retrieve.
     199 * @param array  $args Optional. Request arguments. Default empty array.
    207200 * @return WP_Error|array The response or WP_Error on failure.
    208201 */
Note: See TracChangeset for help on using the changeset viewer.