Contracts and Interfaces

The Hypervel\Config\Contracts\Repository interface defines the public API contract for the configuration system. This interface extends Hyperf\Contract\ConfigInterface, adding array manipulation methods and callback hooks while maintaining full compatibility with the Hyperf framework's dependency injection system.

The contract is implemented by the Hypervel\Config\Repository class (documented in page 5.2) and registered with the DI container through ConfigProvider (page 8).

Interface Hierarchy

The repository contract inherits from Hyperf's base configuration interface and extends it with additional capabilities for array manipulation and reactive configuration changes.

Contract Inheritance Structure

Interface Extension: The Hypervel\Config\Contracts\Repository interface declared at src/Contracts/Repository.php10 extends Hyperf\Contract\ConfigInterface, inheriting its three base methods (get(), has(), set()) and adding four additional methods for enhanced functionality.

Sources: src/Contracts/Repository.php10

Contract Method Specifications

The Repository interface declares seven methods divided into three functional categories: read operations, write operations, and array manipulation operations.

Method Overview Table

Method	Signature	Return Type	Category
has()	has(string $key): bool	bool	Read
get()	get(array|string $key, mixed $default = null): mixed	mixed	Read
all()	all(): array	array	Read
set()	set(array|string $key, mixed $value = null): void	void	Write
afterSettingCallback()	afterSettingCallback(?Closure $callback): void	void	Write
prepend()	prepend(string $key, mixed $value): void	void	Array Manipulation
push()	push(string $key, mixed $value): void	void	Array Manipulation

Sources: src/Contracts/Repository.php12-46

Read Operations

has(string $key): bool

Declared at src/Contracts/Repository.php15 this method determines whether a configuration key exists in the repository. Supports dot-notation keys like 'database.connections.mysql.host'.

Contract Requirements:

• Must accept a string key parameter
• Must return true if key exists, false otherwise
• Must support nested key access via dot notation

get(array|string $key, mixed $default = null): mixed

Declared at src/Contracts/Repository.php20 this method retrieves configuration values with optional default fallback. Unlike the base Hyperf\Contract\ConfigInterface::get() which only accepts string keys, this contract extends it to accept array keys for batch retrieval.

Contract Requirements:

• When $key is a string: return the value at that key or $default if not found
• When $key is an array: return an associative array mapping each key to its value
• Must support dot-notation for nested access (e.g., 'app.timezone')
• Must return $default for missing keys

all(): array

Declared at src/Contracts/Repository.php25 this method returns the complete configuration array as an associative array.

Contract Requirements:

• Must return all configuration data as an array
• Return value represents the full merged configuration state

Sources: src/Contracts/Repository.php15-25

Write Operations

set(array|string $key, mixed $value = null): void

Declared at src/Contracts/Repository.php30 this method modifies configuration values at runtime. Like get(), it extends the base Hyperf contract to support both single and batch updates.

Contract Requirements:

• When $key is a string: set the value at that key to $value
• When $key is an array of key-value pairs: set multiple values (ignore $value parameter)
• Must support dot-notation for nested assignment
• Must trigger any registered callbacks via afterSettingCallback()
• Returns void (no return value)

afterSettingCallback(?Closure $callback): void

Declared at src/Contracts/Repository.php35 this method registers a callback that executes after any set() operation. Used for reactive patterns like cache invalidation.

Contract Requirements:

• Accept a Closure that will be invoked after configuration changes
• When null is passed, remove any registered callback
• Callback should execute after each set() operation completes

Sources: src/Contracts/Repository.php30-35

Array Manipulation Operations

prepend(string $key, mixed $value): void

Declared at src/Contracts/Repository.php40 this method adds a value to the beginning of an array configuration value.

Contract Requirements:

• Target configuration key must point to an array
• Insert $value at the start (index 0) of the array
• Returns void

push(string $key, mixed $value): void

Declared at src/Contracts/Repository.php45 this method appends a value to the end of an array configuration value.

Contract Requirements:

• Target configuration key must point to an array
• Append $value to the end of the array
• Returns void

