Skip to content

Commit 3c7d703

Browse files
authored
Merge pull request #105 from php-http/discovery_puli_optional
Update discovery documentation
2 parents 6114d45 + f725525 commit 3c7d703

File tree

1 file changed

+50
-25
lines changed

1 file changed

+50
-25
lines changed

discovery.rst

+50-25
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,6 @@ Discovery
33

44
The discovery service allows to find and use installed resources.
55

6-
Under the hood it uses `Puli`_ for the discovery logic. All of our packages provide Puli resources.
7-
Discovery is simply a convenience wrapper to statically access clients and factories for when
8-
Dependency Injection is not an option. Discovery is useful in libraries that want to offer
9-
zero-configuration services relying on the virtual packages. If you have Dependency Injection available,
10-
using Puli directly is more elegant (see for example the Symfony HttplugBundle).
11-
126
Consumers of libraries using discovery still need to make sure they install one of the implementations.
137
Discovery can only find installed code, not fetch code from other sources.
148

@@ -22,36 +16,67 @@ Currently available discovery services:
2216

2317
The principle is always the same: you call the static ``find`` method on the discovery service if no explicit
2418
implementation was specified. The discovery service will try to locate a suitable implementation.
25-
If no implementation is found, an ``Http\Discovery\NotFoundException`` is thrown.
19+
If no implementation is found, an ``Http\Discovery\Exception\NotFoundException`` is thrown.
2620

27-
Installation
28-
------------
21+
.. versionadded:: 0.9
22+
The exception ``Http\Discovery\NotFoundException`` has been moved to ``Http\Discovery\Exception\NotFoundException``.
2923

30-
There are two kinds of installation:
24+
Discovery is simply a convenience wrapper to statically access clients and factories for when
25+
Dependency Injection is not an option. Discovery is useful in libraries that want to offer
26+
zero-configuration services relying on the virtual packages.
3127

32-
- In a reusable library
33-
- In an application
3428

35-
In both cases you have to install the discovery package itself:
29+
Strategies
30+
----------
31+
32+
The package supports multiple discovery strategies and comes with two out-of-the-box:
33+
34+
- A built-in strategy supporting the HTTPlug adapters, clients and factories (including Guzzle and Diactoros)
35+
- A strategy supporting the beta version of `Puli`_
36+
37+
Strategies provide candidates of a type which gets evaluated by the discovery service.
38+
When it finds the best candidate, it caches it and stops looking in further strategies.
39+
40+
41+
Installation
42+
------------
3643

3744
.. code-block:: bash
3845
3946
$ composer require php-http/discovery
4047
41-
As mentioned above, discovery relies on Puli. In order to use discovery, you need to also set up Puli.
42-
The easiest way is installing the composer-plugin which automatically configures all the composer packages to act as
43-
Puli modules. For applications, simply do:
48+
49+
Using Puli
50+
^^^^^^^^^^
51+
52+
`Puli`_ is a first class citizen, but completely optional strategy in discovery.
53+
It provides better flexibility than the built-in strategy, but requires more configuration.
54+
55+
There are two kinds of installation:
56+
57+
- In an application
58+
- In a reusable library (for development)
59+
60+
In both cases you have to install the discovery package itself and set up Puli.
61+
The easiest way is installing the composer-plugin which automatically configures
62+
all the composer packages to act as Puli modules.
63+
64+
For applications, simply do:
4465

4566
.. code-block:: bash
4667
47-
$ composer require puli/composer-plugin
68+
$ composer require puli/composer-plugin
69+
4870
49-
If you need the composer-plugin for testing in a reusable library, make it a development dependency instead:
71+
If you need the composer-plugin for development or testing in a reusable library,
72+
make it a development dependency instead:
5073

5174
.. code-block:: bash
5275
53-
$ composer require --dev puli/composer-plugin
76+
$ composer require --dev puli/composer-plugin
5477
78+
All of our packages provide Puli resources too, so if Puli is installed, discovery will use it as the primary strategy
79+
and fall back to the built-in list.
5580

5681
Read more about setting up Puli in their `official documentation`_.
5782

@@ -62,8 +87,8 @@ Common Errors
6287
Puli Factory is not available
6388
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6489

65-
If you get an error that says "*Puli Factory is not available*", it means that you have failed to install Puli. You should
66-
make sure you install the latest version of ``puli/composer-plugin``.
90+
If you get an error that says "*Puli Factory is not available*", it means that you have failed to install Puli.
91+
You should make sure you install the latest version of ``puli/composer-plugin``.
6792

6893
No factories found
6994
^^^^^^^^^^^^^^^^^^
@@ -174,11 +199,11 @@ This type of discovery finds a URI factory for a PSR-7_ URI implementation::
174199
}
175200
}
176201

177-
Integrating your own implementation with the discovery mechanism
178-
----------------------------------------------------------------
202+
Integrating your own implementation with the discovery mechanism using Puli
203+
---------------------------------------------------------------------------
179204

180-
When you are working on an HTTP Client or Message Factory, you can easily make your class discoverable:
181-
you have to configure it as a Puli resource (`binding`_ in Puli terminology).
205+
If you use `Puli`_ you can easily make your own HTTP Client or Message Factory discoverable:
206+
you have to configure it as a Puli resource (`binding`_ in Puli terminology).
182207

183208
A binding must have a type, called `binding-type`_. All of our interfaces are registered as binding types.
184209

0 commit comments

Comments
 (0)