Skip to content

Commit e1402ab

Browse files
ddeboerddeboer
committed
Merge pull request #65 from php-http/merge-httplug-intro
Merge HTTPlug intro and re-group TOC
2 parents ace1a8a + b4a7cf3 commit e1402ab

11 files changed

+224
-180
lines changed

Diff for: ‎clients.rst

+14-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@ Clients & Adapters
44
There are clients implementing one of the HTTPlug interfaces directly,
55
and adapter packages that implement the interface and forward the calls to HTTP clients not implementing the interface.
66

7-
TODO
7+
.. _`php-http/client-implementation`: https://packagist.org/providers/php-http/client-implementation
8+
.. _`php-http/async-client-implementation`: https://packagist.org/providers/php-http/async-client-implementation:
9+
810

911
Clients:
1012

@@ -21,3 +23,14 @@ Client adapters:
2123
clients/guzzle5-adapter
2224
clients/guzzle6-adapter
2325
clients/react-adapter
26+
27+
Composer Virtual Packages
28+
-------------------------
29+
30+
Virtual packages are a way to specify the dependency on an implementation of an interface-only repository
31+
without forcing a specific implementation. For HTTPlug, the virtual package is called ``php-http/client-implementation``.
32+
33+
There is no project registered with that name. However, all client implementations including client adapters for
34+
HTTPlug use the ``provide`` section to tell composer that they do provide the client-implementation.
35+
36+

Diff for: ‎conf.py

+1
Original file line numberDiff line numberDiff line change
@@ -301,4 +301,5 @@
301301
rst_epilog = """
302302
.. _PSR-7: http://www.php-fig.org/psr/psr-7
303303
.. _Composer: https://getcomposer.org
304+
.. _HttplugBundle: https://github.com/php-http/HttplugBundle
304305
"""

Diff for: ‎httplug.rst

-29
This file was deleted.

Diff for: ‎httplug/application-developers.rst

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
HTTPlug for application developers
2+
==================================
3+
4+
Framework integration
5+
---------------------
6+
7+
HTTPlug can be used in any PHP based project. Nonetheless, we provide
8+
integration for some popular frameworks:
9+
10+
- HttplugBundle_: integration with the Symfony framework.
11+

Diff for: ‎httplug/introduction.rst

+42-71
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,66 @@
1-
Introduction to HTTPlug
2-
=======================
1+
HTTPlug: HTTP client abstraction
2+
================================
33

4-
HTTPlug implementations
5-
-----------------------
4+
HTTPlug allows you to write reusable libraries and applications that need
5+
an HTTP client without binding to a specific implementation.
6+
When all packages used in an application only specify HTTPlug,
7+
the application developers can choose the client that best fits their project
8+
and use the same client with all packages.
69

7-
HTTPlug implementations typically are either HTTP clients of their own, or adapters wrapping existing clients
8-
like Guzzle 6. In the latter case, they will depend on the required client implementation,
9-
so you only need to require the adapter and not the actual client.
10+
The client interfaces
11+
---------------------
1012

13+
HTTPlug defines two HTTP client interfaces that we kept as simple as possible:
1114

12-
There are two kind of implementations:
15+
* ``HttpClient`` defines a ``sendRequest`` method that sends a PSR-7
16+
``RequestInterface`` and either returns a PSR-7 ``ResponseInterface`` or
17+
throws an exception that implements ``Http\Client\Exception``.
1318

14-
- `php-http/client-implementation`_:
15-
the synchronous implementation that waits for the response / error before returning from the ``sendRequest`` method.
19+
* ``HttpAsyncClient`` defines a ``sendAsyncRequest`` method that sends a request
20+
asynchronously and always returns a ``Http\Client\Promise``.
1621

17-
- `php-http/async-client-implementation`_:
18-
the asynchronous implementation that immediately returns a ``Http\Promise\Promise``,
19-
allowing to send several requests in parallel and handling responses later.
22+
Implementations
23+
---------------
2024

21-
Check links above for the full list of implementations.
25+
PHP-HTTP offers two types of clients that implement the above interfaces:
2226

23-
.. _`php-http/client-implementation`: https://packagist.org/providers/php-http/client-implementation
24-
.. _`php-http/async-client-implementation`: https://packagist.org/providers/php-http/async-client-implementation:
27+
1. Standalone clients that directly implement the interfaces.
2528

26-
Usage in an application
27-
-----------------------
29+
Examples: :doc:`/clients/curl-client` and :doc:`/clients/socket-client`.
2830

29-
When writing an application, you need to require a concrete implementation_.
31+
2. Adapters that wrap existing HTTP client, such as Guzzle. These adapters act
32+
as a bridge between the HTTPlug interfaces and the clients that do not (yet)
33+
implement these interfaces.
3034

