From edf08beee4f7d0307e483cb6933d99576744b2d1 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Mon, 21 Jan 2019 17:57:39 +0100 Subject: [PATCH 1/3] Added docs about PSR-17 and PSR-18 --- discovery.rst | 59 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 55 insertions(+), 4 deletions(-) diff --git a/discovery.rst b/discovery.rst index 5fd2692..d9ace89 100644 --- a/discovery.rst +++ b/discovery.rst @@ -13,6 +13,8 @@ Currently available discovery services: - PSR-7 Message Factory Discovery - PSR-7 URI Factory Discovery - PSR-7 Stream Factory Discovery +- PSR-17 Factory Discovery +- PSR-18 Client Discovery - Mock Client Discovery (not enabled by default) The principle is always the same: you call the static ``find`` method on the discovery service if no explicit @@ -150,7 +152,7 @@ This type of discovery finds an HTTP Client implementation:: /** * @var HttpClient */ - protected $httpClient; + private $httpClient; /** * @param HttpClient|null $httpClient Client to do HTTP requests, if not set, auto discovery will be used to find a HTTP client. @@ -174,7 +176,7 @@ This type of discovery finds a HTTP asynchronous Client implementation:: /** * @var HttpAsyncClient */ - protected $httpAsyncClient; + private $httpAsyncClient; /** * @param HttpAsyncClient|null $httpAsyncClient Client to do HTTP requests, if not set, auto discovery will be used to find an asynchronous client. @@ -199,7 +201,7 @@ implementation:: /** * @var MessageFactory */ - protected $messageFactory; + private $messageFactory; /** * @param MessageFactory|null $messageFactory to create PSR-7 requests. @@ -223,7 +225,7 @@ This type of discovery finds a URI factory for a PSR-7_ URI implementation:: /** * @var UriFactory */ - protected $uriFactory; + private $uriFactory; /** * @param UriFactory|null $uriFactory to create UriInterface instances from strings. @@ -233,6 +235,55 @@ This type of discovery finds a URI factory for a PSR-7_ URI implementation:: $this->uriFactory = $uriFactory ?: UriFactoryDiscovery::find(); } } + +PSR-17 Factory Discovery +------------------------ + +This type of discovery finds a factory for a PSR-17_ implementation:: + + use Psr\Http\Message\RequestFactoryInterface; + use Psr\Http\Message\ResponseFactoryInterface; + use Http\Discovery\Psr17FactoryDiscovery; + + class MyClass + { + /** + * @var RequestFactoryInterface + */ + private $requestFactory; + + /** + * @var ResponseFactoryInterface + */ + private $responseFactory; + + public function __construct(RequestFactoryInterface $requestFactory = null, ResponseFactoryInterface $responseFactory = null) + { + $this->requestFactory = $requestFactory ?: Psr17FactoryDiscovery::findRequestFactory(); + $this->responseFactory = $responseFactory ?: Psr17FactoryDiscovery::findResponseFactory(); + } + } + +PSR-18 Client Discovery +----------------------- + +This type of discovery finds a PSR-18 HTTP Client implementation:: + + use Psr\Http\Client\ClientInterface; + use Http\Discovery\Psr18ClientDiscovery; + + class MyClass + { + /** + * @var ClientInterface + */ + private $httpClient; + + public function __construct(ClientInterface $httpClient = null) + { + $this->httpClient = $httpClient ?: Psr18ClientDiscovery::find(); + } + } Mock Client Discovery --------------------------- From 0d520e8de94688355debe470237da26c349830fb Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Mon, 21 Jan 2019 18:34:16 +0100 Subject: [PATCH 2/3] Fixed broken links --- discovery.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/discovery.rst b/discovery.rst index d9ace89..8371d18 100644 --- a/discovery.rst +++ b/discovery.rst @@ -267,7 +267,7 @@ This type of discovery finds a factory for a PSR-17_ implementation:: PSR-18 Client Discovery ----------------------- -This type of discovery finds a PSR-18 HTTP Client implementation:: +This type of discovery finds a PSR-18_ HTTP Client implementation:: use Psr\Http\Client\ClientInterface; use Http\Discovery\Psr18ClientDiscovery; @@ -352,3 +352,5 @@ Read more in Puli's documentation (`Providing Resources`_). .. _`binding`: http://docs.puli.io/en/latest/glossary.html#glossary-binding .. _`binding-type`: http://docs.puli.io/en/latest/glossary.html#glossary-binding-type .. _Providing Resources: http://docs.puli.io/en/latest/discovery/providing-resources.html +.. _PSR-17: http://www.php-fig.org/psr/psr-17 +.. _PSR-18: http://www.php-fig.org/psr/psr-18 From 9da775d47a65efd5cfd4f4d44bee00971b5f2f47 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Wed, 23 Jan 2019 09:41:12 +0100 Subject: [PATCH 3/3] Added deprecation notice --- discovery.rst | 110 ++++++++++++++++++++++++++------------------------ 1 file changed, 58 insertions(+), 52 deletions(-) diff --git a/discovery.rst b/discovery.rst index 8371d18..c901f31 100644 --- a/discovery.rst +++ b/discovery.rst @@ -10,12 +10,12 @@ Currently available discovery services: - HTTP Client Discovery - HTTP Async Client Discovery -- PSR-7 Message Factory Discovery -- PSR-7 URI Factory Discovery -- PSR-7 Stream Factory Discovery - PSR-17 Factory Discovery -- PSR-18 Client Discovery +- PSR-18 HTTP Client Discovery - Mock Client Discovery (not enabled by default) +- PSR-7 Message Factory Discovery (deprecated) +- PSR-7 URI Factory Discovery (deprecated) +- PSR-7 Stream Factory Discovery (deprecated) 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. @@ -187,101 +187,107 @@ This type of discovery finds a HTTP asynchronous Client implementation:: } } -PSR-7 Message Factory Discovery -------------------------------- +PSR-17 Factory Discovery +------------------------ -This type of discovery finds a :ref:`message-factory` for a PSR-7_ Message -implementation:: +This type of discovery finds a factory for a PSR-17_ implementation:: - use Http\Message\MessageFactory; - use Http\Discovery\MessageFactoryDiscovery; + use Psr\Http\Message\RequestFactoryInterface; + use Psr\Http\Message\ResponseFactoryInterface; + use Http\Discovery\Psr17FactoryDiscovery; class MyClass { /** - * @var MessageFactory + * @var RequestFactoryInterface */ - private $messageFactory; + private $requestFactory; /** - * @param MessageFactory|null $messageFactory to create PSR-7 requests. + * @var ResponseFactoryInterface */ - public function __construct(MessageFactory $messageFactory = null) + private $responseFactory; + + public function __construct(RequestFactoryInterface $requestFactory = null, ResponseFactoryInterface $responseFactory = null) { - $this->messageFactory = $messageFactory ?: MessageFactoryDiscovery::find(); + $this->requestFactory = $requestFactory ?: Psr17FactoryDiscovery::findRequestFactory(); + $this->responseFactory = $responseFactory ?: Psr17FactoryDiscovery::findResponseFactory(); } } -PSR-7 URI Factory Discovery ---------------------------- +PSR-18 Client Discovery +----------------------- -This type of discovery finds a URI factory for a PSR-7_ URI implementation:: +This type of discovery finds a PSR-18_ HTTP Client implementation:: - use Http\Message\UriFactory; - use Http\Discovery\UriFactoryDiscovery; + use Psr\Http\Client\ClientInterface; + use Http\Discovery\Psr18ClientDiscovery; class MyClass { /** - * @var UriFactory + * @var ClientInterface */ - private $uriFactory; + private $httpClient; - /** - * @param UriFactory|null $uriFactory to create UriInterface instances from strings. - */ - public function __construct(UriFactory $uriFactory = null) + public function __construct(ClientInterface $httpClient = null) { - $this->uriFactory = $uriFactory ?: UriFactoryDiscovery::find(); + $this->httpClient = $httpClient ?: Psr18ClientDiscovery::find(); } } - -PSR-17 Factory Discovery ------------------------- -This type of discovery finds a factory for a PSR-17_ implementation:: +PSR-7 Message Factory Discovery +------------------------------- - use Psr\Http\Message\RequestFactoryInterface; - use Psr\Http\Message\ResponseFactoryInterface; - use Http\Discovery\Psr17FactoryDiscovery; +.. versionadded:: 1.6 + This is deprecated and will be removed in 2.0. Consider using PSR-17 Factory Discovery. + +This type of discovery finds a :ref:`message-factory` for a PSR-7_ Message +implementation:: + + use Http\Message\MessageFactory; + use Http\Discovery\MessageFactoryDiscovery; class MyClass { /** - * @var RequestFactoryInterface + * @var MessageFactory */ - private $requestFactory; - + private $messageFactory; + /** - * @var ResponseFactoryInterface + * @param MessageFactory|null $messageFactory to create PSR-7 requests. */ - private $responseFactory; - - public function __construct(RequestFactoryInterface $requestFactory = null, ResponseFactoryInterface $responseFactory = null) + public function __construct(MessageFactory $messageFactory = null) { - $this->requestFactory = $requestFactory ?: Psr17FactoryDiscovery::findRequestFactory(); - $this->responseFactory = $responseFactory ?: Psr17FactoryDiscovery::findResponseFactory(); + $this->messageFactory = $messageFactory ?: MessageFactoryDiscovery::find(); } } -PSR-18 Client Discovery ------------------------ +PSR-7 URI Factory Discovery +--------------------------- -This type of discovery finds a PSR-18_ HTTP Client implementation:: +.. versionadded:: 1.6 + This is deprecated and will be removed in 2.0. Consider using PSR-17 Factory Discovery. - use Psr\Http\Client\ClientInterface; - use Http\Discovery\Psr18ClientDiscovery; +This type of discovery finds a URI factory for a PSR-7_ URI implementation:: + + use Http\Message\UriFactory; + use Http\Discovery\UriFactoryDiscovery; class MyClass { /** - * @var ClientInterface + * @var UriFactory */ - private $httpClient; + private $uriFactory; - public function __construct(ClientInterface $httpClient = null) + /** + * @param UriFactory|null $uriFactory to create UriInterface instances from strings. + */ + public function __construct(UriFactory $uriFactory = null) { - $this->httpClient = $httpClient ?: Psr18ClientDiscovery::find(); + $this->uriFactory = $uriFactory ?: UriFactoryDiscovery::find(); } }