includes/Requests/Requests/Session.php

   1 <?php
   2 /**
   3  * Session handler for persistent requests and default parameters
   4  *
   5  * @package Requests
   6  * @subpackage Session Handler
   7  */
   8
   9 /**
  10  * Session handler for persistent requests and default parameters
  11  *
  12  * Allows various options to be set as default values, and merges both the
  13  * options and URL properties together. A base URL can be set for all requests,
  14  * with all subrequests resolved from this. Base options can be set (including
  15  * a shared cookie jar), then overridden for individual requests.
  16  *
  17  * @package Requests
  18  * @subpackage Session Handler
  19  */
  20 class Requests_Session {
  21         /**
  22          * Base URL for requests
  23          *
  24          * URLs will be made absolute using this as the base
  25          * @var string|null
  26          */
  27         public $url = null;
  28
  29         /**
  30          * Base headers for requests
  31          * @var array
  32          */
  33         public $headers = array();
  34
  35         /**
  36          * Base data for requests
  37          *
  38          * If both the base data and the per-request data are arrays, the data will
  39          * be merged before sending the request.
  40          *
  41          * @var array
  42          */
  43         public $data = array();
  44
  45         /**
  46          * Base options for requests
  47          *
  48          * The base options are merged with the per-request data for each request.
  49          * The only default option is a shared cookie jar between requests.
  50          *
  51          * Values here can also be set directly via properties on the Session
  52          * object, e.g. `$session->useragent = 'X';`
  53          *
  54          * @var array
  55          */
  56         public $options = array();
  57
  58         /**
  59          * Create a new session
  60          *
  61          * @param string|null $url Base URL for requests
  62          * @param array $headers Default headers for requests
  63          * @param array $data Default data for requests
  64          * @param array $options Default options for requests
  65          */
  66         public function __construct($url = null, $headers = array(), $data = array(), $options = array()) {
  67                 $this->url = $url;
  68                 $this->headers = $headers;
  69                 $this->data = $data;
  70                 $this->options = $options;
  71
  72                 if (empty($this->options['cookies'])) {
  73                         $this->options['cookies'] = new Requests_Cookie_Jar();
  74                 }
  75         }
  76
  77         /**
  78          * Get a property's value
  79          *
  80          * @param string $key Property key
  81          * @return mixed|null Property value, null if none found
  82          */
  83         public function __get($key) {
  84                 if (isset($this->options[$key]))
  85                         return $this->options[$key];
  86
  87                 return null;
  88         }
  89
  90         /**
  91          * Set a property's value
  92          *
  93          * @param string $key Property key
  94          * @param mixed $value Property value
  95          */
  96         public function __set($key, $value) {
  97                 $this->options[$key] = $value;
  98         }
  99
 100         /**
 101          * Remove a property's value
 102          *
 103          * @param string $key Property key
 104          */
 105         public function __isset($key) {
 106                 return isset($this->options[$key]);
 107         }
 108
 109         /**
 110          * Remove a property's value
 111          *
 112          * @param string $key Property key
 113          */
 114         public function __unset($key) {
 115                 $this->options[$key] = null;
 116         }
 117
 118         /**#@+
 119          * @see request()
 120          * @param string $url
 121          * @param array $headers
 122          * @param array $options
 123          * @return Requests_Response
 124          */
 125         /**
 126          * Send a GET request
 127          */
 128         public function get($url, $headers = array(), $options = array()) {
 129                 return $this->request($url, $headers, null, Requests::GET, $options);
 130         }
 131
 132         /**
 133          * Send a HEAD request
 134          */
 135         public function head($url, $headers = array(), $options = array()) {
 136                 return $this->request($url, $headers, null, Requests::HEAD, $options);
 137         }
 138
 139         /**
 140          * Send a DELETE request
 141          */
 142         public function delete($url, $headers = array(), $options = array()) {
 143                 return $this->request($url, $headers, null, Requests::DELETE, $options);
 144         }
 145         /**#@-*/
 146
 147         /**#@+
 148          * @see request()
 149          * @param string $url
 150          * @param array $headers
 151          * @param array $data
 152          * @param array $options
 153          * @return Requests_Response
 154          */
 155         /**
 156          * Send a POST request
 157          */
 158         public function post($url, $headers = array(), $data = array(), $options = array()) {
 159                 return $this->request($url, $headers, $data, Requests::POST, $options);
 160         }
 161
 162         /**
 163          * Send a PUT request
 164          */
 165         public function put($url, $headers = array(), $data = array(), $options = array()) {
 166                 return $this->request($url, $headers, $data, Requests::PUT, $options);
 167         }
 168
 169         /**
 170          * Send a PATCH request
 171          *
 172          * Note: Unlike {@see post} and {@see put}, `$headers` is required, as the
 173          * specification recommends that should send an ETag
 174          *
 175          * @link http://tools.ietf.org/html/rfc5789
 176          */
 177         public function patch($url, $headers, $data = array(), $options = array()) {
 178                 return $this->request($url, $headers, $data, Requests::PATCH, $options);
 179         }
 180         /**#@-*/
 181
 182         /**
 183          * Main interface for HTTP requests
 184          *
 185          * This method initiates a request and sends it via a transport before
 186          * parsing.
 187          *
 188          * @see Requests::request()
 189          *
 190          * @throws Requests_Exception On invalid URLs (`nonhttp`)
 191          *
 192          * @param string $url URL to request
 193          * @param array $headers Extra headers to send with the request
 194          * @param array $data Data to send either as a query string for GET/HEAD requests, or in the body for POST requests
 195          * @param string $type HTTP request type (use Requests constants)
 196          * @param array $options Options for the request (see {@see Requests::request})
 197          * @return Requests_Response
 198          */
 199         public function request($url, $headers = array(), $data = array(), $type = Requests::GET, $options = array()) {
 200                 $request = $this->merge_request(compact('url', 'headers', 'data', 'options'));
 201
 202                 return Requests::request($request['url'], $request['headers'], $request['data'], $type, $request['options']);
 203         }
 204
 205         /**
 206          * Send multiple HTTP requests simultaneously
 207          *
 208          * @see Requests::request_multiple()
 209          *
 210          * @param array $requests Requests data (see {@see Requests::request_multiple})
 211          * @param array $options Global and default options (see {@see Requests::request})
 212          * @return array Responses (either Requests_Response or a Requests_Exception object)
 213          */
 214         public function request_multiple($requests, $options = array()) {
 215                 foreach ($requests as $key => $request) {
 216                         $requests[$key] = $this->merge_request($request, false);
 217                 }
 218
 219                 $options = array_merge($this->options, $options);
 220
 221                 // Disallow forcing the type, as that's a per request setting
 222                 unset($options['type']);
 223
 224                 return Requests::request_multiple($requests, $options);
 225         }
 226
 227         /**
 228          * Merge a request's data with the default data
 229          *
 230          * @param array $request Request data (same form as {@see request_multiple})
 231          * @param boolean $merge_options Should we merge options as well?
 232          * @return array Request data
 233          */
 234         protected function merge_request($request, $merge_options = true) {
 235                 if ($this->url !== null) {
 236                         $request['url'] = Requests_IRI::absolutize($this->url, $request['url']);
 237                         $request['url'] = $request['url']->uri;
 238                 }
 239                 $request['headers'] = array_merge($this->headers, $request['headers']);
 240
 241                 if (is_array($request['data']) && is_array($this->data)) {
 242                         $request['data'] = array_merge($this->data, $request['data']);
 243                 }
 244
 245                 if ($merge_options !== false) {
 246                         $request['options'] = array_merge($this->options, $request['options']);
 247
 248                         // Disallow forcing the type, as that's a per request setting
 249                         unset($request['options']['type']);
 250                 }
 251                 return $request;
 252         }
 253 }