@@ -3,12 +3,6 @@ Discovery
3
3
4
4
The discovery service allows to find and use installed resources.
5
5
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
-
12
6
Consumers of libraries using discovery still need to make sure they install one of the implementations.
13
7
Discovery can only find installed code, not fetch code from other sources.
14
8
@@ -22,36 +16,67 @@ Currently available discovery services:
22
16
23
17
The principle is always the same: you call the static ``find `` method on the discovery service if no explicit
24
18
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.
26
20
27
- Installation
28
- ------------
21
+ .. versionadded :: 0.9
22
+ The exception `` Http\Discovery\NotFoundException `` has been moved to `` Http\Discovery\Exception\NotFoundException ``.
29
23
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.
31
27
32
- - In a reusable library
33
- - In an application
34
28
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
+ ------------
36
43
37
44
.. code-block :: bash
38
45
39
46
$ composer require php-http/discovery
40
47
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:
44
65
45
66
.. code-block :: bash
46
67
47
- $ composer require puli/composer-plugin
68
+ $ composer require puli/composer-plugin
69
+
48
70
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:
50
73
51
74
.. code-block :: bash
52
75
53
- $ composer require --dev puli/composer-plugin
76
+ $ composer require --dev puli/composer-plugin
54
77
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.
55
80
56
81
Read more about setting up Puli in their `official documentation `_.
57
82
@@ -62,8 +87,8 @@ Common Errors
62
87
Puli Factory is not available
63
88
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
64
89
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 ``.
67
92
68
93
No factories found
69
94
^^^^^^^^^^^^^^^^^^
@@ -174,11 +199,11 @@ This type of discovery finds a URI factory for a PSR-7_ URI implementation::
174
199
}
175
200
}
176
201
177
- Integrating your own implementation with the discovery mechanism
178
- ----------------------------------------------------------------
202
+ Integrating your own implementation with the discovery mechanism using Puli
203
+ ---------------------------------------------------------------------------
179
204
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).
182
207
183
208
A binding must have a type, called `binding-type `_. All of our interfaces are registered as binding types.
184
209
0 commit comments