diff --git a/clients/artax-adapter.rst b/clients/artax-adapter.rst index b7962c5..3a48cc4 100644 --- a/clients/artax-adapter.rst +++ b/clients/artax-adapter.rst @@ -13,10 +13,6 @@ not yet included in your project), run: $ composer require php-http/artax-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- @@ -28,16 +24,12 @@ Begin by creating a Artax adapter:: $adapter = new ArtaxAdapter(new DefaultClient(), new GuzzleMessageFactory()); -Or if you installed the :doc:`discovery ` layer:: +Or relying on :doc:`discovery `:: use Http\Adapter\Artax\Client as ArtaxAdapter; $adapter = new ArtaxAdapter(); -.. warning:: - - The message factory parameter is mandatory if the discovery layer is not installed. - -.. include:: includes/further-reading-sync.inc +.. include:: includes/further-reading-async.inc .. _Artax HTTP client: https://github.com/amphp/artax diff --git a/clients/buzz-adapter.rst b/clients/buzz-adapter.rst index 8912c38..79bc4e8 100644 --- a/clients/buzz-adapter.rst +++ b/clients/buzz-adapter.rst @@ -1,7 +1,9 @@ -Buzz Adapter -============ +Buzz Adapter (deprecated) +========================= -An HTTPlug adapter for the `Buzz HTTP client`_. +This adapter only implements the PHP-HTTP synchronous interface. This interface +has been superseded by PSR-18, which the `Buzz HTTP client`_ implements +directly. Installation ------------ @@ -13,10 +15,6 @@ not yet included in your project), run: $ composer require php-http/buzz-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- @@ -44,16 +42,12 @@ Then create the adapter:: $adapter = new BuzzAdapter($browser, new GuzzleMessageFactory()); -Or if you installed the :doc:`discovery ` layer:: +Or relying on :doc:`discovery `:: use Http\Adapter\Buzz\Client as BuzzAdapter; $adapter = new BuzzAdapter($browser); -.. warning:: - - The message factory parameter is mandatory if the discovery layer is not installed. - Be Aware -------- diff --git a/clients/cakephp-adapter.rst b/clients/cakephp-adapter.rst index 027bd1d..8c0742e 100644 --- a/clients/cakephp-adapter.rst +++ b/clients/cakephp-adapter.rst @@ -13,10 +13,6 @@ not yet included in your project), run: $ composer require php-http/cakephp-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- @@ -33,9 +29,8 @@ like:: Then create the adapter:: use Http\Adapter\Cake\Client as CakeAdapter; - use Http\Message\MessageFactory\GuzzleMessageFactory; - $adapter = new CakeAdapter($cakeClient, new GuzzleMessageFactory()); + $adapter = new CakeAdapter($cakeClient); .. note:: @@ -53,6 +48,6 @@ Or if you installed the :doc:`discovery ` layer:: The message factory parameter is mandatory if the discovery layer is not installed. -.. include:: includes/further-reading-sync.inc +.. include:: includes/further-reading-async.inc .. _CakePHP HTTP client: https://book.cakephp.org/3.0/en/core-libraries/httpclient.html diff --git a/clients/curl-client.rst b/clients/curl-client.rst index eb445f2..22822eb 100644 --- a/clients/curl-client.rst +++ b/clients/curl-client.rst @@ -12,16 +12,11 @@ To install the cURL client, run: $ composer require php-http/curl-client -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- -The cURL client needs a :ref:`message factory ` and a -:ref:`stream factory ` in order to to work. You can either specify the factory -explicitly:: +The cURL client needs a PSR-17 message factory and stream factory to work. +You can either specify the factory explicitly:: use Http\Client\Curl\Client; use Http\Message\MessageFactory\DiactorosMessageFactory; @@ -29,13 +24,14 @@ explicitly:: $client = new Client(new DiactorosMessageFactory(), new DiactorosStreamFactory()); -Or you can use :doc:`../discovery`:: +Or you can omit the parameters and let the client use :doc:`../discovery` to +determine a suitable factory:: use Http\Client\Curl\Client; use Http\Discovery\MessageFactoryDiscovery; use Http\Discovery\StreamFactoryDiscovery; - $client = new Client(MessageFactoryDiscovery::find(), StreamFactoryDiscovery::find()); + $client = new Client(); Configuring Client ------------------ @@ -49,7 +45,7 @@ You can use `cURL options `_ to configure Client:: $options = [ CURLOPT_CONNECTTIMEOUT => 10, // The number of seconds to wait while trying to connect. ]; - $client = new Client(MessageFactoryDiscovery::find(), StreamFactoryDiscovery::find(), $options); + $client = new Client(null, null, $options); The following options can not be changed in the set up. Most of them are to be provided with the request instead: @@ -65,4 +61,4 @@ request instead: * CURLOPT_URL * CURLOPT_USERPWD -.. include:: includes/further-reading-sync.inc +.. include:: includes/further-reading-async.inc diff --git a/clients/guzzle5-adapter.rst b/clients/guzzle5-adapter.rst index b0bb481..0ebff38 100644 --- a/clients/guzzle5-adapter.rst +++ b/clients/guzzle5-adapter.rst @@ -1,8 +1,14 @@ -Guzzle5 Adapter -=============== +Guzzle5 Adapter (deprecated) +============================ An HTTPlug adapter for the `Guzzle 5 HTTP client`_. +This adapter only implements the PHP-HTTP synchronous interface. This interface +has been superseded by PSR-18. + +Guzzle 5 is very old and `not maintained anymore`_. We recommend to upgrade to +Guzzle version 7. + Installation ------------ @@ -13,10 +19,6 @@ not yet included in your project), run: $ composer require php-http/guzzle5-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- @@ -50,3 +52,4 @@ Or if you installed the :doc:`discovery ` layer:: .. include:: includes/further-reading-sync.inc .. _Guzzle 5 HTTP client: http://docs.guzzlephp.org/en/5.3/ +.. _not maintained anymore: https://github.com/guzzle/guzzle#version-guidance diff --git a/clients/guzzle7-adapter.rst b/clients/guzzle7-adapter.rst index dfa7f79..faa133a 100644 --- a/clients/guzzle7-adapter.rst +++ b/clients/guzzle7-adapter.rst @@ -2,8 +2,9 @@ Guzzle 7 Adapter ================ An HTTPlug adapter for the `Guzzle 7 HTTP client`_. Guzzle 7 supports PSR-18 -out of the box. This adapter makes sense if you want to use HTTPlug async interface or to use -Guzzle 7 with a library that did not upgrade to PSR-18 yet and depends on ``php-http/client-implementation``. +out of the box. This adapter makes sense if you want to use HTTPlug async +interface or to use Guzzle 7 with a library that did not upgrade to PSR-18 yet +and depends on ``php-http/client-implementation``. Installation ------------ diff --git a/clients/includes/install-discovery.inc b/clients/includes/install-discovery.inc deleted file mode 100644 index 68c431d..0000000 --- a/clients/includes/install-discovery.inc +++ /dev/null @@ -1,6 +0,0 @@ -Alternatively you can install the :doc:`discovery ` layer -to be able to automatically find installed resources, like factories: - -.. code-block:: bash - - $ composer require php-http/discovery diff --git a/clients/includes/install-message-factory.inc b/clients/includes/install-message-factory.inc deleted file mode 100644 index fccb721..0000000 --- a/clients/includes/install-message-factory.inc +++ /dev/null @@ -1,21 +0,0 @@ -This client does not come with a PSR-7 implementation out of the box, so you have -to install one as well (for example `Guzzle PSR-7`_): - -.. code-block:: bash - - $ composer require guzzlehttp/psr7 - -In order to provide full interoperability, message implementations are -accessed through :ref:`factories `. Message factories for -`Laminas Diactoros`_ (and its abandoned predecessor `Zend Diactoros`_), `Guzzle PSR-7`_ and `Slim Framework`_ are available in the -:doc:`message ` component: - -.. code-block:: bash - - $ composer require php-http/message - -.. _Guzzle PSR-7: https://github.com/guzzle/psr7 -.. _Laminas Diactoros: https://github.com/laminas/laminas-diactoros -.. _Slim PSR-7: https://github.com/slimphp/Slim-Psr7 -.. _Zend Diactoros: https://github.com/zendframework/zend-diactoros -.. _Slim Framework: https://github.com/slimphp/Slim diff --git a/clients/mock-client.rst b/clients/mock-client.rst index 5f7b927..9ad6e41 100644 --- a/clients/mock-client.rst +++ b/clients/mock-client.rst @@ -1,7 +1,6 @@ Mock Client =========== - The mock client is a special type of client. It is a test double that does not send the requests that you pass to it, but collects them instead. You can then retrieve those request objects and make assertions about them. Additionally, you diff --git a/clients/react-adapter.rst b/clients/react-adapter.rst index 8e96e84..62d56a8 100644 --- a/clients/react-adapter.rst +++ b/clients/react-adapter.rst @@ -13,10 +13,6 @@ dependency. $ composer require php-http/react-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- diff --git a/clients/socket-client.rst b/clients/socket-client.rst index 4b1c0c4..a90e7e7 100644 --- a/clients/socket-client.rst +++ b/clients/socket-client.rst @@ -1,9 +1,12 @@ -Socket Client -============= +Socket Client (deprecated) +========================== The socket client uses the stream extension from PHP, which is integrated into the core. +This client only implements the PHP-HTTP synchronous interface, which has been +superseded by PSR-18. Use one of the PSR-18 clients instead. + Features -------- @@ -21,7 +24,23 @@ To install the Socket client, run: $ composer require php-http/socket-client -.. include:: includes/install-message-factory.inc +This client does not come with a PSR-7 implementation out of the box, so you have +to install one as well (for example `Guzzle PSR-7`_): + +.. code-block:: bash + + $ composer require guzzlehttp/psr7 + +In order to provide full interoperability, message implementations are accessed +through :ref:`factories `. Message factories for +`Laminas Diactoros`_ (and its abandoned predecessor `Zend Diactoros`_), +`Guzzle PSR-7`_ and `Slim PSR-7`_ are available in the +:doc:`message ` component: + +.. code-block:: bash + + $ composer require php-http/message + Usage ----- @@ -49,8 +68,8 @@ The available options are: :write_buffer_size: When sending the request we need to buffer the body, this option specify the size of this buffer, default is 8192, if you are sending big file with your client it may be interesting to have a bigger value in order to increase performance. -As an example someone may want to pass a client certificate when using the ssl, a valid configuration for this -use case would be:: +As an example someone may want to pass a client certificate when using the ssl, +a valid configuration for this use case would be:: use Http\Client\Socket\Client; @@ -65,9 +84,11 @@ use case would be:: .. warning:: - This client assumes that the request is compliant with HTTP 2.0, 1.1 or 1.0 standard. So a request without a ``Host`` header, or - with a body but without a ``Content-Length`` will certainly fail. - To make sure all requests will be sent out correctly, we recommend to use the ``PluginClient`` with the following plugins: + This client assumes that the request is compliant with HTTP 2.0, 1.1 or 1.0 + standard. So a request without a ``Host`` header, or with a body but + without a ``Content-Length`` will certainly fail. To make sure all requests + will be sent out correctly, we recommend to use the ``PluginClient`` with + the following plugins: * ``ContentLengthPlugin`` sets the correct ``Content-Length`` header, or decorate the stream to use chunked encoding * ``DecoderPlugin`` decodes encoding coming from the response (chunked, gzip, deflate and compress) @@ -75,3 +96,8 @@ use case would be:: :doc:`Read more on plugins ` .. include:: includes/further-reading-sync.inc + +.. _Guzzle PSR-7: https://github.com/guzzle/psr7 +.. _Laminas Diactoros: https://github.com/laminas/laminas-diactoros +.. _Slim PSR-7: https://github.com/slimphp/Slim-Psr7 +.. _Zend Diactoros: https://github.com/zendframework/zend-diactoros diff --git a/clients/symfony-client.rst b/clients/symfony-client.rst index 91a8d98..c490b45 100644 --- a/clients/symfony-client.rst +++ b/clients/symfony-client.rst @@ -12,15 +12,15 @@ To install the Symfony client, run: $ composer require symfony/http-client -This client does not come with a PSR-7 implementation out of the box, so you have -to install one as well. `Nyholm PSR-7`_ is supported natively: +This client does not come with a PSR-7 implementation out of the box. If you do +not require one, `discovery <../discovery>` will install `Nyholm PSR-7`_. If +you do not allow the composer plugin of the ``php-http/discovery`` component, +you need to install a PSR-7 implementation manually: .. code-block:: bash $ composer require nyholm/psr7 -.. include:: includes/install-discovery.inc - Usage ----- .. code-block:: php diff --git a/clients/zend-adapter.rst b/clients/zend-adapter.rst index 322f105..01e12a8 100644 --- a/clients/zend-adapter.rst +++ b/clients/zend-adapter.rst @@ -1,8 +1,15 @@ -Zend Adapter -============ +Zend Adapter (deprecated) +========================= An HTTPlug adapter for the Zend HTTP client. +Zend framework meanwhile has been renamed to Laminas, and the client is no +longer maintained. + +This adapter only implements the PHP-HTTP synchronous interface. This interface +has been superseded by PSR-18, which the `Laminas Diactoros`_ implements +directly. + Installation ------------ @@ -13,11 +20,4 @@ not yet included in your project), run: $ composer require php-http/zend-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - -Usage ------ - -To be written... +.. _Laminas Diactoros: https://docs.laminas.dev/laminas-diactoros/ diff --git a/message.rst b/message.rst index 841d3c8..f369f90 100644 --- a/message.rst +++ b/message.rst @@ -11,6 +11,4 @@ This package contains various PSR-7 tools which might be useful in an HTTP workf * Authentication method implementations * Various Stream encoding tools * Message decorators -* Message factory implementations for Guzzle PSR-7, Diactoros and Slim Framework. -* Stream and URI factory implementations for Guzzle PSR-7 and Diactoros * Cookie implementation diff --git a/message/message-factory.rst b/message/message-factory.rst index 0852733..9d7b93d 100644 --- a/message/message-factory.rst +++ b/message/message-factory.rst @@ -1,28 +1,26 @@ .. _message-factory: .. _stream-factory: -HTTP Factories -============== +HTTP Factories (deprecated) +=========================== **Factory interfaces for PSR-7 HTTP objects.** +This package has been superseded by `PSR-17`_. Our HTTP-PHP factories have been +retired and the repository archived. The PHP-HTTP libraries switched to use the +PSR-17 factories. Please migrate your code to the PSR-17 factories too. + Rationale --------- -While it should be possible to use every PSR-7 aware HTTP client with any -request, URI and stream implementation, instantiating objects explicitly would -still tie the code to a specific implementation. If each reusable library is -tied to a specific message implementation, an application could end up -installing several message implementations. The factories move instantiation -out of the library code, further decoupling libraries from implementation. - -The FIG was pretty straightforward by NOT putting any construction logic into PSR-7. -The ``MessageFactory`` aims to provide an easy way to construct messages. +At the time of building this, PSR-17 did not yet exist. Read the documentation +of `PSR-17`_ to learn why a standard for factories is useful. Factories --------- -The `php-http/message-factory` package defines interfaces for PSR-7 factories including: +The `php-http/message-factory` package defines interfaces for PSR-7 factories +including: - ``RequestFactory`` - ``ResponseFactory`` @@ -30,7 +28,9 @@ The `php-http/message-factory` package defines interfaces for PSR-7 factories in - ``StreamFactory`` - ``UriFactory`` -Implementations of the interfaces above for `Laminas Diactoros`_ (and its abandoned predecessor `Zend Diactoros`_), `Guzzle PSR-7`_ and the `Slim Framework`_ can be found in ``php-http/message``. +Implementations of the interfaces above for `Laminas Diactoros`_ (and its +abandoned predecessor `Zend Diactoros`_), `Guzzle PSR-7`_ and the +`Slim PSR-7`_ can be found in ``php-http/message``. Usage ----- @@ -127,14 +127,7 @@ automatically find an available factory in the client:: type hint, instead of the ``MessageFactory``. And vice versa if you create responses only. -Server Side Factories ---------------------- - -It would make sense to also provide factories for the server side constructs -``ServerRequestInterface`` and ``UploadedFileInterface``. We did not get around -to do that yet. Contributions are welcome if you want to define the -``ServerRequestFactory`` and ``UploadedFileFactory``. - +.. _PSR-17: https://www.php-fig.org/psr/psr-17/ .. _Guzzle PSR-7: https://github.com/guzzle/psr7 .. _Laminas Diactoros: https://github.com/laminas/laminas-diactoros .. _Slim PSR-7: https://github.com/slimphp/Slim-Psr7