Skip to content
@psr-discovery

PSR Discovery

Automagically find and use installed PSR implementations. No configuration necessary; it Just Works™

Lightweight library that discovers available PSR implementations by searching for a list of well-known classes that implement the relevant interfaces, and returning an instance of the first one that is found.

The library currently supports PSR-18 HTTP Clients, PSR-17 HTTP Factories, PSR-14 Event Dispatchers, PSR-11 Containers, PSR-6 Caches and PSR-3 Logs.

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

Requirements

  • PHP 8.1+
  • Composer 2.0+

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

Installation

You should install the appropriate dependencies from the list below for the PSRs you wish to have discovery support for.

Meta-Packages

The psr-discovery/all meta-package includes all of the discovery suite packages. If you're looking for an all-in-one solution, this is the one you want.

Installation:

composer require psr-discovery/all

See the following sections for more information on the individual usage of each package.

PSR-18 HTTP Clients

Installation:

composer require psr-discovery/http-client-implementations

Usage:

use PsrDiscovery\Discover;

$httpClient = Discover::httpClient();

Please see the psr-discovery/http-client-implementations repository for a list of the supported implementations. If a particular implementation is missing you'd like to see, please open a pull request adding support.

PSR-17 HTTP Factories

Installation:

composer require psr-discovery/http-factory-implementations

Usage:

use PsrDiscovery\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');

Please see the psr-discovery/http-factory-implementations repository for a list of the supported implementations. If a particular implementation is missing you'd like to see, please open a pull request adding support.

PSR-14 Event Dispatchers

Installation:

composer require psr-discovery/event-dispatcher-implementations

Usage:

use PsrDiscovery\Discover;

$eventDispatcher = Discover::eventDispatcher();

Please see the psr-discovery/event-dispatcher-implementations repository for a list of the supported implementations. If a particular implementation is missing you'd like to see, please open a pull request adding support.

PSR-11 Containers

Installation:

composer require psr-discovery/container-implementations

Usage:

use PsrDiscovery\Discover;

$container = Discover::container();

Please see the psr-discovery/container-implementations repository for a list of the supported implementations. If a particular implementation is missing you'd like to see, please open a pull request adding support.

PSR-6 Caches

Installation:

composer require psr-discovery/cache-implementations

Usage:

use PsrDiscovery\Discover;

$cache = Discover::cache();

Please see the psr-discovery/cache-implementations repository for a list of the supported implementations. If a particular implementation is missing you'd like to see, please open a pull request adding support.

PSR-3 Logs

Installation:

composer require psr-discovery/log-implementations

Usage:

use PsrDiscovery\Discover;

$log = Discover::log();

Please see the psr-discovery/log-implementations repository for a list of the supported implementations. If a particular implementation is missing you'd like to see, please open a pull request adding support.

Handling Failures

If the library is unable to discover a suitable implementation, the relevant discovery method will simply return null. This allows you to handle the failure gracefully, for example by falling back to a default implementation.

Example:

use PsrDiscovery\Discover;

$httpClient = Discover::httpClient();

if ($httpClient === null) {
    // No suitable HTTP Client implementation was discovered.
    // Fall back to a default implementation.
    $httpClient = new DefaultHttpClient();
}

Exceptions

The library will expose a PsrDiscovery\Exceptions\SupportPackageNotFoundException when a discovery method is called, but the required support package is not installed.

Singletons

By default, the discovery methods will always return a new instance of the discovered implementation. If you wish to use a singleton instance instead, simply pass true to the $singleton parameter of the discovery method.

Example:

use PsrDiscovery\Discover;

// $httpClient1 !== $httpClient2 (default)
$httpClient1 = Discover::httpClient();
$httpClient2 = Discover::httpClient();

// $httpClient1 === $httpClient2
$httpClient1 = Discover::httpClient(singleton: true);
$httpClient2 = Discover::httpClient(singleton: true);

Mocking Priority

This library will give priority to searching for an available PSR mocking library, like psr-mock/http-client-implementation or php-http/mock-client.

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.

Preferring an Implementation

If you wish to prefer a specific implementation over others, you can use the prefer() on any installed discovery support libraries.

Example using psr-discovery/http-factories-implementations:

use PsrDiscovery\Discover;
use PsrDiscovery\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();

