From 51ea34514d25dcecec246c438a329137ea7b4b4e Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Fri, 20 Jan 2023 17:32:11 +0100 Subject: [PATCH] Add doc for auto-installation of missing implementations by Discovery --- discovery.rst | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/discovery.rst b/discovery.rst index 878311f..9a36986 100644 --- a/discovery.rst +++ b/discovery.rst @@ -1,10 +1,7 @@ Discovery ========= -The discovery service allows to find and use installed resources. - -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. +The discovery service allows to find installed resources and install missing ones. Currently available discovery services: @@ -28,6 +25,30 @@ Discovery is simply a convenience wrapper to statically access clients and facto Dependency Injection is not an option. Discovery is useful in libraries that want to offer zero-configuration services relying on the virtual packages. +Auto-installation +----------------- + +.. versionadded:: 1.15 + Auto-installation of missing dependencies is available since v1.15. + +Discovery embeds a composer plugin that can auto-install missing implementations +when an application does not specify any specific implementation. + +If a library requires both ``php-http/discovery`` and one of the supported virtual packages +(see :doc:`library-developers`), but no implementation for the virtual package is already +installed, the plugin will auto-install the best matching known implementation. + +For example, if one is using ``react/event-loop``, the plugin will select ``php-http/react-adapter`` +to meet a missing dependency on ``php-http/client-implementation``. + +The following abstractions are currently supported: + +- ``php-http/async-client-implementation`` +- ``php-http/client-implementation`` +- ``psr/http-client-implementation`` +- ``psr/http-factory-implementation`` +- ``psr/http-message-implementation`` + .. _discovery-strategies: Strategies