Merge pull request #281 from php-http/psr-18

mention psr-18

clients.rst

@@ -48,12 +48,13 @@ Composer Virtual Packages
 
 Virtual packages are a way to specify the dependency on an implementation of an interface-only repository
 without forcing a specific implementation. For HTTPlug, the virtual packages are called `php-http/client-implementation`_
-and `php-http/async-client-implementation`_.
+(though you should be using `psr/http-client-implementation`_ to use PSR-18) and `php-http/async-client-implementation`_.
 
 There is no library registered with those names. However, all client implementations (including client adapters) for
 HTTPlug use the ``provide`` section to tell composer that they do provide the client-implementation.
 
 .. _`php-http/client-implementation`: https://packagist.org/providers/php-http/client-implementation
+.. _`psr/http-client-implementation`: https://packagist.org/providers/psr/http-client-implementation
 .. _`php-http/async-client-implementation`: https://packagist.org/providers/php-http/async-client-implementation
 .. _`Adapter pattern`: https://en.wikipedia.org/wiki/Adapter_pattern
 .. _`Liskov substitution principle`: https://en.wikipedia.org/wiki/Liskov_substitution_principle

httplug/introduction.rst

@@ -12,12 +12,16 @@ Client Interfaces
 
 HTTPlug defines two HTTP client interfaces that we kept as simple as possible:
 
-* ``HttpClient`` defines a ``sendRequest`` method that sends a PSR-7
-  ``RequestInterface`` and either returns a PSR-7 ``ResponseInterface`` or
-  throws an exception that implements ``Http\Client\Exception``.
+* PSR-18 defines the ``ClientInterface`` with a ``sendRequest`` method that
+  accepts a PSR-7 ``RequestInterface`` and either returns a PSR-7
+  ``ResponseInterface`` or throws an exception that implements
+  ``Psr\Http\Client\ClientExceptionInterface``.
 
-* ``HttpAsyncClient`` defines a ``sendAsyncRequest`` method that sends a request
-  asynchronously and always returns a ``Http\Client\Promise``.
+  HTTPlug has the compatible interface ``HttpClient`` which now extends the
+  PSR-18 interface to allow migrating to PSR-18.
+
+* ``HttpAsyncClient`` defines a ``sendAsyncRequest`` method that sends a PSR-7
+  request asynchronously and always returns a ``Http\Client\Promise``.
   See :doc:`../components/promise` for more information.
 
 Implementations
@@ -29,16 +33,22 @@ PHP-HTTP offers two types of clients that implement the above interfaces:
 
    Examples: :doc:`/clients/curl-client` and :doc:`/clients/socket-client`.
 
-2. Adapters that wrap existing HTTP client, such as Guzzle. These adapters act
+2. Adapters that wrap existing HTTP clients, such as Guzzle. These adapters act
    as a bridge between the HTTPlug interfaces and the clients that do not (yet)
    implement these interfaces.
 
-   Examples: :doc:`/clients/guzzle6-adapter` and :doc:`/clients/react-adapter`.
+   More and more clients implement PSR-18 directly. If that is all you need, we
+   recommend not using HTTPlug as it would only add overhead. However, as there
+   is no PSR for asynchronous requests yet, you can use the adapters to do such
+   requests without binding yourself to a specific implementation.
+
+   Examples: :doc:`/clients/guzzle7-adapter` and :doc:`/clients/react-adapter`.
 
 .. note::
 
-    Ideally, all HTTP client libraries out there will implement the HTTPlug
-    interfaces. At that point, our adapters will no longer be necessary.
+    Ideally, there will be a PSR for asynchronous requests and all HTTP client
+    libraries out there will implement PSR-18 and the not yet existing PSR. At
+    that point, our adapters will no longer be necessary.
 
 Usage
 -----

httplug/library-developers.rst

@@ -11,7 +11,8 @@ Manage Dependencies
 -------------------
 
 To depend on *some* HTTP client, specify either
-``php-http/client-implementation`` or ``php-http/async-client-implementation``
+``psr/http-client-implementation`` for PSR-18 synchronous requests or
+``php-http/async-client-implementation`` for asynchronous requests
 in your library’s ``composer.json``. These are virtual Composer packages that
 will throw an error if no concrete client was found:
 
@@ -20,7 +21,7 @@ will throw an error if no concrete client was found:
     {
         "name": "you/and-your-awesome-library",
         "require": {
-            "php-http/client-implementation": "^1.0"
+            "psr/http-client-implementation": "^1.0"
         }
     }
 
@@ -50,7 +51,7 @@ in the ``require-dev`` section in your library’s ``composer.json``. You could
     {
         "name": "you/and-your-awesome-library",
         "require": {
-            "php-http/client-implementation": "^1.0"
+            "psr/http-client-implementation": "^1.0"
         },
         "require-dev": {
             "php-http/mock-client": "^1.0"
@@ -96,7 +97,7 @@ Putting it all together your final ``composer.json`` is much likely to look simi
         "name": "you/and-your-awesome-library",
         "require": {
             "psr/http-message": "^1.0",
-            "php-http/client-implementation": "^1.0",
+            "psr/http-client-implementation": "^1.0",
             "php-http/httplug": "^1.0",
             "php-http/message-factory": "^1.0",
             "php-http/discovery": "^1.0"

index.rst

@@ -7,10 +7,15 @@ PHP-HTTP: standardized HTTP for PHP
     :alt: HTTPlug Logo
 
 PHP-HTTP is the next step in standardizing HTTP interaction for PHP packages.
+
 It builds on top of PSR-7_, which defines interfaces for HTTP requests and
-responses. PSR-7 does not describe, however, the way you should create requests
-or send them. PHP-HTTP aims to fill that gap by offering an HTTP client
-interface: HTTPlug.
+responses. The HTTPlug HTTP client interface has been standardized in PSR-18_
+to define synchronous HTTP requests. When using a client that implements PSR-18,
+we recommend directly using PSR-18 and not HTTPlug nor our adapters.
+
+However, PSR-18 does not define asynchronous requests. HTTPlug provides interfaces
+for those, but to do that also needs to define how :doc:`promises <components/promise>`
+are implemented.
 
 PHP-HTTP has three goals:
 
@@ -19,9 +24,8 @@ PHP-HTTP has three goals:
 
 2. Provide good quality HTTP-related packages to the PHP community.
 
-3. Over time, make HTTPlug a PHP Standards Recommendation (PSR) so that clients
-   will directly implement the HTTPlug interface and our adapters are no longer
-   needed.
+3. Now that PSR-18 exists, we miss a PSR for asynchronous requests. This is blocked
+   by not having a PSR for promises.
 
 HTTPlug
 -------