Add doc for multiple base_uri as array

Author: Tiriel

http_client.rst

@@ -731,6 +731,61 @@ The ``RetryableHttpClient`` uses a
 decide if the request should be retried, and to define the waiting time between
 each retry.
 
+Retry over different uris
+.........................
+
+When using a ``RetryableHttpClient``, the ``base_uri`` can be set as an array of
+uris. The array will be used in the given order, meaning that the first request 
+will be made with the first uri in the array. Should it fail, the next one will 
+be used for the first retry. If the number of configured retries is greater than
+the number of given uris, the last uri will be used for every exceding retry.
+
+You can pass the array of base uris directly to the ``request`` method or when
+creating a HttpClient with the ``withOptions`` method::
+
+    use Symfony\Component\HttpClient\RetryableHttpClient;
+    
+    $client = new RetryableHttpClient(HttpClient::create());
+
+    $response = $client->request('GET', 'some-path', [
+        'base_uri' => [
+            // first request will use this base uri
+            'http://example.com/a/',
+            // if first request fails, the second base uri will be used
+            'http://example.com/b/',
+        ],
+    ]);
+
+    // You can also use the withOptions method to pass an array of base_uri
+    $client = $client->withOptions(['base_uri' => [
+        'http://example.com/a/',
+        'http://example.com/b/',
+    ]]);
+
+    $response = $client->request('GET', 'some-path');
+
+If you wish some or all of the base uris to be shuffled, you can pass a nested 
+array inside the ``base_uri`` array. Every uri inside the nested array will be 
+randomized, and the order of the base uris outside this nested array will be 
+preserved::
+
+    use Symfony\Component\HttpClient\RetryableHttpClient;
+    
+    $client = new RetryableHttpClient(HttpClient::create());
+
+    $response = $client->request('GET', 'some-path', [
+        'base_uri' => [
+            'http://example.com/a/',
+            [
+                // base uri passed inside a nested array will be shuffled
+                'http://example.com/b/',
+                'http://example.com/c/',
+            ]
+            // the order of the non-nested base uris is preserved
+            'http://example.com/d/',
+        ],
+    ]);
+
 HTTP Proxies
 ~~~~~~~~~~~~