[Summary view] [Print] [Text view]

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