Installation and Setup

Requirements

The package requires:

• PHP 8.2 or higher
• Hyperf framework ~3.1.0

Sources: composer.json31-34

---

Installation via Composer

Install the package using Composer:

The package is automatically discovered by the Hyperf framework through the extra.hyperf.config entry in composer.json39-42 which registers Hypervel\Config\ConfigProvider for automatic discovery by the Hyperf dependency injection container.

Sources: composer.json39-42

---

Automatic Registration

During installation, Composer triggers three parallel registration mechanisms:

1. PSR-4 Class Autoloading

The autoload.psr-4 section maps the Hypervel\Config\ namespace to the src/ directory, enabling automatic class loading for all configuration system components:

Class	File Path	Purpose
ConfigProvider	src/ConfigProvider.php	DI container registration
ConfigFactory	src/ConfigFactory.php	Configuration repository creation
ProviderConfig	src/ProviderConfig.php	Provider discovery and merging
Repository	src/Repository.php	Configuration storage and access
Contracts\Repository	src/Contracts/Repository.php	Repository interface contract

Sources: composer.json23-26

2. Global Function Registration

The autoload.files section loads src/Functions.php, which defines the global config() helper function. This function becomes immediately available throughout the application without requiring any imports.

Sources: composer.json27-29

3. Hyperf Provider Discovery

The extra.hyperf.config entry registers Hypervel\Config\ConfigProvider with Hyperf's provider discovery system. During bootstrap, Hyperf:

1. Discovers ConfigProvider from composer.json
2. Invokes ConfigProvider::__invoke()
3. Registers ConfigFactory as the implementation for Hyperf\Contract\ConfigInterface

Sources: composer.json39-42

Registration Flow Diagram

Registration Flow from composer.json

This diagram maps the three registration mechanisms from specific lines in composer.json to their runtime effects, showing how installation prepares the configuration system for use.

Sources: composer.json23-42

---

Configuration Directory Setup

After installation, create the standard Hyperf configuration directory structure in your application root:

Standard Directory Structure

your-application/
├── config/
│ ├── hyperf.php # Root configuration file (loaded by ConfigFactory)
│ └── autoload/ # Auto-discovered configuration files
│ ├── dependencies.php # Dependency injection bindings
│ ├── middlewares.php # Middleware configurations
│ ├── annotations.php # Annotation scan paths
│ └── *.php # Additional configuration files
├── composer.json
└── ...

Configuration File Requirements

Each configuration file must return a PHP array:

File Discovery Mechanism

The configuration system discovers files through two entry points:

Entry Point	Discovery Method	File Reference
config/hyperf.php	Direct read	ConfigFactory::readConfig()
config/autoload/*.php	Symfony Finder scan	ConfigFactory::readPaths()

Files in config/autoload/ are automatically discovered using Symfony\Component\Finder\Finder and merged into the configuration. The filename (without .php extension) becomes the top-level configuration key.

Sources: Referenced in system architecture diagrams

Directory Permissions

Ensure the config/ directory is readable by the PHP process:

Sources: Standard Hyperf configuration practices

---

Verification

After installation and setup, verify the configuration system is working correctly:

1. Verify Function Availability

Create a test PHP file to confirm the config() function is available:

Sources: composer.json27-29

2. Verify Class Autoloading

Test that configuration classes are autoloadable:

Sources: composer.json23-26

3. Verify Hyperf Integration

In a Hyperf application, verify the configuration system is registered with the DI container:

Run the command to verify:

Sources: composer.json39-42

Verification Checklist

Component	Verification Method	Expected Result
PSR-4 Autoloading	class_exists('Hypervel\Config\Repository')	Returns true
Global Function	function_exists('config')	Returns true
DI Registration	Inject ConfigInterface in constructor	Receives Repository instance
File Discovery	Place config in config/autoload/	Automatically loaded by ConfigFactory

Sources: composer.json23-42

---

Next Steps

After installation and basic configuration access, you may want to explore:

• Configuration Function: Detailed documentation of the config() helper and its integration with ApplicationContext
• Repository Class: Comprehensive guide to Repository methods, including array manipulation and the Macroable trait
• Type-Safe Configuration Access: Type-safe getter methods with runtime validation
• Configuration Loading System: Understanding how configurations are discovered, merged, and loaded
• Custom Configuration Providers: Creating custom ServiceProviders and invokable configuration classes

Sources: Referenced from table of contents structure