Configuration Loading System

Purpose and Scope

The configuration loading system is responsible for discovering, loading, and merging configuration data from multiple sources during application bootstrap. This system runs once during the dependency injection container initialization phase and produces a single unified Repository instance containing all configuration values.

This document provides an overview of the configuration loading architecture and the flow of data from various sources into the final configuration repository. For detailed documentation on specific subsystems, see:

• Provider discovery and merging: Provider Config Discovery and Merging
• Factory orchestration: Configuration Factory
• File-based configuration: File-Based Configuration

For information about accessing configuration at runtime, see Repository Class and Configuration Function.

Loading Phases

The configuration loading system operates in three distinct phases:

Phase	Component	Trigger	Purpose
Registration	ConfigProvider	Hyperf DI container bootstrap	Registers ConfigFactory as implementation of ConfigInterface
Loading	ConfigFactory	First request for ConfigInterface	Orchestrates discovery and merging from all sources
Runtime	Repository	Application code	Provides read/write access to merged configuration

The loading phase is the most complex, involving multiple subsystems that discover and merge configuration from package providers, root configuration files, and autoload directories.

Sources: src/ConfigFactory.php1-66

Configuration Sources

Configuration data flows into the system from three primary source categories, processed in a specific order to establish merge precedence:

Configuration Source Flow

Merge Precedence (lowest to highest):

1. Provider configurations from packages (discovered by ProviderConfig)
2. Root configuration from config/hyperf.php
3. Autoload configurations from config/autoload/*.php files

Later sources override earlier sources when keys conflict, with special handling for arrays and priority definitions.

Sources: src/ConfigFactory.php22-33 src/ProviderConfig.php26-54

Loading Sequence

The following sequence diagram illustrates the execution flow when the DI container first requests the ConfigInterface implementation:

ConfigInterface Resolution Flow

The ConfigFactory::__invoke() method coordinates this entire sequence, ensuring that all configuration sources are discovered, loaded, and merged before creating the final Repository instance.

Sources: src/ConfigFactory.php13-34 src/ProviderConfig.php26-54

Component Architecture

The loading system consists of three main components that work together to produce the final configuration:

Loading System Components

Sources: src/ConfigFactory.php1-66 src/ProviderConfig.php1-169

ProviderConfig System

The ProviderConfig class (importance: 22.24) is the most critical component in the loading system. It handles discovery and merging of configurations from external Composer packages.

Key Responsibilities:

• Discover package configurations from composer.json extra fields
• Filter packages using dont-discover directives
• Instantiate and invoke service providers
• Merge configurations using sophisticated recursive algorithm
• Handle PriorityDefinition objects in dependency arrays

Key Methods:

• ProviderConfig::load() - Main entry point, caches result in static property
• ProviderConfig::loadProviders() - Instantiates providers and collects configs
• ProviderConfig::merge() - Merges multiple config arrays with special dependency handling
• ProviderConfig::mergeTwo() - Public method for merging two arrays

This component is documented in detail in Provider Config Discovery and Merging.

Sources: src/ProviderConfig.php17-169

ConfigFactory System

The ConfigFactory class (importance: 13.90) orchestrates the overall configuration loading process and serves as the DI container factory for ConfigInterface.

Key Responsibilities:

• Coordinate between provider configs, root config, and autoload configs
• Read and validate configuration files
• Discover configuration files using Symfony Finder
• Generate dot-notation keys from file paths
• Merge all sources using ProviderConfig::mergeTwo()
• Instantiate the final Repository

Key Methods:

• ConfigFactory::__invoke() - DI container entry point
• ConfigFactory::readConfig() - Load single config file
• ConfigFactory::readPaths() - Discover and load multiple config files with key generation

This component is documented in detail in Configuration Factory.

Sources: src/ConfigFactory.php11-66

File-Based Configuration

The file-based configuration subsystem handles loading configuration from the local filesystem in two locations:

Root Configuration:

• Path: config/hyperf.php
• Loaded via ConfigFactory::readConfig()
• Returns a flat array merged at root level

Autoload Directory:

• Path: config/autoload/*.php
• Discovered via Symfony Finder
• Each file generates a dot-notation key from its path and basename
• Example: config/autoload/database.php → database key
• Example: config/autoload/cache/redis.php → cache.redis key

This subsystem is documented in detail in File-Based Configuration.

Sources: src/ConfigFactory.php36-65

Merge Strategy

All configuration sources are merged using the ProviderConfig::mergeTwo() method, which implements a sophisticated recursive merge algorithm:

Key Type	Behavior	Example
Numeric keys	Append values with deduplication	[0 => 'a'] + [0 => 'b'] = [0 => 'a', 1 => 'b']
String keys (scalar)	Later value overwrites	['key' => 'a'] + ['key' => 'b'] = ['key' => 'b']
String keys (array)	Recursive merge	['db' => ['host' => 'a']] + ['db' => ['port' => 1]] = ['db' => ['host' => 'a', 'port' => 1]]
PriorityDefinition	Special merge via PriorityDefinition::merge()	Dependency injection priority handling

The merge is performed using array_reduce() with mergeTwo as the callback, processing sources in order: provider configs → root config → autoload configs. This ensures that later sources have higher precedence.

Detailed merge algorithm documentation is available in Configuration Merging Strategies.

Sources: src/ProviderConfig.php100-168 src/ConfigFactory.php27-31

Caching and Performance

The ProviderConfig::load() method caches its result in a static property $providerConfigs after the first invocation. This prevents redundant package discovery and provider instantiation if the method is called multiple times during bootstrap.

To clear the cache (useful in testing scenarios), the parent class provides a ProviderConfig::clear() method.

Sources: src/ProviderConfig.php19-30

Configuration Loading Order

The complete loading order with merge precedence:

Within package providers, the merge order is determined by:

1. Package dependency order (dependencies merged before dependents)
2. Alphabetical order for packages at the same dependency level
3. Individual configuration sources within each package

Sources: src/ConfigFactory.php22-33

Error Handling

The loading system is designed to be resilient to missing or invalid configuration sources:

Error Condition	Behavior
Missing config/hyperf.php	Returns empty array, continues
Invalid PHP in config file	PHP fatal error (not caught)
Invalid provider class	Skipped silently via class_exists() check
Missing __invoke() method	Skipped silently via method_exists() check
Package dont-discover with *	Returns empty provider configs
Invalid getProviderConfig() return	Skipped if falsy value

The system prioritizes availability over strict validation, allowing the application to start even with partial configuration.

Sources: src/ProviderConfig.php32-72 src/ConfigFactory.php36-44

Integration Points

The configuration loading system integrates with the following framework components:

Hyperf Components:

• Hyperf\Support\Composer - Package metadata discovery
• Hyperf\Collection\Arr - Nested array manipulation
• Hyperf\Di\Definition\PriorityDefinition - Dependency priority handling

Symfony Components:

• Symfony\Component\Finder\Finder - Recursive file discovery

Hypervel Components:

• Hypervel\Support\ServiceProvider - Provider base class with getProviderConfig() method

The system extends Hyperf\Config\ProviderConfig to maintain compatibility with Hyperf's configuration discovery mechanism while adding Hypervel-specific extensions.

Sources: src/ProviderConfig.php7-11 src/ConfigFactory.php7-9