Configuration and Framework Integration

This document explains how the hypervel/encryption library integrates with both Hyperf and Hypervel frameworks. It covers the ConfigProvider class, configuration resolution logic, configuration precedence rules, environment variable integration, and the differences between framework-specific configuration approaches.

For information about the core encryption factory implementation, see page 4.3. For details about key generation commands, see page 5.1. For initial setup procedures, see page 3.

ConfigProvider Overview

The ConfigProvider class serves as the primary integration point between the encryption library and the Hyperf framework. It implements the standard Hyperf configuration provider pattern, returning an array that defines dependencies, commands, and publishable assets.

ConfigProvider Structure

Sources: src/ConfigProvider.php10-31

Dependency Registration

The ConfigProvider registers the Encrypter contract with the dependency injection container by mapping it to the EncryptionFactory class. This enables automatic injection of encryption services throughout the application.

Contract	Implementation	Purpose
Encrypter::class	EncryptionFactory::class	Maps encryption interface to factory

The dependency mapping occurs in the dependencies array:

This configuration tells Hyperf's container to instantiate EncryptionFactory whenever Encrypter is requested, enabling the factory pattern for encryption service creation.

Sources: src/ConfigProvider.php15-17

Command Registration

The library registers the KeyGenerateCommand with Hyperf's command system, making the key:generate CLI command available to applications.

The command registration occurs in the commands array:

Sources: src/ConfigProvider.php18-20

Configuration Publishing

The ConfigProvider defines a publishable configuration file that can be copied to the application's configuration directory using Hyperf's vendor publishing system.

Publication Configuration

Property	Value	Purpose
id	'config'	Unique identifier for publication
description	'The configuration file of encryption.'	Human-readable description
source	__DIR__ . '/../publish/encryption.php'	Source template path
destination	BASE_PATH . '/config/autoload/encryption.php'	Target configuration path

The publication definition enables developers to run:

Sources: src/ConfigProvider.php21-28

Configuration File Structure

The published configuration file encryption.php provides a template for encryption settings with backward compatibility considerations for Hyperf framework usage.

Configuration Schema

Configuration Options

Option	Type	Default	Description
cipher	string	'AES-256-CBC'	Encryption cipher algorithm
key	string	env('APP_KEY')	Primary encryption key from environment
previous_keys	array	Parsed from APP_PREVIOUS_KEYS	Previous keys for rotation support

Sources: publish/encryption.php11-21

Environment Variable Integration

The configuration system integrates with environment variables to provide secure key management and flexible deployment configuration.

Environment Variables

• APP_KEY: The primary encryption key used for all encryption operations
• APP_PREVIOUS_KEYS: Comma-separated list of previous encryption keys for backward compatibility

Previous Keys Processing

The configuration processes the APP_PREVIOUS_KEYS environment variable by splitting on commas and filtering empty values:

This allows multiple previous keys to be specified as: APP_PREVIOUS_KEYS=key1,key2,key3

Sources: publish/encryption.php16-20

Configuration Resolution and Precedence

The EncryptionFactory implements a configuration resolution strategy that supports both Hyperf and Hypervel framework conventions through a fallback mechanism.

Resolution Logic

The precedence rules are:

Priority	Namespace	Condition	Framework
1 (Highest)	app.cipher + app.key	Both keys must exist	Hypervel
2 (Fallback)	encryption.*	Used if app config incomplete	Hyperf

Implementation

The configuration resolution occurs in EncryptionFactory::__invoke():

This logic checks for the presence of both app.cipher and app.key. If both exist, the factory uses the app configuration namespace (Hypervel convention). Otherwise, it falls back to the encryption configuration namespace (Hyperf convention).

Sources: src/EncryptionFactory.php19-23

Configuration Keys Used

The factory expects the following keys in the resolved configuration array:

Key	Type	Required	Description
key	string	Yes	Primary encryption key (validated non-empty)
cipher	string	Yes	Cipher algorithm identifier
previous_keys	array	No	Array of previous keys for rotation

Sources: src/EncryptionFactory.php25-31

Framework-Specific Configuration Approaches

The encryption library supports two different configuration approaches depending on the framework in use.

Hyperf Framework Approach

For Hyperf applications, encryption configuration is maintained in a dedicated config/autoload/encryption.php file. This file is published from the package template and uses the encryption namespace.

Configuration File Location: config/autoload/encryption.php

Configuration Structure:

Namespace Access: config->get('encryption')

The published template includes a backward compatibility notice:

Sources: publish/encryption.php1-21

Hypervel Framework Approach

For Hypervel applications, encryption configuration is integrated into the main application configuration file, typically config/app.php. This centralizes security-related configuration.

Configuration File Location: config/app.php

Configuration Structure:

Namespace Access: config->get('app')

Comparison Table

Aspect	Hyperf Approach	Hypervel Approach
Config File	config/autoload/encryption.php	config/app.php
Namespace	encryption	app
Publishing	Required via vendor:publish	Integrated in skeleton
Precedence	Fallback (priority 2)	Primary (priority 1)
Use Case	Standalone Hyperf applications	Hypervel framework applications

Sources: publish/encryption.php7-10 src/EncryptionFactory.php20-23

Migration Path

Applications migrating from Hyperf to Hypervel can retain their encryption.php configuration file during transition. The precedence logic ensures that once app.cipher and app.key are defined, the app namespace takes priority automatically.

Integration Flow

Sources: src/ConfigProvider.php10-31 publish/encryption.php11-21