Core Components

This section provides an overview of the core components that applications interact with directly when working with the configuration system. These components form the public API that developers use to access and manipulate configuration in their applications.

The hypervel/config package exposes three primary components for application use:

Component	File	Primary Responsibility
config() function	src/Functions.php	Global helper function for convenient configuration access
Repository	src/Repository.php	Configuration storage with read/write operations and ArrayAccess support
Type-Safe Accessors	src/Repository.php	Methods that return typed values with runtime validation

For information about internal components that handle configuration loading and merging, see page 6 (Configuration Loading System). For framework integration details, see page 8 (Framework Integration).

Sources: src/Functions.php src/Repository.php

---

Component Architecture

Application-Facing Component Relationships

The following diagram shows how the three core components relate to each other and how applications interact with them:

Sources: src/Functions.php18-31 src/Repository.php14-255

---

config() Helper Function

The config() function src/Functions.php18-31 provides a convenient global interface for accessing configuration throughout the application. It operates in three distinct modes based on the arguments provided:

Call Pattern	Return Type	Behavior
config()	Repository	Returns the entire Repository instance
config('key.name')	mixed	Retrieves a single configuration value
config('key', 'default')	mixed	Retrieves a value with fallback default
config(['key' => 'value'])	null	Sets multiple configuration values

Resolution Mechanism

The function resolves the Repository instance through the Hyperf DI container:

The function uses ApplicationContext::getContainer()->get(ConfigContract::class) src/Functions.php20 to retrieve the singleton Repository instance, ensuring consistent access to the same configuration throughout the application lifecycle.

For detailed usage patterns and examples, see page 5.1 (Configuration Function).

Sources: src/Functions.php18-31

---

Repository Class

The Repository class src/Repository.php14 is the central storage container for all configuration data in the application. It holds configuration in a protected $items array src/Repository.php26 and provides multiple interfaces for accessing and manipulating this data.

Core Capabilities

Feature	Methods	Purpose
Basic Access	get(), set(), has(), all()	Read/write configuration with dot notation
Type-Safe Access	string(), integer(), float(), boolean(), array()	Retrieve typed values with validation
Array Operations	prepend(), push()	Manipulate array configurations
Array Access	offsetGet(), offsetSet(), offsetExists(), offsetUnset()	Use Repository as array via ArrayAccess
Callbacks	afterSettingCallback()	React to configuration changes
Extensibility	Macroable trait	Add custom methods at runtime

Storage Architecture

Key Features

Dot Notation Support: The Repository uses Hyperf\Collection\Arr src/Repository.php9 to enable dot notation access to nested configuration. For example, get('database.connections.mysql.host') retrieves deeply nested values.

Array Access Implementation: The class implements ArrayAccess src/Repository.php14 allowing both method calls and array syntax:

• $repository->get('app.name') is equivalent to $repository['app.name']
• $repository->set('app.name', 'MyApp') is equivalent to $repository['app.name'] = 'MyApp'

Type Safety: Type-safe accessor methods validate return types at runtime, throwing InvalidArgumentException if the value doesn't match the expected type. This prevents type-related bugs when configuration values are accessed.

Reactive Callbacks: The afterSettingCallback() method src/Repository.php210-213 allows registering a closure that executes whenever configuration is modified via set(). This enables reactive patterns such as cache invalidation.

For detailed method documentation and usage examples, see page 5.2 (Repository Class).

Sources: src/Repository.php14-255

---

Type-Safe Configuration Access

The Repository class provides five type-safe accessor methods that return typed values with runtime validation:

Method	Return Type	Exception on Mismatch
string() src/Repository.php73-84	string	InvalidArgumentException
integer() src/Repository.php91-102	int	InvalidArgumentException
float() src/Repository.php109-120	float	InvalidArgumentException
boolean() src/Repository.php127-138	bool	InvalidArgumentException
array() src/Repository.php146-157	array	InvalidArgumentException

Type Validation Flow

Each type-safe method follows the same pattern:

1. Calls the standard get() method src/Repository.php41-48 to retrieve the value
2. Validates the type using PHP's built-in type checking functions
3. Returns the value if valid, or throws InvalidArgumentException with a descriptive message

These methods are particularly useful when strict type guarantees are required, preventing silent type coercion bugs that could occur with the standard get() method.

For detailed usage patterns and examples, see page 5.3 (Type-Safe Configuration Access).

Sources: src/Repository.php73-157

---

Usage Patterns

Common Access Patterns

The three core components work together to provide flexible configuration access:

Sources: src/Functions.php18-31 src/Repository.php41-48 src/Repository.php73-157 src/Repository.php220-254

Component Lifecycle

Sources: src/Functions.php18-31 src/Repository.php14-48

---

Summary

The core components work together in a layered architecture:

1. Discovery Layer (ProviderConfig): Discovers and merges provider-based configurations
2. Factory Layer (ConfigFactory): Aggregates all configuration sources
3. Storage Layer (Repository): Stores and provides type-safe access to configuration
4. Access Layer (config() function): Offers convenient global access
5. Integration Layer (ConfigProvider): Registers the system with Hyperf's DI container

This separation of concerns allows each component to focus on a specific responsibility while maintaining clean interfaces between layers. The static caching in ProviderConfig and lazy initialization through ConfigFactory ensure optimal performance during application runtime.