31-
See :doc:`virtual-package` for more information on the topic of working with HTTPlug implementations.
35+
Examples: :doc:`/clients/guzzle6-adapter` and :doc:`/clients/react-adapter`.
3236

33-
Installation in a reusable package
34-
----------------------------------
37+
.. note::
3538

36-
In many cases, packages are designed to be reused from the very beginning.
37-
For example, API clients are usually used in other packages/applications, not on their own.
39+
Ideally, all HTTP client libraries out there will implement the HTTPlug
40+
interfaces. At that point, our adapters will no longer be necessary.
3841

39-
Reusable packages should **not rely on a concrete implementation** (like Guzzle 6),
40-
but only require any implementation of HTTPlug. HTTPlug uses the concept of virtual packages.
41-
Instead of depending on only the interfaces, which would be missing an implementation,
42-
or depending on one concrete implementation, you should depend on the virtual package ``php-http/client-implementation``
43-
or ``php-http/async-client-implementation``. There is no package with that name,
44-
but all clients and adapters implementing HTTPlug declare that they provide one of this virtual package or both.
42+
Usage
43+
-----
4544

46-
You need to edit the ``composer.json`` of your package to add the virtual package.
47-
For development (installing the package standalone, running tests),
48-
add a concrete implementation in the ``require-dev`` section to make the project installable:
45+
There are two main use cases for HTTPlug:
4946

50-
.. code-block:: json
51-
52-
{
53-
"require": {
54-
"php-http/client-implementation": "^1.0"
55-
},
56-
"require-dev": {
57-
"php-http/guzzle6-adapter": "^1.0"
58-
},
59-
}
60-
61-
For extra convenience, you can use the :doc:`/discovery` system to free the user of your
62-
package from having to instantiate the client.
63-
You should however always accept injecting the client instance to allow the user to configure the client as needed.
64-
You can find an example in the :doc:`/discovery` documentation.
65-
66-
Users of your package will have to select a concrete adapter in their project to make your package installable.
67-
Best point them to the :doc:`virtual-package` page.
68-
69-
To be able to send requests, you should not depend on a specific PSR-7 implementation,
70-
but use the :ref:`message-factory` system.
71-
72-
Framework Integration
73-
^^^^^^^^^^^^^^^^^^^^^
74-
75-
HTTPlug can be used in any PHP based project.
76-
Nonetheless, we provide particular integration for some popular frameworks:
77-
78-
- HttplugBundle_: integration with the Symfony framework.
47+
* usage in an application that executes HTTP requests (see :doc:`application-developers`).
48+
* usage in a reusable package that executes HTTP requests (see :doc:`library-developers`).
7949

8050
History
8151
-------
8252

83-
This project has been started by `Eric Geloen`_ as `Ivory Http Adapter`_. It never made it to a stable release,
84-
but it relied on PSR-7 which was not stable either that time. Because of the constantly changing PSR-7,
85-
Eric had to rewrite the library over and over again (at least the message handling part,
86-
which in most cases affected every adapter as well).
53+
This project has been started by `Eric Geloen`_ as `Ivory Http Adapter`_. It
54+
never made it to a stable release, but it relied on PSR-7 which was not stable
55+
either that time. Because of the constantly changing PSR-7, Eric had to rewrite
56+
the library over and over again (at least the message handling part, which in
57+
most cases affected every adapter as well).
8758

88-
In 2015, a decision has been made to move the library to its own organization, so PHP HTTP was born.
59+
In 2015, a decision has been made to move the library to its own organization,
60+
so PHP-HTTP was born.
8961

90-
See :doc:`migrating` for a guide how to migrate your code from the Ivory adapter to HTTPlug.
62+
See :doc:`migrating` for a guide how to migrate your code from the Ivory
63+
adapter.
9164

92-
.. _implementation: https://packagist.org/providers/php-http/client-implementation
93-
.. _HttplugBundle: https://github.com/php-http/HttplugBundle
9465
.. _`Eric Geloen`: https://github.com/egeloen
95-
.. _`Ivory Http Adapter`: https://github.com/egeloen/ivory-http-adapter).
66+
.. _`Ivory Http Adapter`: https://github.com/egeloen/ivory-http-adapter