Sources: src/Contracts/Repository.php40-45

Contract Design Patterns

Polymorphic Key Handling

The contract demonstrates polymorphic parameter design in get() and set() methods:

Rationale: This design enables both single-item access and batch operations using the same method interface, reducing API surface area while maintaining flexibility.

Sources: src/Contracts/Repository.php20-30

Dot-Notation Key Support

All methods accepting string keys support dot notation for nested array access:

Key String	Array Structure Accessed
'app'	$config['app']
'app.name'	$config['app']['name']
'database.connections.mysql.host'	$config['database']['connections']['mysql']['host']

This convention is delegated to Hyperf\Collection\Arr utility methods in the implementation.

Sources: src/Contracts/Repository.php15-30

Dependency Injection Integration

The Repository contract serves as the type-hint interface for dependency injection throughout the application.

DI Container Registration

The contract is registered in the dependency injection container through the ConfigProvider::__invoke() method:

Binding Registration: Both Hyperf\Contract\ConfigInterface and Hypervel\Config\Contracts\Repository are mapped to the same ConfigFactory in the DI container, ensuring that either interface can be used for injection.

Sources: src/Contracts/Repository.php10

Type-Hinting the Contract

Application code can type-hint either interface for dependency injection:

Interface Type-Hint	Resolved Implementation	Use Case
Hyperf\Contract\ConfigInterface	Hypervel\Config\Repository	Framework compatibility, minimal API
Hypervel\Config\Contracts\Repository	Hypervel\Config\Repository	Full API access including array methods

Recommendation: Type-hint Hypervel\Config\Contracts\Repository when using prepend(), push(), or afterSettingCallback() methods, as these are not part of the base Hyperf contract.

Sources: src/Contracts/Repository.php10

Contract Usage Example

The contract enables decoupled configuration access:

Code Pattern	Interface Used	Method Called
Constructor injection	Repository $config	$config->get('app.name')
Method injection	Repository $config	$config->has('cache.driver')
Array operations	Repository $config	$config->push('providers', $class)
Callback registration	Repository $config	$config->afterSettingCallback($fn)

Sources: src/Contracts/Repository.php15-45

Framework Compatibility Layer

The Repository contract maintains backward compatibility with Hyperf while extending its capabilities.

Contract Extension Comparison

Method	Hyperf\Contract\ConfigInterface	Hypervel\Config\Contracts\Repository	Extension Type
has()	has(string $key): bool	has(string $key): bool	Inherited
get()	get(string $key, $default): mixed	get(array|string $key, $default): mixed	Widened parameter type
set()	set(string $key, $value): void	set(array|string $key, $value): void	Widened parameter type
all()	Not present	all(): array	New method
prepend()	Not present	prepend(string $key, $value): void	New method
push()	Not present	push(string $key, $value): void	New method
afterSettingCallback()	Not present	afterSettingCallback(?Closure $cb): void	New method

Backward Compatibility: Because the get() and set() methods widen parameter types from string to array|string, any code expecting the base Hyperf interface will work correctly with the Hypervel implementation, while new code can leverage the extended capabilities.

Sources: src/Contracts/Repository.php10-45

Interface Substitutability

Liskov Substitution Principle: The Repository implementation can be used wherever Hyperf\Contract\ConfigInterface is expected, ensuring framework compatibility. The reverse is not true—Hyperf's default config implementation cannot satisfy the Repository contract due to the additional methods.

Sources: src/Contracts/Repository.php10

Method Signature Analysis

The Repository interface demonstrates careful design in its method signatures to provide flexibility while maintaining type safety.

Flexible Key Handling

The get() and set() methods accept both string and array keys, enabling different access patterns:

• String keys: 'database.host' for dot-notation access
• Array keys: ['key1', 'key2'] for batch operations

Default Value Handling

The get() method includes optional default value support, preventing null reference errors when accessing undefined configuration keys.

Void Return Types

Mutation methods (set(), prepend(), push(), afterSettingCallback()) return void, clearly indicating their side-effect nature and preventing method chaining confusion.

Sources: src/Contracts/Repository.php14-45