Configuration Merging Strategies

Purpose and Scope

This document explains the configuration merging algorithms used throughout the hypervel/config system. The merging strategies determine how multiple configuration arrays from different sources are combined into a single unified configuration structure.

The core merging logic is implemented in the ProviderConfig class and is used in two primary contexts:

1. Merging provider configurations discovered from multiple packages (see page 6.1: Provider Config Discovery and Merging)
2. Aggregating file-based configurations with provider configurations in ConfigFactory (see page 6.2: Configuration Factory)

This page focuses specifically on the merging algorithms themselves, their behavior with different array types, and special handling for framework-specific constructs like PriorityDefinition.

---

The Core Merging Algorithm: mergeTwo()

The fundamental merging operation is performed by ProviderConfig::mergeTwo(), which combines two configuration arrays according to specific rules based on array key types and value types.

Algorithm Overview

Diagram: Decision tree for ProviderConfig::mergeTwo() method logic

Sources: src/ProviderConfig.php145-168

Merging Behavior by Key Type

The algorithm applies different strategies based on whether array keys are numeric (lists) or string (associative arrays):

Key Type	Scenario	Behavior	Rationale
Numeric	New value not in base	Append to end of array	Preserve list semantics
Numeric	Value already exists	Skip (deduplicate)	Prevent duplicate entries
String	Key doesn't exist in base	Add key-value pair	Introduce new configuration
String	Both values are arrays	Recursive merge	Deep merge nested structures
String	Scalar vs array, or different scalars	Override wins	Later configuration takes precedence

Sources: src/ProviderConfig.php145-168

Implementation Details

The mergeTwo() method is declared as public static specifically so that ConfigFactory can reuse the same merge semantics when aggregating file-based configurations. This ensures consistent merging behavior across the entire configuration loading pipeline.

Diagram: Shared usage of ProviderConfig::mergeTwo() in both provider and file-based merging

Sources: src/ProviderConfig.php141-142 src/ProviderConfig.php145

---

Multi-Array Merging: merge()

When more than two configuration arrays need to be combined, the merge() method uses array_reduce() to iteratively apply mergeTwo().

Reduction Pipeline

Diagram: Array reduction pipeline in ProviderConfig::merge() using array_reduce()

The implementation uses array_reduce() with mergeTwo() as the reduction function:

This approach ensures that:

• The first array serves as the base
• Each subsequent array is merged in order
• Configuration defined later takes precedence for scalar values
• Lists are accumulated with deduplication

Sources: src/ProviderConfig.php100-110

---

Special Handling: PriorityDefinition

After the standard merge process, merge() applies special handling for the dependencies configuration key, which may contain PriorityDefinition objects.

PriorityDefinition Merge Process

PriorityDefinition is a Hyperf framework class used to define dependency injection bindings with priority values. When multiple providers define dependencies with priorities, these must be merged using the PriorityDefinition::merge() method rather than simple array replacement.

Diagram: Special merge logic for dependencies key with PriorityDefinition objects

Sources: src/ProviderConfig.php112-128

Why Special Handling Is Needed

The standard mergeTwo() algorithm would treat PriorityDefinition objects as scalar values and simply replace them. However, PriorityDefinition objects contain multiple candidate implementations with associated priority values. The special handling:

1. Resets the dependencies array to empty
2. Iterates through all input arrays in order
3. For each dependency binding:
   • If no existing PriorityDefinition, sets the value directly
   • If existing PriorityDefinition and new value is also PriorityDefinition, calls depend->merge(value) to merge priority definitions
4. Preserves the priority-based resolution behavior of Hyperf's DI container

Sources: src/ProviderConfig.php113-127

---

Merging Behavior Examples

Example 1: Pure List Merging (Numeric Keys)

Input:

Result:

Behavior: Numeric keys cause appending with deduplication via in_array() strict comparison.

Sources: src/ProviderConfig.php150-154

Example 2: Associative Array Merging (String Keys)

Input:

Result:

Behavior: String keys trigger recursive merge for arrays, with override values taking precedence for scalars.

Sources: src/ProviderConfig.php155-164

Example 3: Mixed Array (Numeric and String Keys)

Input:

Result:

Behavior: Numeric keys append, string keys override, both behaviors applied to the same array.

Sources: src/ProviderConfig.php149-164

Example 4: Nested Structure Merging

Input:

Result:

Behavior: Recursive merging maintains deep structure while allowing targeted overrides at any nesting level.

Sources: src/ProviderConfig.php158-160

---

Integration Points

Usage in ProviderConfig::load()

The merge() method is called within loadProviders() to combine all discovered provider configurations:

Diagram: Method invocation sequence in ProviderConfig::load() showing merge operations

Sources: src/ProviderConfig.php56-75 src/ProviderConfig.php100-131

Usage in ConfigFactory

The ConfigFactory class directly calls ProviderConfig::mergeTwo() when aggregating file-based configurations with provider configurations:

This ensures that file-based configurations and provider configurations follow identical merging semantics, maintaining consistency across the entire configuration loading pipeline.

Sources: src/ProviderConfig.php141-142

---

Key Design Decisions

1. Public Static mergeTwo()

The mergeTwo() method is declared public and static to enable reuse by ConfigFactory. This design choice promotes consistency and reduces code duplication.

Trade-off: Public visibility increases the API surface, but the benefit of consistent merging behavior outweighs this concern.

Sources: src/ProviderConfig.php145

2. Strict Deduplication for Numeric Arrays

The algorithm uses in_array($value, $result, true) with strict comparison, ensuring that only truly identical values are deduplicated. This prevents accidental merging of similar but distinct values.

Example: The strings "0" and 0 are treated as different values.

Sources: src/ProviderConfig.php152

3. Override Semantics for Scalar Values

When a string key exists in both arrays with non-array values, the override value always wins. This follows the principle that later-loaded configurations should take precedence, allowing packages and applications to override framework defaults.

Sources: src/ProviderConfig.php161-163

4. Post-Processing for Dependencies

Rather than integrating PriorityDefinition handling into the recursive merge logic, it is applied as a post-processing step. This separation of concerns keeps the core merging algorithm clean and makes the special case handling explicit and maintainable.

Sources: src/ProviderConfig.php112-128

---

Code Entity Reference

Code Entity	Location	Purpose
ProviderConfig::merge()	src/ProviderConfig.php100-131	Merges multiple configuration arrays using reduction
ProviderConfig::mergeTwo()	src/ProviderConfig.php145-168	Core algorithm for merging two arrays
ProviderConfig::$providerConfigs	src/ProviderConfig.php19	Static cache for merged provider configurations
ProviderConfig::loadProviders()	src/ProviderConfig.php56-75	Invokes merge() after loading provider configs
PriorityDefinition	Hyperf Framework	Framework class for DI bindings with priorities
PriorityDefinition::merge()	Hyperf Framework	Merges two priority definitions

Sources: src/ProviderConfig.php1-169

---

Summary

The configuration merging strategies in hypervel/config provide intelligent behavior that adapts to different array structures:

• Lists (numeric keys): Accumulation with deduplication
• Associative arrays (string keys): Deep recursive merging with override precedence
• Mixed arrays: Combined behavior based on individual key types
• Special constructs: Post-processing for framework-specific objects like PriorityDefinition

This flexible approach allows the system to correctly merge diverse configuration sources—from simple value lists to deeply nested structures—while maintaining framework integration and preventing common pitfalls like duplicate entries or lost configuration values.

Sources: src/ProviderConfig.php90-168