Skip to content

Commit b4a7cf3

Browse files
ddeboerddeboer
committed
Restructure usage chapters
1 parent 95fed70 commit b4a7cf3

File tree

9 files changed

+172
-120
lines changed

9 files changed

+172
-120
lines changed

‎clients.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,14 @@ Client adapters:
2323
clients/guzzle5-adapter
2424
clients/guzzle6-adapter
2525
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+

‎httplug/application-developers.rst‎

Lines changed: 11 additions & 0 deletions
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+

‎httplug/introduction.rst‎

Lines changed: 5 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -39,51 +39,13 @@ PHP-HTTP offers two types of clients that implement the above interfaces:
3939
Ideally, all HTTP client libraries out there will implement the HTTPlug
4040
interfaces. At that point, our adapters will no longer be necessary.
4141

42-
Usage in an application
43-
-----------------------
42+
Usage
43+
-----
4444

45-
When writing an application, you need to require a concrete implementation.
45+
There are two main use cases for HTTPlug:
4646

47-
See :doc:`virtual-package` for more information on the topic of working with HTTPlug implementations.
48-
49-
Installation in a reusable package
50-
----------------------------------
51-
52-
In many cases, packages are designed to be reused from the very beginning.
53-
For example, API clients are usually used in other packages/applications, not on their own.
54-
55-
Reusable packages should **not rely on a concrete implementation** (like Guzzle 6),
56-
but only require any implementation of HTTPlug. HTTPlug uses the concept of virtual packages.
57-
Instead of depending on only the interfaces, which would be missing an implementation,
58-
or depending on one concrete implementation, you should depend on the virtual package ``php-http/client-implementation``
59-
or ``php-http/async-client-implementation``. There is no package with that name,
60-
but all clients and adapters implementing HTTPlug declare that they provide one of this virtual package or both.
61-
62-
You need to edit the ``composer.json`` of your package to add the virtual package.
63-
For development (installing the package standalone, running tests),
64-
add a concrete implementation in the ``require-dev`` section to make the project installable:
65-
66-
.. code-block:: json
67-
68-
{
69-
"require": {
70-
"php-http/client-implementation": "^1.0"
71-
},
72-
"require-dev": {
73-
"php-http/guzzle6-adapter": "^1.0"
74-
},
75-
}
76-
77-
For extra convenience, you can use the :doc:`/discovery` system to free the user of your
78-
package from having to instantiate the client.
79-
You should however always accept injecting the client instance to allow the user to configure the client as needed.
80-
You can find an example in the :doc:`/discovery` documentation.
81-
82-
Users of your package will have to select a concrete adapter in their project to make your package installable.
83-
Best point them to the :doc:`virtual-package` page.
84-
85-
To be able to send requests, you should not depend on a specific PSR-7 implementation,
86-
but use the :ref:`message-factory` system.
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`).
8749

8850
History
8951
-------

‎httplug/library-developers.rst‎

Lines changed: 76 additions & 0 deletions
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`.

‎httplug/tutorial.rst‎

Lines changed: 0 additions & 5 deletions
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`

‎httplug/usage.rst‎

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,12 @@
1-
Usage
2-
=====
1+
HTTPlug usage
2+
=============
33

4-
HTTPlug is an abstraction for HTTP clients. There are two main use cases:
4+
HTTPlug is relevant for three groups of users:
55

6-
1. Usage in a project/application
7-
2. Usage in a reusable package
6+
.. toctree::
7+
:maxdepth: 1
88

9-
10-
Framework Integration
11-
^^^^^^^^^^^^^^^^^^^^^
12-
13-
HTTPlug can be used in any PHP based project.
14-
Nonetheless, we provide particular integration for some popular frameworks:
15-
16-
- HttplugBundle_: integration with the Symfony framework.
9+
Library users <users>
10+
Application developers <application-developers>
11+
Library developers <library-developers>
1712

‎httplug/users.rst‎

Lines changed: 56 additions & 0 deletions
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:

‎httplug/virtual-package.rst‎

Lines changed: 0 additions & 56 deletions
This file was deleted.

‎index.rst‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,9 @@ PHP-HTTP has three goals:
1919

2020
2. Provide good quality HTTP-related packages to the PHP community.
2121

22-
3. Over time, make HTTPlug a PSR so that clients will directly implement the
23-
HTTPlug interface and our adapters are no longer needed.
22+
3. Over time, make HTTPlug a PHP Standards Recommendation (PSR) so that clients
23+
will directly implement the HTTPlug interface and our adapters are no longer
24+
needed.
2425

2526
HTTPlug
2627
-------
@@ -46,6 +47,8 @@ PHP-HTTP offers several packages:
4647
| Plugins | Implementation-independent authentication, cookies and more | ``Http\Plugin\[Name]`` |
4748
+-----------------+-------------------------------------------------------------+------------------------+
4849

50+
Read more about :doc:`clients and adapters <clients>` and :doc:`plugins <plugins/index>`.
51+
4952
The future
5053
----------
5154

@@ -66,7 +69,6 @@ for discussion around a future HTTP client PSR.
6669
Usage <httplug/usage>
6770
Tutorial <httplug/tutorial>
6871
Migrating <httplug/migrating>
69-
Virtual package <httplug/virtual-package>
7072

7173
clients
7274
plugins/index

0 commit comments

Comments
 (0)