[FrameworkBundle][HttpClient] Adding an explanation of ThrottlingHttpClient integration with the Framework

Author: maxhelias

http_client.rst

@@ -1488,30 +1488,108 @@ Limit the Number of Requests
 ----------------------------
 
 This component provides a :class:`Symfony\\Component\\HttpClient\\ThrottlingHttpClient`
-decorator that allows to limit the number of requests within a certain period.
+decorator that allows to limit the number of requests within a certain period, potentially delaying calls based on the rate limiting policy.
 
 The implementation leverages the
 :class:`Symfony\\Component\\RateLimiter\\LimiterInterface` class under the hood
 so the :doc:`Rate Limiter component </rate_limiter>` needs to be
 installed in your application::
 
-    use Symfony\Component\HttpClient\HttpClient;
-    use Symfony\Component\HttpClient\ThrottlingHttpClient;
-    use Symfony\Component\RateLimiter\LimiterInterface;
+.. configuration-block::
 
-    $rateLimiter = ...; // $rateLimiter is an instance of Symfony\Component\RateLimiter\LimiterInterface
-    $client = HttpClient::create();
-    $client = new ThrottlingHttpClient($client, $rateLimiter);
+    .. code-block:: yaml
 
-    $requests = [];
-    for ($i = 0; $i < 100; $i++) {
-        $requests[] = $client->request('GET', 'https://example.com');
-    }
+        # config/packages/framework.yaml
+        framework:
+            http_client:
+                scoped_clients:
+                    symfony.client:
+                        base_uri: 'https://symfony.com'
+                        rate_limiter: 'http_symfony_termsofuse'
 
-    foreach ($requests as $request) {
-        // Depending on rate limiting policy, calls will be delayed
-        $output->writeln($request->getContent());
-    }
+            rate_limiter:
+                # Don't send more than 10 requests in 5 seconds
+                http_symfony_termsofuse:
+                    policy: 'token_bucket'
+                    limit: 10
+                    rate: { interval: '5 seconds', amount: 10 }
+
+    .. code-block:: xml
+
+        <!-- config/packages/framework.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:http-client>
+                    <framework:scoped-client name="symfony.client"
+                        base-uri="https://symfony.com"
+                        rate-limiter="http_symfony_termsofuse"
+                    />
+                </framework:http-client>
+
+                <framework:rate-limiter>
+                    <!-- Don't send more than 10 requests in 5 seconds -->
+                    <framework:limiter name="http_symfony_termsofuse"
+                        policy="token_bucket"
+                        limit="10"
+                    >
+                        <framework:rate interval="5 seconds" amout="10"/>
+                    </framework:limiter>
+                </framework:rate-limiter>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/framework.php
+        use Symfony\Config\FrameworkConfig;
+
+        return static function (FrameworkConfig $framework): void {
+            $framework->httpClient()->scopedClient('symfony.client')
+                ->baseUri('https://symfony.com')
+                ->rateLimiter('http_symfony_termsofuse');
+                // ...
+            ;
+
+            $framework->rateLimiter()
+                // Don't send more than 10 requests in 5 seconds
+                ->limiter('http_symfony_termsofuse')
+                    ->policy('token_bucket')
+                    ->limit(10)
+                    ->rate()
+                        ->interval('5 seconds')
+                        ->amount(10)
+                ;
+        };
+
+    .. code-block:: php-standalone
+
+        use Symfony\Component\HttpClient\HttpClient;
+        use Symfony\Component\HttpClient\ThrottlingHttpClient;
+        use Symfony\Component\RateLimiter\LimiterInterface;
+
+        $rateLimiter = ...; // $rateLimiter is an instance of Symfony\Component\RateLimiter\LimiterInterface
+        $client = HttpClient::create();
+        $client = new ScopingHttpClient($client, [
+            'base_uri' => 'https://symfony.com',
+        ]);
+        $client = new ThrottlingHttpClient($client, $rateLimiter);
+
+        $requests = [];
+        for ($i = 0; $i < 100; $i++) {
+            $requests[] = $client->request('GET', 'https://symfony.com');
+        }
+
+        foreach ($requests as $request) {
+            // Depending on rate limiting policy, calls will be delayed
+            $output->writeln($request->getContent());
+        }
 
 .. versionadded:: 7.1