Configuration Loading & Merging

Purpose and Scope

This document explains how the Hypervel Container loads and merges configuration data from multiple sources during system initialization. The configuration system supports both service dependency definitions and annotation scanning configurations, each with distinct loading priorities and merge strategies.

This page focuses specifically on the mechanics of loading and merging configuration data. For information about the structure and purpose of configuration sources, see Definition Sources. For information about how aspects are loaded using these configurations, see Aspect Scanning.

---

Configuration Sources Overview

The Hypervel Container loads configuration from multiple locations with defined priorities. The following table summarizes all configuration sources:

Configuration Type	Source	Priority	File Path	Merge Strategy
Dependencies	Provider Config	1 (lowest)	N/A (class-based)	array_replace
Dependencies	Autoload Config	2	config/autoload/dependencies.php	array_replace
Dependencies	Explicit Config	3 (highest)	config/dependencies.php	array_replace
Scan Paths	Provider Annotations	1 (lowest)	N/A (class-based)	array_merge
Scan Paths	Annotations File	2	config/annotations.php	array_merge
Scan Paths	Application Config	3 (highest)	config/app.php	array_merge

Key Principle: Later sources override earlier sources for dependencies, but accumulate for scan paths.

Sources: src/DefinitionSourceFactory.php1-40 src/ScanConfig.php1-67

---

Dependency Configuration Loading

The DefinitionSourceFactory class orchestrates the loading and merging of service dependency definitions. This process occurs once during container initialization and produces a DefinitionSource object that feeds the container.

Loading Sequence

Diagram: Dependency Configuration Loading Flow in DefinitionSourceFactory

Sources: src/DefinitionSourceFactory.php12-38

Code Entity Mapping

The following diagram maps natural language concepts to actual code entities:

Diagram: Code Entity Relationships in Dependency Loading

Sources: src/DefinitionSourceFactory.php12-38

Implementation Details

The DefinitionSourceFactory::__invoke() method implements the loading sequence:

1. BASE_PATH Validation src/DefinitionSourceFactory.php14-16: Ensures the application base path is defined before attempting file operations.

2. Provider Config Loading src/DefinitionSourceFactory.php18-23: If ProviderConfig class exists, loads configuration and extracts the dependencies key.

3. Autoload Config Loading src/DefinitionSourceFactory.php26-34: Iterates through two file paths in order:

   • config/autoload/dependencies.php
   • config/dependencies.php

4. Merge Strategy src/DefinitionSourceFactory.php33: Uses array_replace() to merge configurations, ensuring later sources override earlier sources for the same keys.

5. DefinitionSource Creation src/DefinitionSourceFactory.php37: Creates and returns a DefinitionSource instance with the final merged configuration.

Sources: src/DefinitionSourceFactory.php12-38

---

Scan Configuration Loading

The ScanConfig class handles loading and merging of annotation scanning configurations. Unlike dependency configurations, scan configurations accumulate paths from all sources rather than overriding them.

Loading Sequence

Diagram: Scan Configuration Loading Flow in ScanConfig

Sources: src/ScanConfig.php12-46

Code Entity Mapping

Diagram: Code Entity Relationships in Scan Configuration Loading

Sources: src/ScanConfig.php12-46

Implementation Details

The ScanConfig::initConfigByFile() method src/ScanConfig.php12-46 implements a more complex loading sequence than dependency configuration:

1. Provider Annotations Loading src/ScanConfig.php17-27: Loads provider config and extracts the annotations key, then allocates values into the config array.

2. Dependencies Loading src/ScanConfig.php21-25: Loads service dependencies using the same strategy as DefinitionSourceFactory.

3. Annotations File Loading src/ScanConfig.php29-33: Loads config/annotations.php if it exists and merges scan paths.

4. Application Config Loading src/ScanConfig.php35-43: Loads config/app.php for:

   • Environment determination (env key)
   • Cacheability flag (scan_cacheable key or production environment)
   • Additional annotation configurations

5. Return Tuple src/ScanConfig.php45: Returns a three-element array containing the merged scan config, dependencies, and cacheability flag.

Sources: src/ScanConfig.php12-46

Configuration Allocation Logic

The allocateConfigValue() method src/ScanConfig.php48-65 implements the merge logic for scan configurations:

Step	Action	Code Reference
1	Check for scan key in content	src/ScanConfig.php50-52
2	Iterate over scan key-value pairs	src/ScanConfig.php54
3	Initialize config key if not exists	src/ScanConfig.php55-57
4	Normalize value to array	src/ScanConfig.php58-60
5	Merge with array_merge()	src/ScanConfig.php61

This approach ensures that all scan paths from all sources are preserved and accumulated, unlike dependency configurations which override.

Sources: src/ScanConfig.php48-65

---

Merge Strategy Comparison

The two configuration systems use different merge strategies for different purposes:

Dependencies: array_replace()

Purpose: Allow later configuration sources to completely override earlier bindings for the same service.

Behavior: If key exists in both arrays, the value from the second array replaces the value from the first.

Example:

Code Location: src/DefinitionSourceFactory.php33

Scan Paths: array_merge()

Purpose: Accumulate scan paths from all sources so the scanner processes all directories.

Behavior: Values from both arrays are combined into a single array.

Example:

Code Location: src/ScanConfig.php61

Sources: src/DefinitionSourceFactory.php33 src/ScanConfig.php61

---

Complete Initialization Sequence

The following sequence diagram shows how both configuration systems work together during application bootstrap:

Diagram: Complete Configuration Loading and Merging Sequence

Sources: src/DefinitionSourceFactory.php12-38 src/ScanConfig.php12-46

---

Configuration Priority Summary

Dependency Configuration Priority

Priority	Source	Override Behavior
Lowest	ProviderConfig::load()['dependencies']	Provides default bindings from packages
Medium	config/autoload/dependencies.php	Overrides provider defaults
Highest	config/dependencies.php	Final override for all bindings

Scan Configuration Priority

Priority	Source	Accumulation Behavior
Lowest	ProviderConfig::load()['annotations']['scan']	Initial scan paths from packages
Medium	config/annotations.php['scan']	Additional paths added to list
Highest	config/app.php['annotations']['scan']	Final paths added to complete list

Key Difference: Dependencies use replacement semantics (winner takes all), while scan paths use accumulation semantics (everyone wins).

Sources: src/DefinitionSourceFactory.php23-34 src/ScanConfig.php27-42

---

Environment-Specific Behavior

The scan configuration system includes special handling for environment-based cacheability:

Configuration	Default	Override Mechanism	Code Reference
scan_cacheable	false	Set in config/app.php	src/ScanConfig.php39
Environment detection	'dev'	Read from config/app.php['env']	src/ScanConfig.php38
Cacheability logic	scan_cacheable or env === 'production'	Evaluated as boolean	src/ScanConfig.php39

Cacheability Determination: The system automatically enables caching in production environments unless explicitly disabled, but requires explicit enablement in development environments.

Sources: src/ScanConfig.php36-42