@@ -11,8 +11,7 @@ The HttpClient Component
11
11
12
12
.. versionadded :: 4.3
13
13
14
- The HttpClient component was introduced in Symfony 4.3 and it's still
15
- considered an :doc: `experimental feature </contributing/code/experimental >`.
14
+ The HttpClient component was introduced in Symfony 4.3.
16
15
17
16
Installation
18
17
------------
@@ -622,15 +621,15 @@ regular expression applied to relative URLs::
622
621
Interoperability
623
622
----------------
624
623
625
- The component is interoperable with two different abstractions for HTTP clients:
626
- `Symfony Contracts `_ and `PSR-18 `_. If your application uses libraries that need
627
- any of them, the component is compatible with both. They also benefit from
628
- :ref: `autowiring aliases <service-autowiring-alias >` when the
629
- :ref: `framework bundle <framework-bundle-configuration >` is used.
624
+ The component is interoperable with three different abstractions for HTTP
625
+ clients: `Symfony Contracts `_, `PSR-18 `_ and ` HTTPlug `_ v1 and v2. If your
626
+ application uses libraries that need any of them, the component is compatible
627
+ with all of them. They also benefit from :ref: `autowiring aliases <service-autowiring-alias >`
628
+ when the :ref: `framework bundle <framework-bundle-configuration >` is used.
630
629
631
630
If you are writing or maintaining a library that makes HTTP requests, you can
632
631
decouple it from any specific HTTP client implementations by coding against
633
- either Symfony Contracts (recommended) or PSR-18.
632
+ either Symfony Contracts (recommended) or PSR-18 (which superseded HTTPlug) .
634
633
635
634
Symfony Contracts
636
635
~~~~~~~~~~~~~~~~~
@@ -662,12 +661,14 @@ the PSR-18 abstraction, which provides none related to the transport itself.
662
661
Another major feature covered by the Symfony Contracts is async/multiplexing,
663
662
as described in the previous sections.
664
663
665
- PSR-18
666
- ~~~~~~
664
+ PSR-18 and PSR-17
665
+ ~~~~~~~~~~~~~~~~~
667
666
668
667
This component implements the `PSR-18 `_ (HTTP Client) specifications via the
669
668
:class: `Symfony\\ Component\\ HttpClient\\ Psr18Client ` class, which is an adapter
670
669
to turn a Symfony ``HttpClientInterface `` into a PSR-18 ``ClientInterface ``.
670
+ This class also implements the relevant methods of `PSR-17 `_ to ease creating
671
+ request objects.
671
672
672
673
To use it, you need the ``psr/http-client `` package and a `PSR-17 `_ implementation:
673
674
@@ -682,18 +683,72 @@ To use it, you need the ``psr/http-client`` package and a `PSR-17`_ implementati
682
683
683
684
Now you can make HTTP requests with the PSR-18 client as follows::
684
685
685
- use Nyholm\Psr7\Factory\Psr17Factory;
686
686
use Symfony\Component\HttpClient\Psr18Client;
687
687
688
- $psr17Factory = new Psr17Factory();
689
- $psr18Client = new Psr18Client();
688
+ $client = new Psr18Client();
690
689
691
690
$url = 'https://symfony.com/versions.json';
692
- $request = $psr17Factory ->createRequest('GET', $url);
693
- $response = $psr18Client ->sendRequest($request);
691
+ $request = $client ->createRequest('GET', $url);
692
+ $response = $client ->sendRequest($request);
694
693
695
694
$content = json_decode($response->getBody()->getContents(), true);
696
695
696
+ .. versionadded :: 4.4
697
+
698
+ The PSR-17 factory methods of ``Psr18Client `` were introduced in Symfony 4.4.
699
+
700
+ HTTPlug
701
+ ~~~~~~~
702
+
703
+ .. versionadded :: 4.4
704
+
705
+ Support for HTTPlug was introduced in Symfony 4.4.
706
+
707
+ The `HTTPlug `_ specification was published before PSR-18 and is superseded by
708
+ it. As such, you should not use it in newly written code. Yet, many libraries
709
+ still require v1 or v2 of it. The component is interoperable with them thanks to
710
+ the ``HttplugClient `` adapter class. Similarly to ``Psr18Client `` implementing
711
+ relevant parts of PSR-17, ``HttplugClient `` also implements the factory methods
712
+ defined in the related ``php-http/message-factory `` package.
713
+
714
+ Internally, the implementation relies on the ``Psr18Client ``, so that the
715
+ ``psr/http-client `` package is needed to use this class:
716
+
717
+ .. code-block :: terminal
718
+
719
+ # Let's suppose php-http/httplug is already required by the lib you want to use
720
+
721
+ # installs the PSR-18 ClientInterface
722
+ $ composer require psr/http-client
723
+
724
+ # installs an efficient implementation of response and stream factories
725
+ # with autowiring aliases provided by Symfony Flex
726
+ $ composer require nyholm/psr7
727
+
728
+ Let's say you want to instantiate a class with the following constructor,
729
+ that requires HTTPlug dependencies::
730
+
731
+ use Http\Client\HttpClient;
732
+ use Http\Message\RequestFactory;
733
+ use Http\Message\StreamFactory;
734
+
735
+ class SomeSdk
736
+ {
737
+ public function __construct(
738
+ HttpClient $httpClient,
739
+ RequestFactory $requestFactory,
740
+ StreamFactory $streamFactory
741
+ )
742
+ // [...]
743
+ }
744
+
745
+ Because ``HttplugClient `` implements the three interfaces, you can use it this way::
746
+
747
+ use Symfony\Component\HttpClient\HttplugClient;
748
+
749
+ $httpClient = new HttplugClient();
750
+ $apiClient = new SomeSdk($httpClient, $httpClient, $httpClient);
751
+
697
752
Symfony Framework Integration
698
753
-----------------------------
699
754
@@ -816,4 +871,5 @@ However, using ``MockResponse`` allows simulating chunked responses and timeouts
816
871
.. _`cURL PHP extension` : https://php.net/curl
817
872
.. _`PSR-17` : https://www.php-fig.org/psr/psr-17/
818
873
.. _`PSR-18` : https://www.php-fig.org/psr/psr-18/
874
+ .. _`HTTPlug` : https://github.com/php-http/httplug/#readme
819
875
.. _`Symfony Contracts` : https://github.com/symfony/contracts
0 commit comments