This will cause the discovery method to return the preferred implementation if it is available, otherwise, it will fall back to the default behavior.

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

Using a Specific Implementation

If you wish to force a specific implementation and ignore the rest of the discovery candidates, you can use the use() on any installed discovery support libraries.

Example using psr-discovery/http-factories-implementations:

use PsrDiscovery\Discover;
use PsrDiscovery\Implementations\Psr17\RequestFactories;

// Only discover a specific implementation of PSR-17.
RequestFactories::use('nyholm/psr7');

// Return an instance of Nyholm\Psr7\Factory\Psr17Factory,
// or null if it is not available.
$factory = Discover::httpRequestFactory();

This will cause the discovery method to return the preferred implementation if it is available, otherwise, it will return null.


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

Pinned Loading

  1. http-client-implementations http-client-implementations Public

    Lightweight library that discovers available PSR-18 HTTP Client implementations by searching for a list of well-known classes that implement the relevant interface, and returns an instance of the f…

    PHP 5 2

  2. http-factory-implementations http-factory-implementations Public

    Lightweight library that discovers available PSR-17 HTTP Factory implementations by searching for a list of well-known classes that implement the relevant interface, and returns an instance of the …

    PHP 6 2

  3. event-dispatcher-implementations event-dispatcher-implementations Public

    Lightweight library that discovers available PSR-14 Event Dispatcher implementations by searching for a list of well-known classes that implement the relevant interface, and returns an instance of …

    PHP 5 1

  4. container-implementations container-implementations Public

    Lightweight library that discovers available PSR-11 Container implementations by searching for a list of well-known classes that implement the relevant interface, and returns an instance of the fir…

    PHP 5 1

  5. cache-implementations cache-implementations Public

    Lightweight library that discovers available PSR-6 Cache implementations by searching for a list of well-known classes that implement the relevant interface, and returns an instance of the first on…

    PHP 5 1

  6. log-implementations log-implementations Public

    Lightweight library that discovers available PSR-3 Log implementations by searching for a list of well-known classes that implement the relevant interface, and returns an instance of the first one …

    PHP 6

Repositories

Showing 9 of 9 repositories
  • discovery Public

    Lightweight library that discovers available PSR implementations by searching for a list of well-known classes that implement the relevant interfaces, and returning an instance of the first one that is found.

    psr-discovery/discovery’s past year of commit activity
    PHP 6 MIT 2 0 0 Updated Aug 9, 2024
  • http-client-implementations Public

    Lightweight library that discovers available PSR-18 HTTP Client 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.

    psr-discovery/http-client-implementations’s past year of commit activity
    PHP 5 MIT 2 0 0 Updated Mar 16, 2024
  • .github Public
    psr-discovery/.github’s past year of commit activity
    0 0 0 0 Updated Mar 4, 2024
  • log-implementations Public

    Lightweight library that discovers available PSR-3 Log 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.

    psr-discovery/log-implementations’s past year of commit activity
    PHP 6 MIT 0 0 0 Updated Mar 4, 2024
  • http-factory-implementations Public

    Lightweight library that discovers available PSR-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.

    psr-discovery/http-factory-implementations’s past year of commit activity
    PHP 6 MIT 2 0 0 Updated Mar 4, 2024
  • event-dispatcher-implementations Public

    Lightweight library that discovers available PSR-14 Event Dispatcher 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.

    psr-discovery/event-dispatcher-implementations’s past year of commit activity
    PHP 5 MIT 1 0 0 Updated Mar 4, 2024
  • container-implementations Public

    Lightweight library that discovers available PSR-11 Container 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.

    psr-discovery/container-implementations’s past year of commit activity
    PHP 5 MIT 1 0 0 Updated Mar 4, 2024
  • cache-implementations Public

    Lightweight library that discovers available PSR-6 Cache 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.

    psr-discovery/cache-implementations’s past year of commit activity
    PHP 5 MIT 1 0 0 Updated Mar 4, 2024
  • all Public

    [READ ONLY] Lightweight library that discovers available PSR implementations by searching for a list of well-known classes that implement the relevant interfaces, and returning an instance of the first one that is found.

    psr-discovery/all’s past year of commit activity
    4 MIT 0 0 0 Updated Mar 4, 2024

Top languages

Loading…

Most used topics

Loading…