adding support for sandbox PUT methods and added documentation for confirmation flow

stevenmaguire · stevenmaguire · commit 59b5d8af4f1e · 2015-05-28T11:01:33.000-05:00
diff --git a/README.md b/README.md
@@ -127,10 +127,30 @@ $request = $client->requestRide(array(
     'start_latitude' => '41.85582993',
     'start_longitude' => '-87.62730337',
     'end_latitude' => '41.87499492',
-    'end_longitude' => '-87.67126465'
+    'end_longitude' => '-87.67126465',
+    'surge_confirmation_id' => 'e100a670' // Optional
 ));
 ```
 
+#### Surge Confirmation Flow
+
+If the ride request is using a product that has a surge multiplier, the API wrapper will throw an Exception and provide a response body that includes a surge confirmation ID.
+
+```php
+try {
+    $request = $client->requestRide(array(
+        'product_id' => '4bfc6c57-98c0-424f-a72e-c1e2a1d49939',
+        'start_latitude' => '41.85582993',
+        'start_longitude' => '-87.62730337',
+        'end_latitude' => '41.87499492',
+        'end_longitude' => '-87.67126465'
+    ));
+} catch (Stevenmaguire\Uber\Exception $e) {
+    $body = $e->getBody();
+    $surgeConfirmationId = $body['meta']['surge_confirmation']['surge_confirmation_id'];
+}
+```
+
 [https://developer.uber.com/v1/endpoints/#request](https://developer.uber.com/v1/endpoints/#request)
 
 ### Get Ride Details
@@ -176,6 +196,33 @@ These values will update after each request. `getRateLimit` will return null aft
 
 [https://developer.uber.com/v1/api-reference/#rate-limiting](https://developer.uber.com/v1/api-reference/#rate-limiting)
 
+### Using the Sandbox
+
+Modify the status of an ongoing sandbox Request.
+
+```php
+$request = $client->requestRide(array(
+    'product_id' => '4bfc6c57-98c0-424f-a72e-c1e2a1d49939',
+    'start_latitude' => '41.85582993',
+    'start_longitude' => '-87.62730337',
+    'end_latitude' => '41.87499492',
+    'end_longitude' => '-87.67126465'
+));
+
+$updateRequest = $client->setRequest($request->request_id, ['status' => 'accepted']);
+```
+[https://developer.uber.com/v1/sandbox/#request](https://developer.uber.com/v1/sandbox/#request)
+
+Simulate the possible responses the Request endpoint will return when requesting a particular product, such as surge pricing, against the Sandbox.
+
+```php
+$product = $client->getProduct($product_id);
+
+$updateProduct = $client->setProduct($product_id, ['surge_multiplier' => 2.2, 'drivers_available' => false]);
+```
+
+[https://developer.uber.com/v1/sandbox/#product-types](https://developer.uber.com/v1/sandbox/#product-types)
+
 ## Testing
 
 ``` bash
diff --git a/src/Client.php b/src/Client.php
@@ -69,6 +69,20 @@ public function __construct($configuration = [])
         $this->http_client = new HttpClient;
     }
 
+    /**
+     * Apply configuration
+     *
+     * @param  array $configuration
+     *
+     * @return void
+     */
+    private function applyConfiguration($configuration = [])
+    {
+        array_walk($configuration, function ($value, $key) {
+            $this->updateAttribute($key, $value);
+        });
+    }
+
     /**
      * Cancel a single request
      *
@@ -81,6 +95,58 @@ public function cancelRequest($request_id)
         return $this->request('delete', 'requests/'.$request_id);
     }
 
+    /**
+     * Get authorization header value
+     *
+     * @return string
+     */
+    private function getAuthorizationHeader()
+    {
+        if ($this->access_token) {
+            return 'Bearer '.$this->access_token;
+        }
+
+        return 'Token '.$this->server_token;
+    }
+
+    /**
+     * Get HttpClient config for verb and parameters
+     *
+     * @param  string $verb
+     * @param  array  $parameters
+     *
+     * @return array
+     */
+    private function getConfigForVerbAndParameters($verb, $parameters = [])
+    {
+        $config = [
+            'headers' => $this->getHeaders()
+        ];
+
+        if (!empty($parameters)) {
+            if (strtolower($verb) == 'get') {
+                $config['query'] = $parameters;
+            } else {
+                $config['json'] = $parameters;
+            }
+        }
+
+        return $config;
+    }
+
+    /**
+     * Get headers for request
+     *
+     * @return array
+     */
+    public function getHeaders()
+    {
+        return [
+            'Authorization' => trim($this->getAuthorizationHeader()),
+            'Accept-Language' => trim($this->locale),
+        ];
+    }
+
     /**
      * The User Activity endpoint returns a limited amount of data about a
      * user's lifetime activity with Uber. The response will include pickup and
@@ -209,32 +275,6 @@ public function getTimeEstimates($attributes = [])
         return $this->request('get', 'estimates/time', $attributes);
     }
 
-    /**
-     * The Request endpoint allows a ride to be requested on behalf of an Uber
-     * user given their desired product, start, and end locations.
-     *
-     * @param    array    $attributes   Query attributes
-     *
-     * @return   stdClass               The JSON response from the request
-     */
-    public function requestRide($attributes = [])
-    {
-        return $this->request('post', 'requests', $attributes);
-    }
-
-    /**
-     * Get headers for request
-     *
-     * @return array
-     */
-    public function getHeaders()
-    {
-        return [
-            'Authorization' => trim($this->getAuthorizationHeader()),
-            'Accept-Language' => trim($this->locale),
-        ];
-    }
-
     /**
      * Build url
      *
@@ -252,90 +292,59 @@ public function getUrlFromPath($path)
     }
 
     /**
-     * Set Http Client
-     *
-     * @param HttpClient  $client
-     *
-     * @return Client
-     */
-    public function setHttpClient(HttpClient $client)
-    {
-        $this->http_client = $client;
-        return $this;
-    }
-
-    /**
-     * Apply configuration
+     * Handle http client exceptions
      *
-     * @param  array $configuration
+     * @param  HttpClientException $e
      *
      * @return void
+     * @throws Exception
      */
