Repository files navigation

Lightweight library that discovers availablePSR-17 HTTP Factory implementations by searching for a list of well-known classes that implement the relevant interface, and returns an instance of the first one that is found.

This package is part of thePSR Discovery utility suite, which also supportsPSR-18 HTTP Clients,PSR-14 Event Dispatchers,PSR-11 Containers,PSR-6 Caches andPSR-3 Logs.

This is largely intended for inclusion in libraries like SDKs that wish to support PSR-17 Factories without requiring hard dependencies on specific implementations or demanding extra configuration by users.

• Requirements
• Implementations
• Installation
• Usage
• Handling Failures
• Exceptions
• Singletons
• Mocking Priority
• Preferring an Implementation
• Using a Specific Implementation

• PHP 8.2+
• Composer 2.0+

Successful discovery requires the presence of a compatible implementation in the host application. This library does not install any implementations for you.

The followingpsr/http-factory-implementation implementations are discovered and instantiated automatically:

• guzzlehttp/psr7 ^2.0
• http-interop/http-factory-guzzle ^0.2 | ^1.0
• httpsoft/http-message ^1.0.4
• laminas/laminas-diactoros ^2.0
• nimbly/capsule ^2.0
• nyholm/psr7 ^0.2.2 | ^1.0
• slim/psr7 ^1.0
• tuupola/http-factory ^1.0.2
• typo3/core ^10.1 | ^11.0 | ^12.0
• zendframework/zend-diactoros ^2.0

The following mock implementations are also available:

• psr-mock/http-factory-implementation ^1.0

Ifa particular implementation is missing that you'd like to see, please open a pull request adding support.

composer require --dev psr-discovery/http-factory-implementations

usePsrDiscovery\Discover;// Returns a PSR-17 RequestFactoryInterface instance$requestFactory = Discover::httpRequestFactory();// Returns a PSR-17 ResponseFactoryInterface instance$responseFactory = Discover::httpResponseFactory();// Returns a PSR-17 StreamFactoryInterface instance$streamFactory = Discover::httpStreamFactory();// Returns a PSR-17 UploadedFileFactoryInterface instance$uploadedFileFactory = Discover::httpUploadedFileFactory();// Returns a PSR-17 UriFactoryInterface instance$uriFactory = Discover::httpUriFactory();// Returns a PSR-7 RequestInterface instance$request =$requestFactory->createRequest('GET','https://example.com');

If the library is unable to discover a suitable PSR-17 implementation, theDiscover::httpRequestFactory(),Discover::httpResponseFactory() orDiscover::httpStreamFactory() discovery methods will simply returnnull. This allows you to handle the failure gracefully, for example by falling back to a default implementation.

Example:

usePsrDiscovery\Discover;$requestFactory = Discover::httpRequestFactory();if ($requestFactory ===null) {// No suitable HTTP RequestFactory implementation was discovered.// Fall back to a default implementation.$requestFactory =newDefaultRequestFactory();}

By default, theDiscover::httpRequestFactory(),Discover::httpResponseFactory() orDiscover::httpStreamFactory() methods will always return a new instance of the discovered implementation. If you wish to use a singleton instance instead, simply passtrue to the$singleton parameter of the discovery method.

Example:

usePsrDiscovery\Discover;// $httpResponseFactory1 !== $httpResponseFactory2 (default)$httpResponseFactory1 = Discover::httpResponseFactory();$httpResponseFactory2 = Discover::httpResponseFactory();// $httpResponseFactory1 === $httpResponseFactory2$httpResponseFactory1 = Discover::httpResponseFactory(singleton:true);$httpResponseFactory2 = Discover::httpResponseFactory(singleton:true);

This library will give priority to searching for a known, available mocking library before searching for a real implementation. This is to allow for easier testing of code that uses this library.

The expectation is that these mocking libraries will always be installed as development dependencies, and therefore if they are available, they are intended to be used.

If you wish to prefer a specific implementation over others, you canprefer() it by package name:

usePsrDiscovery\Discover;usePsrDiscovery\Implementations\Psr17\RequestFactories;// Prefer the a specific implementation of PSR-17 over others.RequestFactories::prefer('nyholm/psr7');// Return an instance of Nyholm\Psr7\Factory\Psr17Factory,// or the next available from the list of candidates,// Returns null if none are discovered.$factory = Discover::httpRequestFactory();

In this case, this will cause thehttpRequestFactory() method to return the preferred implementation if it is available, otherwise, it will fall back to the default behavior. The same applies tohttpResponseFactory() andhttpStreamFactory() when their relevant classes are configured similarly.

Note that assigning a preferred implementation will give it priority over the default preference of mocking libraries.

If you wish to force a specific implementation and ignore the rest of the discovery candidates, you canuse() its package name:

usePsrDiscovery\Discover;usePsrDiscovery\Implementations\Psr17\ResponseFactories;// Only discover a specific implementation of PSR-17.ResponseFactories::use('nyholm/psr7');// Return an instance of Nyholm\Psr7\Factory\Psr17Factory,// or null if it is not available.$factory = Discover::httpResponseFactory();

In this case, this will cause thehttpResponseFactory() method to return the preferred implementation if it is available, otherwise, it will returnnull. The same applies tohttpRequestFactory() andhttpStreamFactory() when their relevant classes are configured similarly.

This library is not produced or endorsed by, or otherwise affiliated with, the PHP-FIG.