[HttpClient] add section about interop + performance

Author: nicolas-grekas

components/http_client.rst

@@ -43,8 +43,18 @@ low-level HTTP client that makes requests, like the following ``GET`` request::
     $content = $response->toArray();
     // $content = ['id' => 521583, 'name' => 'symfony-docs', ...]
 
+Performance Optimization
+------------------------
+
+The component is built for maximum HTTP performance. By design, it is compatible
+with HTTP/2 and with doing concurrent asynchronous streamed and multiplexed
+requests/responses. Even when doing regular synchronous calls, this design
+allows keeping connections to remote hosts open between requests, improving
+performance by saving repetitive DNS resolution, SSL negociation, etc.
+To leverage all these design benefits, the cURL extension is needed.
+
 Enabling cURL Support
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 This component supports both the native PHP streams and cURL to make the HTTP
 requests. Although both are interchangeable and provide the same features,
@@ -68,7 +78,7 @@ not configurable and cURL will be used automatically if the cURL PHP extension
 is installed and enabled. Otherwise, the native PHP streams will be used.
 
 HTTP/2 Support
---------------
+~~~~~~~~~~~~~~
 
 When requesting an ``https`` URL, HTTP/2 is enabled by default if libcurl >= 7.36
 is used. To force HTTP/2 for ``http`` URLs, you need to enable it explicitly via
@@ -609,14 +619,55 @@ regular expression applied to relative URLs::
         'https://api\.github\.com/'
     );
 
-PSR-18 Compatibility
---------------------
+Interoperability
+----------------
+
+The component is interoperable with 2 different abstractions for HTTP clients:
+`Symfony Contracts`_ and `PSR-18`_. If your app uses
+libraries that need any of them, the component is compatible with them.
+They also benefit from autowiring aliases when the
+:ref:`framework bundle <framework-bundle-configuration>` is used.
+
+If you are writing or maintaining a library that makes HTTP requests, you can
+decouple it from any specific HTTP client implementations by coding against
+either Symfony Contracts (recommended) or PSR-18.
+
+Symfony Contracts
+~~~~~~~~~~~~~~~~~
+
+The interfaces found in the ``symfony/http-client-contracts`` package define
+the primary abstractions implemented by the component. Its entry point is the
+:class:`Symfony\\Contracts\\HttpClient\\HttpClientInterface`. That's the
+interface you need to code against when a client is needed::
+
+    use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+    class MyApiLayer
+    {
+        private $client;
+
+        public function __construct(HttpClientInterface $client)
+        {
+            $this->client = $client
+        }
+
+        // [...]
+    }
+
+All request options mentionned above (e.g. timeout management) are also defined
+in the wordings of the interface, so that any compliant implementations (like this
+component) is guaranteed to provide them. That's a major difference with the
+PSR-18 abstraction, which provides none related to the transport itself.
+
+Another major feature covered by the Symfony Contracts is async/multiplexing,
+as described in the previous sections.
+
+PSR-18
+~~~~~~
 
-This component uses and implements abstractions defined by the
-``symfony/http-client-contracts``. It also implements the `PSR-18`_ (HTTP Client)
-specifications via the :class:`Symfony\\Component\\HttpClient\\Psr18Client`
-class, which is an adapter to turn a Symfony ``HttpClientInterface`` into a
-PSR-18 ``ClientInterface``.
+This component implements the `PSR-18`_ (HTTP Client) specifications via the
+:class:`Symfony\\Component\\HttpClient\\Psr18Client` class, which is an adapter
+to turn a Symfony ``HttpClientInterface`` into a PSR-18 ``ClientInterface``.
 
 To use it, you need the ``psr/http-client`` package and a `PSR-17`_ implementation:
 
@@ -765,3 +816,4 @@ However, using ``MockResponse`` allows simulating chunked responses and timeouts
 .. _`cURL PHP extension`: https://php.net/curl
 .. _`PSR-17`: https://www.php-fig.org/psr/psr-17/
 .. _`PSR-18`: https://www.php-fig.org/psr/psr-18/
+.. _`Symfony Contracts`: https://github.com/symfony/contracts