-    private function applyConfiguration($configuration = [])
+    private function handleRequestException(HttpClientException $e)
     {
-        array_walk($configuration, function ($value, $key) {
-            $this->updateAttribute($key, $value);
-        });
-    }
+        if ($response = $e->getResponse()) {
+            $exception = new Exception($response->getReasonPhrase(), $response->getStatusCode(), $e);
+            $exception->setBody($response->json());
 
-    /**
-     * Get authorization header value
-     *
-     * @return string
-     */
-    private function getAuthorizationHeader()
-    {
-        if ($this->access_token) {
-            return 'Bearer '.$this->access_token;
+            throw $exception;
         }
 
-        return 'Token '.$this->server_token;
+        throw new Exception($e->getMessage(), 500, $e);
     }
 
     /**
-     * Get HttpClient config for verb and parameters
+     * Parse configuration using defaults
      *
-     * @param  string $verb
-     * @param  array  $parameters
+     * @param  array $configuration
      *
-     * @return array
+     * @return array $configuration
      */
-    private function getConfigForVerbAndParameters($verb, $parameters = [])
+    private function parseConfiguration($configuration = [])
     {
-        $config = [
-            'headers' => $this->getHeaders()
-        ];
-
-        if (!empty($parameters)) {
-            if (strtolower($verb) == 'get') {
-                $config['query'] = $parameters;
-            } else {
-                $config['json'] = $parameters;
-            }
-        }
+        $defaults = array(
+            'access_token'  =>  null,
+            'server_token'  =>  null,
+            'use_sandbox'   =>  false,
+            'version'   =>  'v1',
+            'locale'    => 'en_US',
+        );
 
-        return $config;
+        return array_merge($defaults, $configuration);
     }
 
-
     /**
-     * Handle http client exceptions
+     * Attempt to pull rate limit headers from response and add to client
      *
-     * @param  HttpClientException $e
+     * @param  Response  $response
      *
      * @return void
-     * @throws Exception
      */
-    private function handleRequestException(HttpClientException $e)
+    private function parseRateLimitFromResponse(Response $response)
     {
-        if ($response = $e->getResponse()) {
-            $exception = new Exception($response->getReasonPhrase(), $response->getStatusCode(), $e);
-            $exception->setBody($response->json());
-
-            throw $exception;
-        }
-
-        throw new Exception($e->getMessage(), 500, $e);
+        $this->rate_limit = new RateLimit(
+            $response->getHeader('X-Rate-Limit-Limit'),
+            $response->getHeader('X-Rate-Limit-Remaining'),
+            $response->getHeader('X-Rate-Limit-Reset')
+        );
     }
 
     /**
@@ -367,38 +376,54 @@ private function request($verb, $path, $parameters = [])
     }
 
     /**
-     * Parse configuration using defaults
+     * The Request endpoint allows a ride to be requested on behalf of an Uber
+     * user given their desired product, start, and end locations.
      *
-     * @param  array $configuration
+     * @param    array    $attributes   Query attributes
      *
-     * @return array $configuration
+     * @return   stdClass               The JSON response from the request
      */
-    private function parseConfiguration($configuration = [])
+    public function requestRide($attributes = [])
     {
-        $defaults = array(
-            'access_token'  =>  null,
-            'server_token'  =>  null,
-            'use_sandbox'   =>  false,
-            'version'   =>  'v1',
-            'locale'    => 'en_US',
-        );
+        return $this->request('post', 'requests', $attributes);
+    }
 
-        return array_merge($defaults, $configuration);
+    /**
+     * Set Http Client
+     *
+     * @param HttpClient  $client
+     *
+     * @return Client
+     */
+    public function setHttpClient(HttpClient $client)
+    {
+        $this->http_client = $client;
+        return $this;
     }
 
     /**
-     * Attempt to pull rate limit headers from response and add to client
+     * Set product properties for sandbox responses
      *
-     * @param  Response  $response
+     * @param string $product_id
+     * @param array $attributes
      *
-     * @return void
+     * @return  stdClass
      */
-    private function parseRateLimitFromResponse(Response $response)
+    public function setProduct($product_id, $attributes = [])
     {
-        $this->rate_limit = new RateLimit(
-            $response->getHeader('X-Rate-Limit-Limit'),
-            $response->getHeader('X-Rate-Limit-Remaining'),
-            $response->getHeader('X-Rate-Limit-Reset')
-        );
+        return $this->request('put', 'sandbox/products/'.$product_id, $attributes);
+    }
+
+    /**
+     * Set request properties for sandbox responses
+     *
+     * @param string $request_id
+     * @param array $attributes
+     *
+     * @return  stdClass
+     */
+    public function setRequest($request_id, $attributes = [])
+    {
+        return $this->request('put', 'sandbox/requests/'.$request_id, $attributes);
     }
 }
diff --git a/tests/src/UberTest.php b/tests/src/UberTest.php
