wp-includes/http.php

   1 <?php
   2 /**
   3  * Simple and uniform HTTP request API.
   4  *
   5  * Will eventually replace and standardize the WordPress HTTP requests made.
   6  *
   7  * @link http://trac.wordpress.org/ticket/4779 HTTP API Proposal
   8  *
   9  * @package WordPress
  10  * @subpackage HTTP
  11  * @since 2.7.0
  12  */
  13
  14 /**
  15  * Returns the initialized WP_Http Object
  16  *
  17  * @since 2.7.0
  18  * @access private
  19  *
  20  * @return WP_Http HTTP Transport object.
  21  */
  22 function &_wp_http_get_object() {
  23         static $http;
  24
  25         if ( is_null($http) )
  26                 $http = new WP_Http();
  27
  28         return $http;
  29 }
  30
  31 /**
  32  * Retrieve the raw response from the HTTP request.
  33  *
  34  * The array structure is a little complex.
  35  *
  36  * <code>
  37  * $res = array( 'headers' => array(), 'response' => array('code' => int, 'message' => string) );
  38  * </code>
  39  *
  40  * All of the headers in $res['headers'] are with the name as the key and the
  41  * value as the value. So to get the User-Agent, you would do the following.
  42  *
  43  * <code>
  44  * $user_agent = $res['headers']['user-agent'];
  45  * </code>
  46  *
  47  * The body is the raw response content and can be retrieved from $res['body'].
  48  *
  49  * This function is called first to make the request and there are other API
  50  * functions to abstract out the above convoluted setup.
  51  *
  52  * @since 2.7.0
  53  *
  54  * @param string $url Site URL to retrieve.
  55  * @param array $args Optional. Override the defaults.
  56  * @return WP_Error|array The response or WP_Error on failure.
  57  */
  58 function wp_remote_request($url, $args = array()) {
  59         $objFetchSite = _wp_http_get_object();
  60         return $objFetchSite->request($url, $args);
  61 }
  62
  63 /**
  64  * Retrieve the raw response from the HTTP request using the GET method.
  65  *
  66  * @see wp_remote_request() For more information on the response array format.
  67  *
  68  * @since 2.7.0
  69  *
  70  * @param string $url Site URL to retrieve.
  71  * @param array $args Optional. Override the defaults.
  72  * @return WP_Error|array The response or WP_Error on failure.
  73  */
  74 function wp_remote_get($url, $args = array()) {
  75         $objFetchSite = _wp_http_get_object();
  76         return $objFetchSite->get($url, $args);
  77 }
  78
  79 /**
  80  * Retrieve the raw response from the HTTP request using the POST method.
  81  *
  82  * @see wp_remote_request() For more information on the response array format.
  83  *
  84  * @since 2.7.0
  85  *
  86  * @param string $url Site URL to retrieve.
  87  * @param array $args Optional. Override the defaults.
  88  * @return WP_Error|array The response or WP_Error on failure.
  89  */
  90 function wp_remote_post($url, $args = array()) {
  91         $objFetchSite = _wp_http_get_object();
  92         return $objFetchSite->post($url, $args);
  93 }
  94
  95 /**
  96  * Retrieve the raw response from the HTTP request using the HEAD method.
  97  *
  98  * @see wp_remote_request() For more information on the response array format.
  99  *
 100  * @since 2.7.0
 101  *
 102  * @param string $url Site URL to retrieve.
 103  * @param array $args Optional. Override the defaults.
 104  * @return WP_Error|array The response or WP_Error on failure.
 105  */
 106 function wp_remote_head($url, $args = array()) {
 107         $objFetchSite = _wp_http_get_object();
 108         return $objFetchSite->head($url, $args);
 109 }
 110
 111 /**
 112  * Retrieve only the headers from the raw response.
 113  *
 114  * @since 2.7.0
 115  *
 116  * @param array $response HTTP response.
 117  * @return array The headers of the response. Empty array if incorrect parameter given.
 118  */
 119 function wp_remote_retrieve_headers(&$response) {
 120         if ( is_wp_error($response) || ! isset($response['headers']) || ! is_array($response['headers']))
 121                 return array();
 122
 123         return $response['headers'];
 124 }
 125
 126 /**
 127  * Retrieve a single header by name from the raw response.
 128  *
 129  * @since 2.7.0
 130  *
 131  * @param array $response
 132  * @param string $header Header name to retrieve value from.
 133  * @return string The header value. Empty string on if incorrect parameter given, or if the header doesnt exist.
 134  */
 135 function wp_remote_retrieve_header(&$response, $header) {
 136         if ( is_wp_error($response) || ! isset($response['headers']) || ! is_array($response['headers']))
 137                 return '';
 138
 139         if ( array_key_exists($header, $response['headers']) )
 140                 return $response['headers'][$header];
 141
 142         return '';
 143 }
 144
 145 /**
 146  * Retrieve only the response code from the raw response.
 147  *
 148  * Will return an empty array if incorrect parameter value is given.
 149  *
 150  * @since 2.7.0
 151  *
 152  * @param array $response HTTP response.
 153  * @return string the response code. Empty string on incorrect parameter given.
 154  */
 155 function wp_remote_retrieve_response_code(&$response) {
 156         if ( is_wp_error($response) || ! isset($response['response']) || ! is_array($response['response']))
 157                 return '';
 158
 159         return $response['response']['code'];
 160 }
 161
 162 /**
 163  * Retrieve only the response message from the raw response.
 164  *
 165  * Will return an empty array if incorrect parameter value is given.
 166  *
 167  * @since 2.7.0
 168  *
 169  * @param array $response HTTP response.
 170  * @return string The response message. Empty string on incorrect parameter given.
 171  */
 172 function wp_remote_retrieve_response_message(&$response) {
 173         if ( is_wp_error($response) || ! isset($response['response']) || ! is_array($response['response']))
 174                 return '';
 175
 176         return $response['response']['message'];
 177 }
 178
 179 /**
 180  * Retrieve only the body from the raw response.
 181  *
 182  * @since 2.7.0
 183  *
 184  * @param array $response HTTP response.
 185  * @return string The body of the response. Empty string if no body or incorrect parameter given.
 186  */
 187 function wp_remote_retrieve_body(&$response) {
 188         if ( is_wp_error($response) || ! isset($response['body']) )
 189                 return '';
 190
 191         return $response['body'];
 192 }
 193
 194 ?>