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 define them as an
+associative array via 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 in the 300-599 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::
 
@@ -335,19 +341,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 defined 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 +364,25 @@ 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 need the ``psr/http-client`` package and a `PSR-17`_ implementation:
 
 .. 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 +434,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
@@ -533,5 +529,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/

reference/configuration/framework.rst

@@ -90,30 +90,51 @@ Configuration
 
 * `http_client`_
 
-  * `auth_basic`_
-  * `auth_bearer`_
-  * `base_uri`_
-  * `bindto`_
-  * `buffer`_
-  * `cafile`_
-  * `capath`_
-  * `capture_peer_cert_chain`_
-  * `ciphers`_
-  * `headers`_
-  * `http_version`_
-  * `local_cert`_
-  * `local_pk`_
+  * `default_options`_
+
+      * `bindto`_
+      * `cafile`_
+      * `capath`_
+      * `ciphers`_
+      * `headers`_
+      * `http_version`_
+      * `local_cert`_
+      * `local_pk`_
+      * `max_redirects`_
+      * `no_proxy`_
+      * `passphrase`_
+      * `peer_fingerprint`_
+      * `proxy`_
+      * `resolve`_
+      * `timeout`_
+      * `verify_host`_
+      * `verify_peer`_
+
   * `max_host_connections`_
-  * `max_redirects`_
-  * `no_proxy`_
-  * `passphrase`_
-  * `peer_fingerprint`_
-  * `proxy`_
-  * `query`_
-  * `resolve`_
-  * `timeout`_
-  * `verify_host`_
-  * `verify_peer`_
+  * `scoped_clients`_
+
+      * `scope`_
+      * `auth_basic`_
+      * `auth_bearer`_
+      * `base_uri`_
+      * `bindto`_
+      * `cafile`_
+      * `capath`_
+      * `ciphers`_
+      * `headers`_
+      * `http_version`_
+      * `local_cert`_
+      * `local_pk`_
+      * `max_redirects`_
+      * `no_proxy`_
+      * `passphrase`_
+      * `peer_fingerprint`_
+      * `proxy`_
+      * `query`_
+      * `resolve`_
+      * `timeout`_
+      * `verify_host`_
+      * `verify_peer`_
 
 * `http_method_override`_
 * `ide`_
@@ -662,39 +683,49 @@ when the request starts with this path.
 http_client
 ~~~~~~~~~~~
 
-If there's only one HTTP client defined in the app, you can configure it
-directly under the ``framework.http_client`` option:
+When the HttpClient component is installed, an HTTP client is available
+as a service named ``http_client`` or using the autowiring alias
+:class:`Symfony\\Constracts\\HttpClient\\HttpClientInterface`.
+
+This service can be configured using ``framework.http_client.default_options``:
 
 .. code-block:: yaml
 
     # config/packages/framework.yaml
     framework:
         # ...
         http_client:
-            headers: [{ 'X-Powered-By': 'ACME App' }]
             max_host_connections: 10
-            max_redirects: 7
+            default_options:
+                headers: [{ 'X-Powered-By': 'ACME App' }]
+                max_redirects: 7
 
-If the app defines multiple HTTP clients, you must give them a unique name and
-define them under the type of HTTP client you are creating (``http_clients`` for
-regular clients and ``api_clients`` for clients that include utilities to
-consume APIs):
+Multiple pre-configured HTTP client services can be defined, each with its
+service name defined as a key under ``scoped_clients``. Scoped clients inherit
+the default options defined for the ``http_client`` service. You can override
+these options and can define a few others:
 
 .. code-block:: yaml
 
     # config/packages/framework.yaml
     framework:
         # ...
         http_client:
-            http_clients:
-                crawler:
-                    # ...
-                default:
-                    # ...
-            api_clients:
-                github:
+            scoped_clients:
+                my_api.client:
+                    auth_bearer: secret_bearer_token
                     # ...
 
+Options defined for scoped clients apply only to URLs that match either their
+`base_uri`_ or the `scope`_ option when it is defined. Non-matching URLs always
+use default options.
+
+Each scoped client also define a corresponding named autowiring alias.
+E.g. if you use
+``Symfony\Constracts\HttpClient\HttpClientInterface $myApiClient``
+as the type and name of an argument, autowiring will inject the ``my_api.client``
+service into your autowired classes.
+
 auth_basic
 ..........
 
@@ -743,15 +774,6 @@ bindto
 A network interface name, IP address, a host name or a UNIX socket to use as the
 outgoing network interface.
 
-buffer
-......
-
-**type**: ``boolean``
-
-.. TODO: improve this useless description
-
-Indicates if the response should be buffered or not.
-
 cafile
 ......
 
@@ -767,14 +789,6 @@ capath
 
 The path to a directory that contains one or more certificate authority files.
 
-capture_peer_cert_chain
-.......................
-
-**type**: ``boolean``
-
-If ``true``, the response includes a ``peer_certificate_chain`` attribute with
-the peer certificates (OpenSSL X.509 resources).
-
 ciphers
 .......
 
@@ -887,17 +901,27 @@ resolve
 
 A list of hostnames and their IP addresses to pre-populate the DNS cache used by
 the HTTP client in order to avoid a DNS lookup for those hosts. This option is
-useful both to improve performance and to make your tests easier.
+useful to improve security when IPs are checked before the URL is passed to the
+client and to make your tests easier.
 
 The value of this option is an associative array of ``domain => IP address``
 (e.g ``['symfony.com' => '46.137.106.254', ...]``).
 
+scope
+.....
+
+**type**: ``string``
+
+For scoped clients only: the regular expression that the URL must match before
+applying all other non-default options. By default, the scope is derived from
+`base_uri`_.
+
 timeout
 .......
 
 **type**: ``float`` **default**: depends on your PHP config
 
-Time, in seconds, to wait for a response. If the response takes longer, a
+Time, in seconds, to wait for a response. If the response stales for longer, a
 :class:`Symfony\\Component\\HttpClient\\Exception\\TransportException` is thrown.
 Its default value is the same as the value of PHP's `default_socket_timeout`_
 config option.