Configuration Factory

Purpose and Scope

The ConfigFactory class orchestrates the entire configuration loading process during application bootstrap. It coordinates between provider-based configurations (see Provider Config Discovery and Merging), file-based configurations (see File-Based Configuration), and produces the final Repository instance (see Repository Class) that applications use at runtime. This page explains how ConfigFactory coordinates these subsystems and implements the merge order that determines configuration precedence.

Overview

The ConfigFactory class serves as the factory implementation registered with Hyperf's dependency injection container to provide ConfigInterface instances. When the container needs to resolve a configuration dependency, it invokes ConfigFactory which:

1. Loads provider configurations from Composer packages
2. Loads the root hyperf.php configuration file
3. Scans the config/autoload/ directory for additional configuration files
4. Merges all sources using a specific precedence order
5. Returns a Repository instance containing the unified configuration

Sources: src/ConfigFactory.php1-67

Factory Invocation Flow

The following diagram illustrates how ConfigFactory is invoked and the sequence of operations it performs:

Description: The DI container invokes ConfigFactory::__invoke() which performs configuration loading in two distinct phases: loading from multiple sources and merging them into a unified array.

Sources: src/ConfigFactory.php13-34

Configuration Sources and Code Mapping

The following diagram maps the natural language concepts to specific code entities and file paths:

Description: This diagram maps configuration sources to specific code constructs, showing the exact class names, method names, and file paths involved in the loading process.

Sources: src/ConfigFactory.php13-34

Configuration Merge Order and Precedence

The ConfigFactory implements a specific merge order that determines which configuration values take precedence when conflicts occur:

Priority	Source	Code Location	Description
1 (Lowest)	Provider Configs	ProviderConfig::load()	Configurations from Composer packages
2	Root Config	readConfig('config/hyperf.php')	Main configuration file
3 (Highest)	Autoload Configs	readPaths(['config/autoload'])	Individual feature configuration files

The merge is performed using array_reduce with ProviderConfig::mergeTwo as the reduction function:

merged = reduce([provider, root, ...autoload], mergeTwo, provider)

This means:

• Provider configs are merged first (base)
• Root config is merged on top (overrides provider configs)
• Each autoload config is merged in turn (overrides everything before it)

The following diagram visualizes the merge precedence:

Description: Configuration sources are merged left-to-right, with later sources taking precedence over earlier ones. The gradient represents increasing precedence.

Sources: src/ConfigFactory.php25-31

Root Configuration Loading

The readConfig method handles loading the root config/hyperf.php file:

Behavior:

• Checks if file exists and is readable at src/ConfigFactory.php39
• Uses require to load the PHP file at src/ConfigFactory.php40
• Validates the result is an array at src/ConfigFactory.php43
• Returns empty array if file doesn't exist or doesn't return an array

File Path: The root config is always located at BASE_PATH/config/hyperf.php as specified at src/ConfigFactory.php22

Sources: src/ConfigFactory.php36-44

Autoload Directory Scanning

The readPaths method discovers and loads configuration files from one or more directories using Symfony Finder:

File Discovery Process

Description: The file discovery process uses Symfony Finder to locate PHP files, generates dot-notation keys from file paths, and loads each file's contents into a nested array structure.

Sources: src/ConfigFactory.php46-65

Key Generation Mechanism

The key generation converts file paths to dot-notation configuration keys:

File Path	Relative Path	Basename	Generated Key
config/autoload/app.php	""	app	app
config/autoload/cache.php	""	cache	cache
config/autoload/dependencies/custom.php	dependencies	custom	dependencies.custom

The key generation logic at src/ConfigFactory.php56-59:

1. Get relative path: $file->getRelativePath() - directory structure
2. Convert slashes to dots: str_replace('/', '.', $relativePath)
3. Get basename: $file->getBasename('.php') - filename without extension
4. Combine with dots: implode('.', array_filter([relativePath, basename]))
5. Use Arr::set() to create nested array structure

Sources: src/ConfigFactory.php54-61

Load Paths Configuration

The factory determines which directories to scan based on the Hyperf folder structure:

Description: The factory checks for an autoload subdirectory and includes it in the scan paths if present, providing compatibility with Hyperf's standard folder structure.

Implementation Details:

• Base config path is always included: $loadPaths = [$configPath] at src/ConfigFactory.php16
• Autoload directory is conditionally added at src/ConfigFactory.php18-20
• Root hyperf.php is explicitly excluded from autoload scan at src/ConfigFactory.php23

Sources: src/ConfigFactory.php15-20

Method Reference

__invoke(ContainerInterface $container): Repository

Location: src/ConfigFactory.php13-34

Purpose: Main factory method invoked by the DI container to create a Repository instance.

Parameters:

• $container: The DI container instance (currently unused but required by factory interface)

Return Value: A Repository instance containing the merged configuration from all sources.

Process:

1. Defines base config path and load paths
2. Loads provider configurations via ProviderConfig::load()
3. Loads root configuration via readConfig()
4. Loads autoload configurations via readPaths()
5. Merges all sources using array_reduce with ProviderConfig::mergeTwo
6. Creates and returns new Repository instance

---

readConfig(string $configPath): array

Location: src/ConfigFactory.php36-44

Purpose: Loads a single PHP configuration file and validates it returns an array.

Parameters:

• $configPath: Absolute path to the PHP configuration file

Return Value: Array of configuration data, or empty array if file doesn't exist or doesn't return an array.

Validation:

• Checks file exists with file_exists()
• Checks file is readable with is_readable()
• Validates return value is an array with is_array()

---

readPaths(array $paths, array $excludes = []): array

Location: src/ConfigFactory.php46-65

Purpose: Scans one or more directories for PHP configuration files, generates dot-notation keys from file paths, and loads each file into a nested array structure.

Parameters:

• $paths: Array of directory paths to scan
• $excludes: Array of filename patterns to exclude (e.g., ['hyperf.php'])

Return Value: Array of configuration arrays, where each element is an array with dot-notation keys derived from the file path.

Key Features:

• Uses Symfony\Component\Finder\Finder for file discovery
• Generates keys from relative path and basename
• Uses Hyperf\Collection\Arr::set() for nested array creation
• Each file's configuration is wrapped in its own array before merging

Sources: src/ConfigFactory.php46-65

Integration with Other Components

The ConfigFactory integrates with several other components in the configuration system:

Component	Relationship	Description
ProviderConfig	Delegates to	Calls ProviderConfig::load() for provider configurations and uses ProviderConfig::mergeTwo() for merging
Repository	Creates	Instantiates Repository with merged configuration data
DI Container	Invoked by	Registered as factory for ConfigInterface via ConfigProvider
Symfony Finder	Uses	Leverages for file system traversal and filtering
Hyperf Arr	Uses	Utilizes for dot-notation key manipulation

For information about how ConfigFactory is registered with the DI container, see Framework Integration.

Sources: src/ConfigFactory.php1-67