Configuration Function

Purpose and Scope

This document provides detailed documentation of the global config() helper function, which serves as the primary entry point for accessing configuration in Hypervel applications. The function provides a convenient, globally-accessible interface for both reading and writing configuration values.

For detailed information about the underlying Repository class that config() returns, see Repository Class. For information about type-safe configuration access methods, see Type-Safe Configuration Access.

Function Definition

The config() function is defined as a global helper function in the Hypervel\Config namespace. It is located in src/Functions.php18-31 and provides a simplified interface to the configuration system.

Function Signature:

function config(mixed $key = null, mixed $default = null): mixed

The function accepts two optional parameters:

• $key - Can be null, a string configuration key, or an array of key-value pairs
• $default - Default value to return if the requested key does not exist (only applicable when $key is a string)

Sources: src/Functions.php1-32

Resolution Mechanism

The config() function resolves the configuration Repository instance from the dependency injection container using Hyperf's ApplicationContext. This ensures that all calls to config() access the same singleton Repository instance throughout the application lifecycle.

Resolution Steps:

1. The function calls ApplicationContext::getContainer() to obtain the DI container instance src/Functions.php20
2. It requests the ConfigContract::class (which is Hypervel\Config\Contracts\Repository) from the container src/Functions.php20
3. The container returns the singleton Repository instance that was registered during application bootstrap
4. The function then delegates the operation to the Repository

Sources: src/Functions.php20

Calling Patterns

The config() function supports three distinct calling patterns, each serving a different purpose. The behavior is determined by the type and presence of the $key parameter.

Pattern 1: No Arguments - Return Repository Instance

When called without any arguments, config() returns the Repository instance itself. This pattern is useful when you need direct access to Repository methods that are not exposed through the helper function.

Implementation:

Use Cases:

• Accessing Repository-specific methods like has(), string(), integer(), etc.
• Passing the Repository to other components
• Chaining multiple operations on the Repository

Example Usage Pattern:

Sources: src/Functions.php22-24

Pattern 2: Array Argument - Set Multiple Values

When passed an array as the $key parameter, the function treats it as a batch set operation. Each key-value pair in the array is set in the configuration store.

Implementation:

Behavior:

• Accepts an associative array where keys are configuration paths (using dot notation)
• Delegates to Repository::set() which handles the actual storage
• Returns null after setting the values src/Functions.php27
• Each key can use dot notation to set nested values (e.g., 'database.host')

Example Usage Pattern:

Sources: src/Functions.php26-28

Pattern 3: String Argument - Get Single Value

When passed a string as the $key parameter, the function retrieves a single configuration value. If the key does not exist, it returns the $default value.

Implementation:

Behavior:

• Accepts a string key using dot notation for nested values
• Returns the configuration value if it exists
• Returns $default if the key does not exist src/Functions.php30
• Delegates to Repository::get() for actual retrieval logic

Example Usage Pattern:

Sources: src/Functions.php30

Return Type Behavior

The config() function exhibits polymorphic return type behavior based on its input parameters. This is documented in the function's PHPDoc type annotation:

Input Pattern	Return Type	Description
config()	Repository	Returns the Repository instance
config(['key' => 'value'])	null	Returns null after setting values
config('key') or config('key', $default)	mixed	Returns the configuration value or default

PHPDoc Type Annotation:

This conditional return type annotation src/Functions.php16 uses PHPStan/Psalm syntax to express:

• If $key is null, return Repository
• If $key is a string, return mixed (the value)
• Otherwise (array case), return null

Sources: src/Functions.php16

Dependency on ApplicationContext

The config() function relies on Hyperf's ApplicationContext to resolve the Repository instance from the dependency injection container. This creates a dependency on the framework's context initialization.

Key Dependencies:

Component	Type	Purpose
ApplicationContext	Class	Provides access to the DI container
ConfigContract	Interface	Type used to resolve Repository from container
DI Container	Service	Manages singleton Repository instance

Implications:

• The config() function cannot be used before the application context is initialized
• The function always returns the same Repository instance (singleton behavior)
• The function inherits the thread-safety characteristics of ApplicationContext

Sources: src/Functions.php7-20

Function Import and Usage

The config() function is defined in the Hypervel\Config namespace but is intended to be used as a global function. To use it in your application code, you need to import it with a use function statement.

Import Statement:

Alternative Global Access:

Common Usage Patterns:

Pattern	Code Example
Get value	$name = config('app.name');
Get with default	$timeout = config('timeout', 30);
Set multiple	config(['key1' => 'val1', 'key2' => 'val2']);
Get Repository	$repo = config();

Sources: src/Functions.php5

Comparison with Direct Repository Access

The config() helper function provides a more convenient interface compared to directly injecting and using the Repository class. Here is a comparison:

Aspect	config() Function	Direct Repository Injection
Syntax	config('app.name')	$this->config->get('app.name')
Setup	use function import	Constructor injection or property
Access Pattern	Global function call	Method call on instance
Testability	Harder to mock (global)	Easier to mock (injected dependency)
Use Case	Quick access, scripting	Long-lived services, unit tests

When to Use config():

• In controllers, commands, or event listeners for quick configuration access
• In procedural code or helper functions
• When you need a single configuration value

When to Inject Repository:

• In services with extensive configuration usage
• When writing unit tests (easier to mock)
• When you need multiple configuration operations
• For better testability and dependency management

For more information about the Repository class and dependency injection patterns, see Repository Class.

Sources: src/Functions.php1-32

Code Entity Reference

The following table maps the natural language concepts discussed in this document to specific code entities in the codebase:

Concept	Code Entity	File Location
Configuration function	config()	src/Functions.php18
Function namespace	Hypervel\Config	src/Functions.php5
Repository resolution	ApplicationContext::getContainer()->get(ConfigContract::class)	src/Functions.php20
Repository contract	Hypervel\Config\Contracts\Repository	src/Functions.php8
Application context	Hyperf\Context\ApplicationContext	src/Functions.php7
Null check (return Repository)	is_null($key)	src/Functions.php22
Array check (set values)	is_array($key)	src/Functions.php26
String case (get value)	$config->get($key, $default)	src/Functions.php30
Set operation	$config->set($key)	src/Functions.php27

Sources: src/Functions.php1-32