Add support for automatically retrying rate limited requests

Author: jwilsson

README.md

@@ -14,6 +14,7 @@ This is a PHP wrapper for [Spotify's Web API](https://developer.spotify.com/web-
     * User playback control.
 * Authorization flow helpers.
 * Automatic refreshing of access tokens.
+* Automatic retry of rate limited requests.
 * PSR-4 autoloading support.
 
 ## Requirements

docs/examples/handling-errors.md

@@ -15,6 +15,8 @@ try {
 When an authentication error occurs, a `SpotifyWebAPIAuthException` will be thrown. This will contain the same properties as above.
 
 ## Handling rate limit errors
+_As of version `2.12.0` it's possible to automatically retry rate limited requests by setting the `auto_retry` option to `true`._
+
 If your application should hit the Spotify API rate limit, you will get an error back and the number of seconds you need to wait before sending another request.
 
 Here's an example of how to handle this:
@@ -24,7 +26,7 @@ try {
     $track = $api->getTrack('7EjyzZcbLxW7PaaLua9Ksb');
 } catch (SpotifyWebAPIException $e) {
     if ($e->getCode() == 429) { // 429 is Too Many Requests
-        $lastResponse = $api->getRequest()->getLastResponse(); // Note "getRequest()" since $api->getLastResponse() won't be set
+        $lastResponse = $api->getRequest()->getLastResponse();
 
         $retryAfter = $lastResponse['headers']['Retry-After']; // Number of seconds to wait before sending another request
     } else {
@@ -33,4 +35,4 @@ try {
 }
 ```
 
-Read more about the exact mechanics of rate limiting in the [Spotify API docs](https://developer.spotify.com/web-api/user-guide/#rate-limiting).
+Read more about the exact mechanics of rate limiting in the [Spotify API docs](https://developer.spotify.com/documentation/web-api/#rate-limiting).

src/SpotifyWebAPI.php

@@ -10,6 +10,7 @@ class SpotifyWebAPI
     protected $lastResponse = [];
     protected $options = [
         'auto_refresh' => false,
+        'auto_retry' => false,
     ];
     protected $request = null;
     protected $session = null;
@@ -80,6 +81,13 @@ protected function sendRequest($method, $uri, $parameters = [], $headers = [])
 
                 $headers = $this->authHeaders($headers);
 
+                return $this->sendRequest($method, $uri, $parameters, $headers);
+            } elseif ($this->options['auto_retry'] && $e->isRateLimited()) {
+                $lastResponse = $this->request->getLastResponse();
+                $retryAfter = (int) $lastResponse['headers']['Retry-After'];
+
+                sleep($retryAfter);
+
                 return $this->sendRequest($method, $uri, $parameters, $headers);
             }
 

tests/SpotifyWebAPITest.php

@@ -6,7 +6,7 @@ class SpotifyWebAPITest extends PHPUnit\Framework\TestCase
     private function setupStub($expectedMethod, $expectedUri, $expectedParameters, $expectedHeaders, $expectedReturn)
     {
         $stub = $this->getMockBuilder('Request')
-                ->setMethods(['api'])
+                ->setMethods(['api', 'getLastResponse'])
                 ->getMock();
 
         $stub->expects($this->any())
@@ -72,6 +72,45 @@ public function testAutoRefreshOption()
         $this->assertObjectHasAttribute('id', $response);
     }
 
+    public function testAutoRetryOption()
+    {
+        $headers = [
+            'Authorization' => 'Bearer ' . $this->accessToken,
+        ];
+
+        $return = [
+            'body' => get_fixture('track'),
+            'headers' => [
+                'Retry-After' => 3,
+            ],
+            'status' => 429,
+        ];
+
+        $stub = $this->setupStub(
+            'GET',
+            '/v1/tracks/0eGsygTp906u18L0Oimnem',
+            [],
+            $headers,
+            $return
+        );
+
+        $stub->expects($this->at(0))
+            ->method('api')
+            ->willThrowException(
+                new SpotifyWebAPI\SpotifyWebAPIException('API rate limit exceeded', 429)
+            );
+
+        $api = new SpotifyWebAPI\SpotifyWebAPI($stub);
+        $api->setAccessToken($this->accessToken);
+        $api->setOptions([
+            'auto_retry' => true,
+        ]);
+
+        $response = $api->getTrack('0eGsygTp906u18L0Oimnem');
+
+        $this->assertObjectHasAttribute('id', $response);
+    }
+
     public function testAddMyAlbums()
     {
         $albums = [