From f72552512c774797ef79828cfd786cf8b2ec508c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Sat, 25 Jun 2016 13:45:27 +0300 Subject: [PATCH] Update discovery documentation --- discovery.rst | 75 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 50 insertions(+), 25 deletions(-) diff --git a/discovery.rst b/discovery.rst index ef408fb..faea515 100644 --- a/discovery.rst +++ b/discovery.rst @@ -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) + +In both cases you have to install the discovery package itself and 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: .. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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.