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 doesn't 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 /**
 195  * Determines if there is an HTTP Transport that can process this request.
 196  *
 197  * @since 3.2.0
 198  *
 199  * @param array  $capabilities Array of capabilities to test or a wp_remote_request() $args array.
 200  * @param string $url Optional. If given, will check if the URL requires SSL and adds that requirement to the capabilities array.
 201  *
 202  * @return bool
 203  */
 204 function wp_http_supports( $capabilities = array(), $url = null ) {
 205         $objFetchSite = _wp_http_get_object();
 206
 207         $capabilities = wp_parse_args( $capabilities );
 208
 209         $count = count( $capabilities );
 210
 211         // If we have a numeric $capabilities array, spoof a wp_remote_request() associative $args array
 212         if ( $count && count( array_filter( array_keys( $capabilities ), 'is_numeric' ) ) == $count ) {
 213                 $capabilities = array_combine( array_values( $capabilities ), array_fill( 0, $count, true ) );
 214         }
 215
 216         if ( $url && !isset( $capabilities['ssl'] ) ) {
 217                 $scheme = parse_url( $url, PHP_URL_SCHEME );
 218                 if ( 'https' == $scheme || 'ssl' == $scheme ) {
 219                         $capabilities['ssl'] = true;
 220                 }
 221         }
 222
 223         return (bool) $objFetchSite->_get_first_available_transport( $capabilities );
 224 }
 225
 226 /**
 227  * Get the HTTP Origin of the current request.
 228  *
 229  * @since 3.4.0
 230  *
 231  * @return string URL of the origin. Empty string if no origin.
 232  */
 233 function get_http_origin() {
 234         $origin = '';
 235         if ( ! empty ( $_SERVER[ 'HTTP_ORIGIN' ] ) )
 236                 $origin = $_SERVER[ 'HTTP_ORIGIN' ];
 237
 238         return apply_filters( 'http_origin', $origin );
 239 }
 240
 241 /**
 242  * Retrieve list of allowed http origins.
 243  *
 244  * @since 3.4.0
 245  *
 246  * @return array Array of origin URLs.
 247  */
 248 function get_allowed_http_origins() {
 249         $admin_origin = parse_url( admin_url() );
 250         $home_origin = parse_url( home_url() );
 251
 252         // @todo preserve port?
 253         $allowed_origins = array_unique( array(
 254                 'http://' . $admin_origin[ 'host' ],
 255                 'https://' . $admin_origin[ 'host' ],
 256                 'http://' . $home_origin[ 'host' ],
 257                 'https://' . $home_origin[ 'host' ],
 258         ) );
 259
 260         return apply_filters( 'allowed_http_origins' , $allowed_origins );
 261 }
 262
 263 /**
 264  * Determines if the http origin is an authorized one.
 265  *
 266  * @since 3.4.0
 267  *
 268  * @param string Origin URL. If not provided, the value of get_http_origin() is used.
 269  * @return bool True if the origin is allowed. False otherwise.
 270  */
 271 function is_allowed_http_origin( $origin = null ) {
 272         $origin_arg = $origin;
 273
 274         if ( null === $origin )
 275                 $origin = get_http_origin();
 276
 277         if ( $origin && ! in_array( $origin, get_allowed_http_origins() ) )
 278                 $origin = '';
 279
 280         return apply_filters( 'allowed_http_origin', $origin, $origin_arg );
 281 }
 282
 283 /**
 284  * Send Access-Control-Allow-Origin and related headers if the current request
 285  * is from an allowed origin.
 286  *
 287  * @since 3.4.0
 288  *
 289  * @return bool|string Returns the origin URL if headers are sent. Returns false
 290  * if headers are not sent.
 291  */
 292 function send_origin_headers() {
 293         $origin = get_http_origin();
 294         if ( ! is_allowed_http_origin( $origin ) )
 295                 return false;
 296
 297         @header( 'Access-Control-Allow-Origin: ' .  $origin );
 298         @header( 'Access-Control-Allow-Credentials: true' );
 299
 300         return $origin;
 301 }