[HttpClient] make HttpClient::create() return an AmpHttpClient when amphp/http-client is found but curl is not or too old

Author: alexandre-daubois

http_client.rst

@@ -854,15 +854,28 @@ 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,
-including concurrent requests, HTTP/2 is only supported when using cURL.
+This component supports the native PHP streams, ``amphp/http-client`` and cURL to
+make the HTTP requests. Although they are interchangeable and provide the
+same features, including concurrent requests, HTTP/2 is only supported when
+using cURL or ``amphp/http-client``.
+
+.. note::
+
+    To use the :class:`Symfony\\Component\\HttpClient\\AmpHttpClient`, the
+    `amphp/http-client`_ package must be installed.
+
+.. versionadded:: 5.1
+
+    Integration with ``amphp/http-client`` was introduced in Symfony 5.1.
 
 The :method:`Symfony\\Component\\HttpClient\\HttpClient::create` method
-selects the cURL transport if the `cURL PHP extension`_ is enabled and falls
-back to PHP streams otherwise. If you prefer to select the transport
-explicitly, use the following classes to create the client::
+selects the cURL transport if the `cURL PHP extension`_ is enabled. It falls
+back to ``AmpHttpClient`` if cURL couldn't be found or is too old. Finally, if
+``AmpHttpClient`` is not available, it falls back to PHP streams.
+If you prefer to select the transport explicitly, use the following classes
+to create the client::
 
+    use Symfony\Component\HttpClient\AmpHttpClient;
     use Symfony\Component\HttpClient\CurlHttpClient;
     use Symfony\Component\HttpClient\NativeHttpClient;
 
@@ -872,9 +885,12 @@ explicitly, use the following classes to create the client::
     // uses the cURL PHP extension
     $client = new CurlHttpClient();
 
+    // uses the client from the `amphp/http-client` package
+    $client = new AmpHttpClient();
+
 When using this component in a full-stack Symfony application, this behavior is
 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.
+is installed and enabled, and will fall back as explained above.
 
 Configuring CurlHttpClient Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -984,9 +1000,10 @@ To force HTTP/2 for ``http`` URLs, you need to enable it explicitly via the
 
         $client = HttpClient::create(['http_version' => '2.0']);
 
-Support for HTTP/2 PUSH works out of the box when libcurl >= 7.61 is used with
-PHP >= 7.2.17 / 7.3.4: pushed responses are put into a temporary cache and are
-used when a subsequent request is triggered for the corresponding URLs.
+Support for HTTP/2 PUSH works out of the box when using ``amphp/http-client``
+or when libcurl >= 7.61 is used with PHP >= 7.2.17 / 7.3.4: pushed responses
+are put into a temporary cache and are used when a subsequent request is
+triggered for the corresponding URLs.
 
 Processing Responses
 --------------------
@@ -2055,3 +2072,4 @@ test it in a real application::
 .. _`EventSource`: https://www.w3.org/TR/eventsource/#eventsource
 .. _`idempotent method`: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods
 .. _`SSRF`: https://portswigger.net/web-security/ssrf
+.. _`AmpHttpClient`: https://github.com/amphp/http-client