Improve doc for HttpClient

Author: nicolas-grekas

components/http_client.rst

@@ -6,12 +6,18 @@ The HttpClient Component
 ========================
 
     The HttpClient component is a low-level HTTP client with support for both
-    PHP stream wrappers and cURL. It also provides utilities to consume APIs.
+    PHP stream wrappers and cURL. It provides utilities to consume APIs and
+    supports synchronous and asynchronous operations.
 
 .. versionadded:: 4.3
 
     The HttpClient component was introduced in Symfony 4.3.
 
+.. TODO
+.. tell about implementation vs abstraction
+.. tell there are more options
+.. tell chunked + compression are supported out of the box
+
 Installation
 ------------
 
@@ -69,14 +75,15 @@ Enabling HTTP/2 Support
 -----------------------
 
 HTTP/2 is only supported when using the cURL-based transport and the libcurl
-version is >= 7.36.0. If you meet these requirements, you can enable HTTP/2
-explicitly via the ``http_version`` option::
+version is >= 7.36.0. If you meet these requirements, HTTP/2 will be used by
+default when the request protocol is ``https``. If you need it for ``http``,
+you must enable it explicitly via the ``http_version`` option::
 
     $httpClient = HttpClient::create(['http_version' => '2.0']);
 
-If you don't set the HTTP version explicitly, Symfony will use ``'2.0'`` only
-when the request protocol is ``https://`` (and the cURL requirements mentioned
-earlier are met).
+Support for HTTP/2 PUSH works out of the box when libcurl >= 7.61.0 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.
 
 Making Requests
 ---------------
@@ -89,14 +96,13 @@ method to perform all kinds of HTTP requests::
     $response = $httpClient->request('PUT', 'https://...');
     // ...
 
-Responses are always asynchronous, so they are ready as soon as the response
-HTTP headers are received, instead of waiting to receive the entire response
-contents::
+Responses are always asynchronous, so that the call to the method returns
+immediately instead of waiting to receive the response::
 
+    // code execution continues immediately; it doesn't wait to receive the response
     $response = $httpClient->request('GET', 'http://releases.ubuntu.com/18.04.2/ubuntu-18.04.2-desktop-amd64.iso');
 
-    // code execution continues immediately; it doesn't wait to receive the response
-    // you can get the value of any HTTP response header
+    // getting the response headers waits until they arrive
     $contentType = $response->getHeaders()['content-type'][0];
 
     // trying to get the response contents will block the execution until
@@ -135,8 +141,8 @@ each request (which overrides any global authentication)::
 Query String Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-You can either append them manually to the requested URL, or better, add them
