Merge branch '4.4'

* 4.4:
  [HttpClient] add words about HTTPlug

Author: javiereguiluz

components/http_client.rst

@@ -617,15 +617,15 @@ regular expression applied to relative URLs::
 Interoperability
 ----------------
 
-The component is interoperable with two different abstractions for HTTP clients:
-`Symfony Contracts`_ and `PSR-18`_. If your application uses libraries that need
-any of them, the component is compatible with both. They also benefit from
-:ref:`autowiring aliases <service-autowiring-alias>` when the
-:ref:`framework bundle <framework-bundle-configuration>` is used.
+The component is interoperable with three different abstractions for HTTP
+clients: `Symfony Contracts`_, `PSR-18`_ and `HTTPlug`_ v1 and v2. If your
+application uses libraries that need any of them, the component is compatible
+with all of them. They also benefit from :ref:`autowiring aliases <service-autowiring-alias>`
+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.
+either Symfony Contracts (recommended) or PSR-18 (which superseded HTTPlug).
 
 Symfony Contracts
 ~~~~~~~~~~~~~~~~~
@@ -657,12 +657,14 @@ 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
-~~~~~~
+PSR-18 and PSR-17
+~~~~~~~~~~~~~~~~~
 
 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``.
+This class also implements the relevant methods of `PSR-17`_ to ease creating
+request objects.
 
 To use it, you need the ``psr/http-client`` package and a `PSR-17`_ implementation:
 
@@ -677,18 +679,72 @@ To use it, you need the ``psr/http-client`` package and a `PSR-17`_ implementati
 
 Now you can make HTTP requests with the PSR-18 client as follows::
 
-    use Nyholm\Psr7\Factory\Psr17Factory;
     use Symfony\Component\HttpClient\Psr18Client;
 
-    $psr17Factory = new Psr17Factory();
-    $psr18Client = new Psr18Client();
+    $client = new Psr18Client();
 
     $url = 'https://symfony.com/versions.json';
-    $request = $psr17Factory->createRequest('GET', $url);
-    $response = $psr18Client->sendRequest($request);
+    $request = $client->createRequest('GET', $url);
+    $response = $client->sendRequest($request);
 
     $content = json_decode($response->getBody()->getContents(), true);
 
+.. versionadded:: 4.4
+
+    The PSR-17 factory methods of ``Psr18Client`` were introduced in Symfony 4.4.
+
+HTTPlug
+~~~~~~~
+
+.. versionadded:: 4.4
+
+    Support for HTTPlug was introduced in Symfony 4.4.
+
+The `HTTPlug`_ specification was published before PSR-18 and is superseded by
+it. As such, you should not use it in newly written code. Yet, many libraries
+still require v1 or v2 of it. The component is interoperable with them thanks to
+the ``HttplugClient`` adapter class. Similarly to ``Psr18Client`` implementing
+relevant parts of PSR-17, ``HttplugClient`` also implements the factory methods
+defined in the related ``php-http/message-factory`` package.
+
+Internally, the implementation relies on the ``Psr18Client``, so that the
+``psr/http-client`` package is needed to use this class::
+
+.. code-block:: terminal
+
+    # Let's suppose php-http/httplug is already required by the lib you want to use
+
+    # installs the PSR-18 ClientInterface
+    $ composer require psr/http-client
+
+    # installs an efficient implementation of response and stream factories
+    # with autowiring aliases provided by Symfony Flex
+    $ composer require nyholm/psr7
+
+Let's say you want to instantiate a class with the following constructor,
+that requires HTTPlug dependencies::
+
+    use Http\Client\HttpClient;
+    use Http\Message\RequestFactory;
+    use Http\Message\StreamFactory;
+
+    class SomeSdk
+    {
+        public function __construct(
+            HttpClient $httpClient,
+            RequestFactory $requestFactory,
+            StreamFactory $streamFactory
+        )
+        // [...]
+    }
+
+Because ``HttplugClient`` implements the three interfaces, you can use it this way::
+
+    use Symfony\Component\HttpClient\HttplugClient;
+
+    $httpClient = new HttplugClient();
+    $apiClient = new SomeSdk($httpClient, $httpClient, $httpClient);
+
 Symfony Framework Integration
 -----------------------------
 
@@ -811,4 +867,5 @@ 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/
+.. _`HTTPlug`: https://github.com/php-http/httplug/#readme
 .. _`Symfony Contracts`: https://github.com/symfony/contracts