-
Notifications
You must be signed in to change notification settings - Fork 56
Update discovery documentation #105
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,12 +3,6 @@ Discovery | |
|
||
The discovery service allows to find and use installed resources. | ||
|
||
Under the hood it uses `Puli`_ for the discovery logic. All of our packages provide Puli resources. | ||
Discovery is simply a convenience wrapper to statically access clients and factories for when | ||
Dependency Injection is not an option. Discovery is useful in libraries that want to offer | ||
zero-configuration services relying on the virtual packages. If you have Dependency Injection available, | ||
using Puli directly is more elegant (see for example the Symfony HttplugBundle). | ||
|
||
Consumers of libraries using discovery still need to make sure they install one of the implementations. | ||
Discovery can only find installed code, not fetch code from other sources. | ||
|
||
|
@@ -22,36 +16,67 @@ Currently available discovery services: | |
|
||
The principle is always the same: you call the static ``find`` method on the discovery service if no explicit | ||
implementation was specified. The discovery service will try to locate a suitable implementation. | ||
If no implementation is found, an ``Http\Discovery\NotFoundException`` is thrown. | ||
If no implementation is found, an ``Http\Discovery\Exception\NotFoundException`` is thrown. | ||
|
||
Installation | ||
------------ | ||
.. versionadded:: 0.9 | ||
The exception ``Http\Discovery\NotFoundException`` has been moved to ``Http\Discovery\Exception\NotFoundException``. | ||
|
||
There are two kinds of installation: | ||
Discovery is simply a convenience wrapper to statically access clients and factories for when | ||
Dependency Injection is not an option. Discovery is useful in libraries that want to offer | ||
zero-configuration services relying on the virtual packages. | ||
|
||
- In a reusable library | ||
- In an application | ||
|
||
In both cases you have to install the discovery package itself: | ||
Strategies | ||
---------- | ||
|
||
The package supports multiple discovery strategies and comes with two out-of-the-box: | ||
|
||
- A built-in strategy supporting the HTTPlug adapters, clients and factories (including Guzzle and Diactoros) | ||
- A strategy supporting the beta version of `Puli`_ | ||
|
||
Strategies provide candidates of a type which gets evaluated by the discovery service. | ||
When it finds the best candidate, it caches it and stops looking in further strategies. | ||
|
||
|
||
Installation | ||
------------ | ||
|
||
.. code-block:: bash | ||
|
||
$ composer require php-http/discovery | ||
|
||
As mentioned above, discovery relies on Puli. In order to use discovery, you need to also set up Puli. | ||
The easiest way is installing the composer-plugin which automatically configures all the composer packages to act as | ||
Puli modules. For applications, simply do: | ||
|
||
Using Puli | ||
^^^^^^^^^^ | ||
|
||
`Puli`_ is a first class citizen, but completely optional strategy in discovery. | ||
It provides better flexibility than the built-in strategy, but requires more configuration. | ||
|
||
There are two kinds of installation: | ||
|
||
- In an application | ||
- In a reusable library (for development) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I made it clear that it applies for development. Is it okay? |
||
|
||
In both cases you have to install the discovery package itself and set up Puli. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. should a reusable library ever care about puli now? i guess not - except if it wants if for ci testing, but that feels like quite an edge case. the library can depend on discovery alone now. only when using the library with discovery and wanting puli should you have to care about it. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. No, A resusable package should never care about the strategies. They may be replaced by an application user anyway. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I disagree. Puli might be installed for development. For example when you want to install a client for testing which can be discovered with Puli. |
||
The easiest way is installing the composer-plugin which automatically configures | ||
all the composer packages to act as Puli modules. | ||
|
||
For applications, simply do: | ||
|
||
.. code-block:: bash | ||
|
||
$ composer require puli/composer-plugin | ||
$ composer require puli/composer-plugin | ||
|
||
|
||
If you need the composer-plugin for testing in a reusable library, make it a development dependency instead: | ||
If you need the composer-plugin for development or testing in a reusable library, | ||
make it a development dependency instead: | ||
|
||
.. code-block:: bash | ||
|
||
$ composer require --dev puli/composer-plugin | ||
$ composer require --dev puli/composer-plugin | ||
|
||
All of our packages provide Puli resources too, so if Puli is installed, discovery will use it as the primary strategy | ||
and fall back to the built-in list. | ||
|
||
Read more about setting up Puli in their `official documentation`_. | ||
|
||
|
@@ -62,8 +87,8 @@ Common Errors | |
Puli Factory is not available | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is this still a thing @Nyholm? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes. But only as "previous exception" See comment: php-http/discovery#59 (comment) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hm, should we reflect that in the docs? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think it is good as it is. But we should add docs about the "DiscoveryFailedException" and maybe rewrite the "NotFoundException" a bit. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would like to get this merged ASAP. I created #116 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Good! |
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
||
If you get an error that says "*Puli Factory is not available*", it means that you have failed to install Puli. You should | ||
make sure you install the latest version of ``puli/composer-plugin``. | ||
If you get an error that says "*Puli Factory is not available*", it means that you have failed to install Puli. | ||
You should make sure you install the latest version of ``puli/composer-plugin``. | ||
|
||
No factories found | ||
^^^^^^^^^^^^^^^^^^ | ||
|
@@ -174,11 +199,11 @@ This type of discovery finds a URI factory for a PSR-7_ URI implementation:: | |
} | ||
} | ||
|
||
Integrating your own implementation with the discovery mechanism | ||
---------------------------------------------------------------- | ||
Integrating your own implementation with the discovery mechanism using Puli | ||
--------------------------------------------------------------------------- | ||
|
||
When you are working on an HTTP Client or Message Factory, you can easily make your class discoverable: | ||
you have to configure it as a Puli resource (`binding`_ in Puli terminology). | ||
If you use `Puli`_ you can easily make your own HTTP Client or Message Factory discoverable: | ||
you have to configure it as a Puli resource (`binding`_ in Puli terminology). | ||
|
||
A binding must have a type, called `binding-type`_. All of our interfaces are registered as binding types. | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we should start by repeating that using puli is optional and you only need this if you want to use clients not handled by the built-in discovery.