Download the PHP package quellabs/discover without Composer

Quellabs Discover

A lightweight, flexible service discovery component for PHP applications that automatically discovers service providers across your application and its dependencies with advanced caching and lazy loading capabilities.

Introduction

Quellabs Discover solves the common challenge of service discovery in PHP applications. It focuses solely on locating service providers defined in your application and its dependencies, giving you complete control over how to use these providers in your application architecture. Unlike other service discovery solutions that force specific patterns, Discover is framework-agnostic and can be integrated into any PHP application.

Key Features:

• Framework Agnostic: Works with any PHP application or framework
• Multiple Discovery Methods: Composer configuration, directory scanning, and custom scanners
• Provider Families: Organize providers into logical groups
• Fluent Query Builder: Chainable API for filtering providers
• Efficient Discovery: Uses static methods to gather metadata without instantiation
• Efficient Caching: Export and import provider definitions for fast subsequent loads
• Lazy Instantiation: Providers are only created when actually needed

Installation

Install the package via Composer:

Quick Start

Here's how to quickly get started with Discover:

Service Providers

Creating a Service Provider

To create a discoverable service provider, implement the ProviderInterface:

Provider Interface

The core ProviderInterface separates discovery-time methods (static) from runtime methods (instance):

Static methods are called during discovery without instantiation; instance methods are used at runtime when providers are actually needed.

Discovery Methods

Quellabs Discover supports multiple methods to discover service providers:

Composer Configuration

Add service providers to your composer.json file using the nested structure where discover is always the top-level key:

Use the ComposerScanner to discover these providers:

Directory Scanning

Scan directories for provider classes:

Metadata Scanning

In addition to discovering service providers, Quellabs Discover can collect arbitrary key/value metadata that packages advertise in their composer.json. This is useful when packages need to expose configuration paths, resource directories, or other structured data to the host application — without registering a full service provider.

Provider scanning and metadata scanning are separate systems that run in the same discover() call. A single Discover instance can run both simultaneously.

How It Works

Metadata scanners read from the extra.discover.<family> section of every installed package's composer.json. Each package can declare any number of keys under the family. Values can be a scalar string or an array of strings — they are returned as-is without transformation.

MetadataScannerInterface

Custom metadata scanners implement MetadataScannerInterface, which requires two methods:

Unlike ScannerInterface (which produces ProviderDefinition objects), metadata scanners return raw values. Results are grouped by package name to preserve the relationship between keys declared together in the same composer.json.

Using MetadataCollector

MetadataCollector is the built-in implementation. Register it via the same addScanner() method used for provider scanners — Discover automatically routes it to the metadata pipeline based on the interface it implements:

The MetadataCollector constructor accepts a few optional parameters:

In strict mode, malformed entries (wrong types, non-array family blocks) throw a \RuntimeException instead of being silently skipped.

Retrieving Collected Metadata

After discover() runs, three methods are available for accessing collected metadata:

getAllMetadata(): array

Returns everything collected, nested as [family][package][key]:

getFamilyMetadata(string $familyName): array

Returns all metadata for a single family, grouped by package name. Useful when you need to know which package declared what — for example, to resolve paths relative to each package's install directory:

getFamilyValues(string $familyName, string $metadataKey): array

Returns a flat, deduplicated list of all values for a specific key across all packages. Handles both scalar values and arrays transparently. This is the most convenient method when you just need a merged list and don't care which package contributed each entry:

Strict Mode and Logging

By default, MetadataCollector silently skips malformed entries and logs a warning if a PSR-3 logger is provided. Enable strict mode to surface these issues as exceptions instead:

Warnings are emitted for:

• A family block that is not an array (e.g. "canvas": "invalid")
• A metadata value that is neither a string nor an array

Custom Metadata Scanners

For sources other than composer.json, implement MetadataScannerInterface directly:

The results are merged with any data collected from MetadataCollector under the same family name, so multiple scanners for the same family work transparently.

Querying Providers

Fluent Query Builder

The findProviders() method returns a query builder that allows you to chain filter methods for expressive, readable queries:

Query Methods

Use get() to return all matches as an array, or lazy() to get a generator that instantiates providers one at a time — preferable for large result sets.

Direct Access Methods

For simple lookups without the query builder:

Caching and Performance

Provider definitions can be exported after discovery and re-imported on subsequent requests, bypassing the scanning process entirely.

Provider instances are cached after first instantiation, so repeated calls to get() or findProviders() for the same class never re-instantiate.

Provider Configuration

Quellabs Discover supports configuration files for providers registered through Composer.

Basic Configuration File

Create a configuration file that returns an array:

Registering Provider with Configuration

Specify a configuration file in your composer.json:

Using Configuration in Providers

Configuration is loaded and merged with defaults when providers are instantiated:

Provider Families

Provider families organize service providers into logical groups. Families are determined by the composer.json structure, not by the provider classes themselves.

Defining Provider Families

Define providers in different families in your composer.json:

Using Multiple Family Scanners

Create scanners for each family:

Extending Discover

Creating Custom Scanners

Implement the ScannerInterface to create custom scanners:

License

The Quellabs Discover package is open-sourced software licensed under the MIT license.