adjust documentation to PSR-17 and PSR-18, deprecate a couple of obsolete PHP-HTTP adapters and clients

dbu · dbu · commit f1343ebca8ec · 2023-05-15T08:50:43.000+02:00
diff --git 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 </discovery>` layer::
+Or relying on :doc:`discovery </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
@@ -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 </discovery>` layer::
+Or relying on :doc:`discovery </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
@@ -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 </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
@@ -12,30 +12,26 @@ 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 <message-factory>` and a
-:ref:`stream factory <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;
     use Http\Message\StreamFactory\DiactorosStreamFactory;
 
     $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 <http://php.net/curl_setopt>`_ 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
@@ -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 </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
@@ -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
diff --git a/clients/includes/install-message-factory.inc b/clients/includes/install-message-factory.inc
diff --git 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
@@ -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
@@ -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-factory>`. Message factories for
+`Laminas Diactoros`_ (and its abandoned predecessor `Zend Diactoros`_),
+`Guzzle PSR-7`_ and `Slim PSR-7`_ are available in the
+:doc:`message </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,13 +84,20 @@ 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)
 
     :doc:`Read more on plugins </plugins/introduction>`
 
 .. 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
@@ -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
@@ -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
@@ -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