Diff for: ‎httplug/library-developers.rst

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
HTTPlug for library developers
2+
==============================
3+
4+
If you’re developing a library or framework that performs HTTP requests, you
5+
should not be dependent on concrete HTTP client libraries (such as Guzzle).
6+
Instead, you should only make sure that *some* HTTP client is available. It is
7+
then up to your users to decide which HTTP client they want to include in their
8+
projects.
9+
10+
Manage dependencies
11+
-------------------
12+
13+
To depend on *some* HTTP client, specify either
14+
``php-http/client-implementation`` or ``php-http/async-client-implementation``
15+
in your library’s ``composer.json``. These are virtual Composer packages that
16+
will throw an error if no concrete client was found:
17+
18+
.. code-block:: json
19+
20+
{
21+
"name": "you/and-your-awesome-library",
22+
"require": {
23+
"php-http/client-implementation": "^1.0"
24+
}
25+
}
26+
27+
Your users then include your project alongside with a HTTP client of their
28+
choosing in their project’s ``composer.json``. In this case, the user decided
29+
to include the Socket client:
30+
31+
.. code-block:: json
32+
33+
{
34+
"name": "some-user/nice-project",
35+
"require": {
36+
"you/and-your-awesome-library": "^1.2",
37+
"php-http/socket-client": "^1.0"
38+
}
39+
}
40+
41+
Standalone installation
42+
-----------------------
43+
44+
This is sufficient for your library’s users. For the library’s developers,
45+
however, it’s best if some specific client is installed when they run
46+
``composer install`` in the library’s directory. So specify any concrete client
47+
in the ``require-dev`` section in your library’s ``composer.json``. In this
48+
example, we chose the Guzzle 6 adapter:
49+
50+
.. code-block:: json
51+
52+
{
53+
"name": "you/and-your-awesome-library",
54+
"require": {
55+
"php-http/client-implementation": "^1.0"
56+
},
57+
"require-dev": {
58+
"php-http/guzzle6-adapter": "^1.0"
59+
}
60+
}
61+
62+
For extra convenience, you can use :doc:`/discovery` to free your users from
63+
having to instantiate the client.
64+
65+
Messages
66+
--------
67+
68+
When you construct HTTP message objects in your library, you should not depend
69+
on a concrete PSR-7 message implementation. Instead, use the
70+
:ref:`PHP-HTTP message factory <message-factory>`.
71+
72+
User documentation
73+
------------------
74+
75+
To explain to your users that they need to install a concrete HTTP client,
76+
you can point them to :doc:`users`.

Diff for: ‎httplug/tutorial.rst

-5
Original file line numberDiff line numberDiff line change
@@ -155,8 +155,3 @@ Handling errors
155155
---------------
156156

157157
TODO: explain how to handle exceptions, distinction between network exception and HttpException.
158-
159-
Writing a reusable package
160-
--------------------------
161-
162-
See :ref:`httplug-building-reusable-library`

Diff for: ‎httplug/usage.rst

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
HTTPlug usage
2+
=============
3+
4+
HTTPlug is relevant for three groups of users:
5+
6+
.. toctree::
7+
:maxdepth: 1
8+
9+
Library users <users>
10+
Application developers <application-developers>
11+
Library developers <library-developers>
12+

Diff for: ‎httplug/users.rst

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
HTTPlug for library users
2+
=========================
3+
4+
If you use a library that depends on HTTPlug (say, ``some/awesome-library``),
5+
you need to include an HTTPlug client in your project before you can include
6+
``awesome-library``.
7+
8+
From the list of :doc:`clients </clients>`, choose on that best fits your
9+
application, then include it in your project. For instance, if you decide to
10+
use the Socket client:
11+
12+
.. code-block:: bash
13+
14+
$ composer require php-http/socket-client
15+
16+
Instead of an HTTPlug client, you may want to use an adapter for your favorite
17+
HTTP client. If that turns out to be Guzzle:
18+
19+
.. code-block:: bash
20+
21+
$ composer require php-http/guzzle6-adapter
22+
23+
Then you can include the library:
24+
25+
.. code-block:: bash
26+
27+
$ composer require some/awesome-library
28+
29+
Troubleshooting
30+
---------------
31+
32+
If you try to include the HTTPlug-dependent library before you have included a
33+
HTTP client in your project, Composer will throw an error:
34+
35+
.. code-block:: none
36+
37+
Loading composer repositories with package information
38+
Updating dependencies (including require-dev)
39+
Your requirements could not be resolved to an installable set of packages.
40+
41+
Problem 1
42+
- The requested package php-http/client-implementation could not be found in any version,
43+
there may be a typo in the package name.
44+
45+
You can solve this by including a HTTP client or adapter, as described above.
46+
47+
Background
48+
----------
49+
50+
Reusable libraries do not depend on a concrete implementation but only on the virtual package
51+
``php-http/client-implementation``. This is to avoid hard coupling and allows the user of the
52+
library to choose the implementation. You can think of this as an "interface" or "contract" for packages.
53+
54+
When *using a reusable library* in an application, one must ``require`` a concrete implementation.
55+
Make sure the ``require`` section includes a package that provides ``php-http/client-implementation``.
56+
Failing to do that will lead to composer reporting this error:

0 commit comments

Comments
 (0)