Dynamic Provider Management

This page covers practical patterns for dynamically managing configuration providers in the testbench environment. It demonstrates how to add custom providers, exclude unwanted providers, and filter providers based on runtime conditions using the ConfigProviderRegister API and test class extension points.

For API reference documentation of ConfigProviderRegister methods, see ConfigProviderRegister API. For a catalog of available Hyperf and Hypervel providers, see Hyperf and Hypervel Providers.

Overview

The testbench provides two primary mechanisms for dynamic provider management:

1. Static Registry Manipulation: Directly modifying the ConfigProviderRegister before application creation
2. Test Class Hooks: Overriding getPackageProviders() and getPackageAliases() in test classes

Both approaches allow customization of which configuration providers are loaded into the application container during test execution.

Provider Management Flow

Sources: src/ConfigProviderRegister.php59-88 src/Concerns/CreatesApplication.php19-58

Adding Custom Providers

Using ConfigProviderRegister::add()

The ConfigProviderRegister::add() method appends one or more custom configuration providers to the static registry. This method accepts either a single provider class string or an array of provider class strings.

Implementation Details

The add() method at src/ConfigProviderRegister.php73-79 uses Arr::wrap() to normalize input and array_merge() to combine providers:

Step	Method	Purpose
1	Arr::wrap($providers)	Convert string to array, or pass through existing array
2	array_merge()	Append new providers to existing registry
3	Update static::$configProviders	Persist changes to static property

Usage Example: Adding a Package Provider

Sources: src/ConfigProviderRegister.php73-79

Using getPackageProviders() in Tests

The CreatesApplication trait provides the getPackageProviders() hook method for registering package-specific providers within individual test classes. This approach is preferred when providers should only be loaded for specific tests.

Implementation Details

The registration flow at src/Concerns/CreatesApplication.php35-42 iterates through providers returned by getPackageProviders() and registers each with the application:

Usage Example: Test-Scoped Provider Registration

Comparison: Static vs Test-Scoped Registration

Approach	Scope	Timing	Use Case
ConfigProviderRegister::add()	Global (all tests)	Before application creation	Package-wide providers needed by all tests
getPackageProviders()	Test class only	During defineEnvironment()	Test-specific providers or conditional loading

Sources: src/Concerns/CreatesApplication.php19-42

Excluding Providers

The ConfigProviderRegister::except() method removes specified providers from the registry. This is useful when default providers conflict with test requirements or when testing behavior with specific services disabled.

Exclusion Mechanism

Implementation Details

The except() method at src/ConfigProviderRegister.php81-87 uses array_diff() to remove providers:

This performs a set difference operation where all providers matching those in $providers are removed from the registry.

Usage Example: Disabling Redis in Tests

Usage Example: Testing Without Cache

Sources: src/ConfigProviderRegister.php81-87

Filtering Providers

The ConfigProviderRegister::filter() method applies a custom callback function to select which providers to keep in the registry. This provides maximum flexibility for conditional provider loading based on runtime conditions.

Filter Operation Flow

Implementation Details

The filter() method at src/ConfigProviderRegister.php68-71 retrieves the current registry via get() and applies the callback:

Note that filter() both returns the filtered array and updates the static registry, making the change persistent for subsequent operations.

Usage Example: Namespace-Based Filtering

Usage Example: Conditional Provider Loading

Usage Example: Excluding Provider Patterns

Sources: src/ConfigProviderRegister.php68-71

Practical Patterns and Examples

Pattern: Testing Without External Dependencies

When testing package logic that shouldn't depend on external services, exclude those providers:

Pattern: Minimal Provider Set for Fast Tests

For unit tests that need minimal framework overhead:

Pattern: Combining add() and except()

Adding custom providers while removing conflicting ones:

Pattern: Feature Flag-Based Provider Loading

Sources: src/ConfigProviderRegister.php59-88 src/Concerns/CreatesApplication.php19-42

Provider Registration Lifecycle

Understanding when provider modifications take effect is crucial for correct usage.

Complete Provider Resolution Timeline

Key Timing Constraints

Operation	Must Occur Before	Reason
ConfigProviderRegister::add()	createApplication()	Static registry must be finalized before retrieval
ConfigProviderRegister::except()	createApplication()	Exclusions must happen before provider loading
ConfigProviderRegister::filter()	createApplication()	Filtering must occur before provider instantiation
getPackageProviders() override	N/A (called during setup)	Hook is invoked automatically by defineEnvironment()

Per-Test Isolation

The ConfigProviderRegister uses a static property, so modifications persist across tests unless explicitly reset. For per-test modifications, use one of these patterns:

Pattern 1: Reset in setUp()

Pattern 2: Use getPackageProviders() for Scoped Changes

Sources: src/ConfigProviderRegister.php11-88 src/Concerns/CreatesApplication.php1-59

Method Reference Summary

Method	Parameters	Returns	Side Effects	Use Case
ConfigProviderRegister::get()	None	array	May append Devtool\ConfigProvider if available	Retrieve current provider list
ConfigProviderRegister::add()	array|string $providers	void	Updates static registry	Append custom providers
ConfigProviderRegister::except()	array|string $providers	void	Updates static registry	Remove unwanted providers
ConfigProviderRegister::filter()	callable $callback	array	Updates static registry	Conditional provider selection
getPackageProviders()	ApplicationContract $app	array	None (hook method)	Test-scoped provider additions
getPackageAliases()	ApplicationContract $app	array	None (hook method)	Test-scoped alias definitions

Sources: src/ConfigProviderRegister.php59-88 src/Concerns/CreatesApplication.php19-58