diff --git a/clients.rst b/clients.rst index 8409555..9736f07 100644 --- a/clients.rst +++ b/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 diff --git a/httplug/introduction.rst b/httplug/introduction.rst index 52b9dff..4c2ceea 100644 --- a/httplug/introduction.rst +++ b/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 ----- diff --git a/httplug/library-developers.rst b/httplug/library-developers.rst index f66d465..9e95757 100644 --- a/httplug/library-developers.rst +++ b/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" diff --git a/index.rst b/index.rst index 0dec400..9e4d068 100644 --- a/index.rst +++ b/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 ` +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 -------