Be more friendly to third party users

httplug/users.rst

@@ -5,31 +5,42 @@ If you use a library that depends on HTTPlug (say, ``some/awesome-library``),
 you need to include an HTTPlug client in your project before you can include
 ``awesome-library``.
 
-From the list of :doc:`clients </clients>`, choose on that best fits your
-application, then include it in your project. For instance, if you decide to
-use the Socket client:
+First you need to choose library to send HTTP messages and that also provide the virtual package
+`php-http/client-implementation`_. In the example
+below we are using cURL.
 
-.. code-block:: bash
-
-    $ composer require php-http/socket-client
+.. note::
 
-Instead of an HTTPlug client, you may want to use an adapter for your favorite
-HTTP client. If that turns out to be Guzzle:
+    Read about the clients and adapters provided by the PHP-HTTP organization at :doc:`this page </clients>`.
 
 .. code-block:: bash
 
-    $ composer require php-http/guzzle6-adapter
+    $ composer require php-http/curl-client
 
 Then you can include the library:
 
 .. code-block:: bash
 
     $ composer require some/awesome-library
 
+Secondly you need to install a library that implements PSR-7 and a library containing message factories. The majority
+of users installs Zend's Diactoros or Guzzle's PSR-7. Do one of the following:
+
+.. code-block:: bash
+
+    $ composer require php-http/message zendframework/zend-diactoros
+
+.. code-block:: bash
+
+    $ composer require php-http/message guzzlehttp/psr7
+
 Troubleshooting
 ---------------
 
-If you try to include the HTTPlug-dependent library before you have included a
+Composer fails
+``````````````
+
+If you try to include the HTTPlug dependent library before you have included a
 HTTP client in your project, Composer will throw an error:
 
 .. code-block:: none
@@ -44,13 +55,28 @@ HTTP client in your project, Composer will throw an error:
 
 You can solve this by including a HTTP client or adapter, as described above.
 
+No  message factories
+`````````````````````
+
+You may get an exception telling you that "No message factories found", this means that either you have not installed a
+PSR-7 implementation or that there is no factories installed to create HTTP messages.
+
+.. code-block:: none
+
+    No message factories found. To use Guzzle or Diactoros factories install php-http/message and
+    the chosen message implementation.
+
+
+You can solve this by including ``php-http/message`` and ``zendframework/zend-diactoros``, as described above.
+
 Background
 ----------
 
 Reusable libraries do not depend on a concrete implementation but only on the virtual package
 ``php-http/client-implementation``. This is to avoid hard coupling and allows the user of the
 library to choose the implementation. You can think of this as an "interface" or "contract" for packages.
 
-When *using a reusable library* in an application, one must ``require`` a concrete implementation.
-Make sure the ``require`` section includes a package that provides ``php-http/client-implementation``.
-Failing to do that will lead to composer reporting this error:
+The reusable libraries have no hard coupling to the PSR-7 implementation either which gives you the flexibility to
+choose an implementation yourself.
+
+.. _`php-http/client-implementation`: https://packagist.org/providers/php-http/client-implementation

spelling_word_list.txt

@@ -30,3 +30,4 @@ username
 whitelist
 wiki
 workflow
+Zend