-as an associative array to the ``query`` option::
+You can either append them manually to the requested URL, or add them as an
+associative array to the ``query`` option that will be merged with the URL::
 
     // it makes an HTTP GET request to https://httpbin.org/get?token=...&name=...
     $response = $httpClient->request('GET', 'https://httpbin.org/get', [
@@ -155,7 +161,7 @@ requests and the specific headers for each request::
 
     // this header is added to all requests made by this client
     $httpClient = HttpClient::create(['headers' => [
-        'Accept-Encoding' => 'gzip',
+        'User-Agent' => 'My Fancy App',
     ]]);
 
     // this header is only included in this request and overrides the value
@@ -170,7 +176,7 @@ Uploading Data
 ~~~~~~~~~~~~~~
 
 This component provides several methods for uploading data using the ``body``
-option. You can use regular strings, closures and resources and they'll be
+option. You can use regular strings, closures, iterables and resources and they'll be
 processed automatically when making the requests::
 
     $response = $httpClient->request('POST', 'https://...', [
@@ -264,7 +270,7 @@ following methods::
 Streaming Responses
 ~~~~~~~~~~~~~~~~~~~
 
-Call to the ``stream()`` method of the HTTP client to get *chunks* of the
+Call the ``stream()`` method of the HTTP client to get *chunks* of the
 response sequentially instead of waiting for the entire response::
 
     $url = 'https://releases.ubuntu.com/18.04.1/ubuntu-18.04.1-desktop-amd64.iso';
@@ -286,13 +292,13 @@ response sequentially instead of waiting for the entire response::
     // response chunks implement Symfony\Contracts\HttpClient\ChunkInterface
     $fileHandler = fopen('/ubuntu.iso', 'w');
     foreach ($httpClient->stream($response) as $chunk) {
-        fwrite($fileHandler, $chunk->getContent(););
+        fwrite($fileHandler, $chunk->getContent());
     }
 
 Handling Exceptions
 ~~~~~~~~~~~~~~~~~~~
 
-When the HTTP status code of the response is not in the 200-299 range (i.e. 3xx,
+When the HTTP status code of the response is not in the 100-299 range (i.e. 3xx,
 4xx or 5xx) your code is expected to handle it. If you don't do that, the
 ``getHeaders()`` and ``getContent()`` methods throw an appropriate exception::
 
@@ -303,8 +309,8 @@ When the HTTP status code of the response is not in the 200-299 range (i.e. 3xx,
     // because it doesn't check the status code of the response
     $content = $response->getContent();
 
-    // pass FALSE as the optional argument to not throw an exception and
-    // return instead an empty string
+    // pass FALSE as the optional argument to not throw an exception
+    // and get the content of the 403 response instead
     $content = $response->getContent(false);
 
 Caching Requests and Responses
@@ -318,7 +324,8 @@ installed in your application.
 
 ..
 .. TODO:
-.. Show some example of caching requests+responses
+.. Show some example of caching requests+responses - should be move in a dedicated page?
+.. move to a dedicated page?
 ..
 ..
 
@@ -335,19 +342,15 @@ class to autoconfigure the HTTP client based on the requested URL::
     use Symfony\Component\HttpClient\ScopingHttpClient;
 
     $client = HttpClient::create();
-    $httpClient = new ScopingHttpClient($client, [
-        // the key is a regexp which must match the beginning of the request URL
+    $client = new ScopingHttpClient($client, [
+        // the options definesd as values apply only to the URLs matching
+        // the regular expressions defined as keys
         'https://api\.github\.com/' => [
             'headers' => [
                 'Accept' => 'application/vnd.github.v3+json',
                 'Authorization' => 'token '.$githubToken,
             ],
         ],
-
-        // use a '*' wildcard to apply some options to all requests
-        '*' => [
-            // ...
-        ]
     ]);
 
 If the request URL is relative (because you use the ``base_uri`` option), the
@@ -362,30 +365,26 @@ regular expression applied to relative URLs::
             'base_uri' => 'https://api.github.com/',
             // ...
         ],
-
-        '*' => [
-            // ...
-        ]
     ],
         // this is the regexp applied to all relative URLs
         'https://api\.github\.com/'
     );
 
-PSR-7 and PSR-18 Compatibility
-------------------------------
+PSR-18 Compatibility
+--------------------
 
-This component uses its own interfaces and exception classes different from the
-ones defined in `PSR-7`_ (HTTP message interfaces) and `PSR-18`_ (HTTP Client).
-However, it includes the :class:`Symfony\\Component\\HttpClient\\Psr18Client`
+This component uses and implements abstractions defined by the
+``symfony/contracts`` package. 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``.
 
-Before using it in your application, run the following commands to install the
-required dependencies:
+To use it, you the ``psr/http-client`` package and use a `PSR-17`_
+implementations:
 
 .. code-block:: terminal
 
-    # installs the base ClientInterface
+    # installs the PSR-18 ClientInterface
     $ composer require psr/http-client
 
     # installs an efficient implementation of response and stream factories
@@ -437,12 +436,11 @@ If you want to define multiple HTTP clients, use this other expanded configurati
     framework:
         # ...
         http_client:
-            http_clients:
-                crawler:
+            scoped_clients:
+                crawler.client:
                     headers: [{ 'X-Powered-By': 'ACME App' }]
                     http_version: '1.0'
-                default:
-                    max_host_connections: 10
+                some_api.client:
                     max_redirects: 7
 
 Injecting the HTTP Client Into Services
@@ -481,6 +479,8 @@ has a unique service named after its configuration.
         App\Some\Service:
             $someArgument: '@http_client.crawler'
 
+.. TODO tell about named autowiring aliases
+
 Testing HTTP Clients and Responses
 ----------------------------------
 
@@ -533,5 +533,5 @@ However, using ``MockResponse`` allows simulating chunked responses and timeouts
     $mockResponse = new MockResponse($body());
 
 .. _`cURL PHP extension`: https://php.net/curl
-.. _`PSR-7`: https://www.php-fig.org/psr/psr-7/
+.. _`PSR-17`: https://www.php-fig.org/psr/psr-17/
 .. _`PSR-18`: https://www.php-fig.org/psr/psr-18/