ConfigProviderRegister API

Purpose and Scope

This document describes the public API of the ConfigProviderRegister class, which provides methods for retrieving and manipulating the configuration provider registry. The class maintains a static list of 45+ configuration provider classes from the Hyperf and Hypervel ecosystems and offers four primary methods for registry interaction: get(), filter(), add(), and except().

For an overview of the entire Configuration Provider System, see Configuration Provider System. For details about the specific providers registered by default, see Hyperf and Hypervel Providers. For practical usage examples and patterns, see Dynamic Provider Management.

Sources: src/ConfigProviderRegister.php1-89

---

Class Structure and Static Registry

The ConfigProviderRegister class src/ConfigProviderRegister.php9-88 maintains a single static property $configProviders that contains an array of fully-qualified class names. This static property serves as the central registry for all configuration providers in the testbench environment.

Static Property Structure

protected static $configProviders = [
 \Hyperf\Command\ConfigProvider::class,
 \Hyperf\Database\SQLite\ConfigProvider::class,
 // ... 43 more provider class names
];

The registry is initialized with a fixed list of 45 provider classes src/ConfigProviderRegister.php11-57:

• 20 Hyperf providers (lines 12-31): Core Hyperf framework components
• 25 Hypervel providers (lines 32-57): Laravel-like abstractions built on Hyperf

Because the property is static, modifications persist across method calls within the same PHP process, making the registry a singleton-like shared state.

Sources: src/ConfigProviderRegister.php11-57

---

Method Reference

get()

Purpose: Retrieves the current array of configuration provider class names.

Behavior:

• Returns the static $configProviders array src/ConfigProviderRegister.php65
• Conditionally adds \Hyperf\Devtool\ConfigProvider if the class exists src/ConfigProviderRegister.php61-62
• Does not mutate the static registry; the Devtool provider is only included in the returned array

Return Value: Array of fully-qualified configuration provider class names.

Example Return Structure:

Use Cases:

• Retrieving the full provider list for application bootstrapping
• Inspecting the current registry state
• Passing providers to the application container

Sources: src/ConfigProviderRegister.php59-66

---

filter()

Purpose: Filters the provider registry using a custom callback function and updates the static registry with the filtered result.

Parameters:

• $callback (callable): A callback function that receives each provider class name and returns true to keep it or false to exclude it

Behavior:

• Calls get() to retrieve the current provider list (including conditional Devtool provider) src/ConfigProviderRegister.php70
• Applies array_filter() with the provided callback
• Mutates the static $configProviders property with the filtered result src/ConfigProviderRegister.php70
• Returns the filtered array

Return Value: Array of provider class names that passed the filter condition.

Callback Signature:

Important Notes:

• This method permanently modifies the registry
• Subsequent calls to any method will use the filtered registry
• The Devtool provider may be included in filtering if the class exists

Sources: src/ConfigProviderRegister.php68-71

---

add()

Purpose: Adds one or more configuration provider class names to the registry.

Parameters:

• $providers (array|string): Either a single provider class name (string) or an array of provider class names

Behavior:

• Wraps the input parameter using Arr::wrap() to normalize single strings into arrays src/ConfigProviderRegister.php77
• Merges the new provider(s) with the existing static registry using array_merge() src/ConfigProviderRegister.php75-78
• Mutates the static $configProviders property src/ConfigProviderRegister.php75
• Does not return a value

Return Value: void

Normalization Behavior:

• add('MyProvider') is normalized to add(['MyProvider'])
• add(['Provider1', 'Provider2']) remains unchanged
• Duplicate providers are not automatically filtered (array merge allows duplicates)

Use Cases:

• Adding custom package providers
• Registering test-specific providers
• Extending the provider list at runtime

Sources: src/ConfigProviderRegister.php73-79

---

except()

Purpose: Removes one or more configuration provider class names from the registry.

Parameters:

• $providers (array|string): Either a single provider class name (string) or an array of provider class names to exclude

Behavior:

