Scan Configuration

Purpose and Scope

This document covers the ScanConfig class, which manages annotation scanning configuration for the Hypervel Container's aspect-oriented programming system. The ScanConfig class is responsible for loading scan-related settings from multiple configuration sources, merging them according to a defined priority, and determining whether annotation scanning results should be cached.

For information about how aspects are loaded and registered using this configuration, see Aspect Scanning. For broader context on the configuration system, see Configuration & Initialization.

---

ScanConfig Class

The ScanConfig class extends Hyperf's base ScanConfig class and provides enhanced configuration loading capabilities that integrate with the Hypervel provider system.

Class Location: src/ScanConfig.php10

class ScanConfig extends HyperfScanConfig

The class overrides the initConfigByFile method to implement a multi-source configuration loading strategy that prioritizes provider-based configuration while maintaining compatibility with file-based configuration.

Sources: src/ScanConfig.php10

---

Configuration Loading Architecture

The following diagram illustrates how ScanConfig loads and merges configuration from multiple sources:

Sources: src/ScanConfig.php12-46

---

Configuration Sources

The ScanConfig class loads configuration from multiple sources in a specific order, with later sources overriding earlier ones for conflicting values:

Source	File Path	Priority	Configuration Keys
ProviderConfig	N/A (class-based)	1 (Lowest)	annotations, dependencies
Dependencies File	{configDir}/dependencies.php	2	Service definitions
Annotations File	{configDir}/annotations.php	3	scan array
App File	{configDir}/app.php	4 (Highest)	annotations.scan, env, scan_cacheable

ProviderConfig Source

If the ProviderConfig class exists, configuration is loaded from registered service providers:

Code Reference: src/ScanConfig.php17-19

The provider configuration may include:

• annotations array containing scan configuration
• dependencies array containing service definitions

Dependencies File

The dependencies file is merged with provider-based dependencies:

Code Reference: src/ScanConfig.php21-25

Annotations File

The annotations file provides explicit scan configuration:

Code Reference: src/ScanConfig.php29-33

App File

The app configuration file provides environment-specific settings and determines cacheability:

Code Reference: src/ScanConfig.php36-43

Sources: src/ScanConfig.php12-46

---

Configuration Merge Strategy

The allocateConfigValue method implements the merge strategy for scan configuration:

Merge Behavior

The allocateConfigValue method src/ScanConfig.php48-65 exhibits the following behavior:

1. Structure Validation: Only processes configuration if content['scan'] exists
2. Key Initialization: Creates empty arrays for new configuration keys
3. Value Normalization: Converts non-array values to single-element arrays
4. Array Merging: Uses array_merge to combine values, allowing duplicates and preserving order

Configuration Structure

Scan configuration follows this structure:

Each key within the scan array is merged independently, allowing fine-grained control over which paths, annotations, or mappings to include.

Sources: src/ScanConfig.php48-65

---

Cacheability Determination

The ScanConfig class determines whether annotation scanning results should be cached based on the application environment:

Cacheability Logic

Code Reference: src/ScanConfig.php36-43

Condition	Cacheable Result
scan_cacheable explicitly set to true	true
scan_cacheable explicitly set to false	false
scan_cacheable not set, env is 'production'	true
scan_cacheable not set, env is not 'production'	false
app.php does not exist	false (default)

Default Behavior

The default value for $cacheable is false src/ScanConfig.php16 ensuring that scanning always occurs in development environments unless explicitly configured otherwise.

Return Value

The initConfigByFile method returns a three-element array:

Code Reference: src/ScanConfig.php45

Index	Name	Type	Description
0	$config	array	Merged scan configuration
1	$serverDependencies	array	Service definitions from all sources
2	$cacheable	bool	Whether scan results should be cached

Sources: src/ScanConfig.php36-45

---

Integration with Scanner

The ScanConfig class provides configuration that the Scanner class uses during aspect loading. The following diagram shows the data flow between these components:

The Scanner uses the returned configuration to:

• Determine which paths to scan for aspects
• Identify annotations to process or ignore
• Cache scan results when appropriate

For details on how the Scanner uses this configuration, see Aspect Scanning.

Sources: src/ScanConfig.php12-46

---

Method Reference

initConfigByFile

Purpose: Loads and merges scan configuration from multiple sources.

Parameters:

• $configDir (string): Base directory for configuration files

Returns: Array with three elements: [$config, $serverDependencies, $cacheable]

Code Reference: src/ScanConfig.php12-46

---

allocateConfigValue

Purpose: Merges scan configuration from a source into the accumulated configuration.

Parameters:

• $content (array): Configuration array containing a scan key
• $config (array): Accumulated configuration to merge into

Returns: Merged configuration array

Behavior:

• Returns $config unchanged if $content['scan'] does not exist
• Initializes missing keys in $config as empty arrays
• Normalizes non-array values to single-element arrays
• Merges values using array_merge

Code Reference: src/ScanConfig.php48-65

---

Configuration Priority Example

The following table demonstrates how configuration values are merged across sources:

Config Key	Provider	annotations.php	app.php	Final Result
paths	['app']	['plugin']	['custom']	['app', 'plugin', 'custom']
ignore_annotations	['deprecated']	['internal']	-	['deprecated', 'internal']
class_map	-	['A' => 'path1']	['B' => 'path2']	['A' => 'path1', 'B' => 'path2']

Each source adds to the configuration without removing values from earlier sources, resulting in an accumulative merge strategy.

Sources: src/ScanConfig.php48-65