diff --git a/httplug/users.rst b/httplug/users.rst index 4834cb0..b1675aa 100644 --- a/httplug/users.rst +++ b/httplug/users.rst @@ -5,20 +5,17 @@ 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 `, 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 `. .. code-block:: bash - $ composer require php-http/guzzle6-adapter + $ composer require php-http/curl-client Then you can include the library: @@ -26,10 +23,24 @@ Then you can include the library: $ 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,6 +55,20 @@ 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 ---------- @@ -51,6 +76,7 @@ Reusable libraries do not depend on a concrete implementation but only on the vi ``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 diff --git a/spelling_word_list.txt b/spelling_word_list.txt index 21f86fe..858031e 100644 --- a/spelling_word_list.txt +++ b/spelling_word_list.txt @@ -30,3 +30,4 @@ username whitelist wiki workflow +Zend