• Wraps the input parameter using Arr::wrap() to normalize single strings into arrays src/ConfigProviderRegister.php85
• Removes specified providers using array_diff() src/ConfigProviderRegister.php83-86
• Mutates the static $configProviders property src/ConfigProviderRegister.php83
• Does not return a value

Return Value: void

Difference Behavior:

• except('ProviderToRemove') removes a single provider
• except(['Provider1', 'Provider2']) removes multiple providers
• If a specified provider doesn't exist, no error is raised (array_diff silently ignores non-existent values)
• Array keys are not preserved after the diff operation

Use Cases:

• Disabling problematic providers in tests
• Removing unwanted framework components
• Testing provider isolation scenarios

Sources: src/ConfigProviderRegister.php81-87

---

API Method Relationships

Method Classification

The four API methods can be classified by their characteristics:

Method	Returns Data	Mutates Registry	Conditional Logic
get()	✓	✗	✓ (Devtool check)
filter()	✓	✓	✗
add()	✗	✓	✗
except()	✗	✓	✗

Method Call Patterns

Diagram: ConfigProviderRegister method relationships and data flow

Sources: src/ConfigProviderRegister.php59-87

---

State Mutation Lifecycle

The following diagram illustrates how the static registry state changes through method calls:

Diagram: State transitions of the static $configProviders registry

Important Characteristics:

1. Immutable Operations: Only get() is non-mutating
2. Cumulative Mutations: add() can be called multiple times to accumulate providers
3. Irreversible Filtering: Once filter() or except() removes providers, they cannot be automatically restored
4. No Reset Method: There is no public API to reset the registry to its initial 45-provider state

Sources: src/ConfigProviderRegister.php59-87

---

Method Interaction Patterns

Pattern 1: Conditional Retrieval

Diagram: Conditional logic in get() method

Sources: src/ConfigProviderRegister.php59-66

---

Pattern 2: Filter with Mutation

Diagram: Filter operation with permanent registry mutation

Sources: src/ConfigProviderRegister.php68-71

---

Pattern 3: Array Normalization

Both add() and except() use Arr::wrap() for parameter normalization:

Diagram: Parameter normalization and operation execution for add() and except()

Sources: src/ConfigProviderRegister.php73-87

---

Complete Method Signature Reference

Method Summary Table

Method	Signature	Return Type	Mutates Registry	Parameter Type
get()	public static function get()	array	No	None
filter()	public static function filter(callable $callback)	array	Yes	callable
add()	public static function add(array|string $providers)	void	Yes	array|string
except()	public static function except(array|string $providers)	void	Yes	array|string

Callable Signature for filter()

The filter() method accepts any callable that matches this signature:

Valid callable formats:

• Closure: fn($p) => str_contains($p, 'Hyperf')
• Function name: 'is_string'
• Class method: [$object, 'methodName']
• Static method: ['ClassName', 'staticMethod']

Sources: src/ConfigProviderRegister.php59-87

---

Dependencies and Imports

The ConfigProviderRegister class has minimal external dependencies:

Diagram: External dependencies of ConfigProviderRegister

Import Statement:

The Arr::wrap() helper is used in src/ConfigProviderRegister.php77 and src/ConfigProviderRegister.php85 to normalize scalar strings into arrays, allowing both add('Provider') and add(['Provider']) syntax.

Conditional Dependency: The Hyperf\Devtool\ConfigProvider class is checked for existence but not imported src/ConfigProviderRegister.php61 This optional dependency pattern allows the testbench to function with or without the Hyperf Devtool package installed.

Sources: src/ConfigProviderRegister.php7 src/ConfigProviderRegister.php61

---

API Usage Context

The ConfigProviderRegister API is typically called during application bootstrapping. The most common usage pattern occurs in the CreatesApplication trait, where getPackageProviders() may interact with this registry. See CreatesApplication Trait for integration patterns.

The registry serves as a centralized source of truth for which configuration providers should be loaded into the application container during test execution. Dynamic manipulation of this registry allows tests to customize the application environment by including or excluding specific framework components.

Sources: src/ConfigProviderRegister.php1-89